# 从概念到落地——智能体全景图

## 一个工程场景

假设你正在维护一个技术知识库，需要让 AI 帮你处理文档。你会遇到两种截然不同的需求：

第一种："把这篇文章总结一下。" —— 输入文档，得到摘要，结束。

第二种："帮我维护知识库，让它能持续反映项目的真实状态。" —— 这意味着：需要定期检查新文档，识别过时内容，更新关联链接，重新组织目录结构，处理格式冲突，在不确定时标记需要人工确认的条目。

第一种是传统的 LLM 应用：单次输入，单次输出，无状态。第二种才是 Agent：有持续目标，需要在环境中行动，接收反馈，并根据反馈调整下一步。

Agent 不是"更长的 Prompt"，而是从 LLM 调用到可行动系统的转变。

## 什么是 Agent

普通 LLM 应用的核心形态是：输入一段上下文，模型生成一次输出。即使它有聊天历史，本质上仍然是一次次无状态推理的拼接。

Agent 的关键变化在于：模型不只是回答问题，而是在目标约束下持续观察、决策、行动、接收反馈，并根据反馈调整下一步。

可以把 Agent 看成一个闭环系统：

```text
目标
  -> 观察环境
  -> 选择行动
  -> 调用工具或生成结果
  -> 读取反馈
  -> 修正计划
  -> 继续执行或停止
```

这里最重要的不是"模型会不会调用工具"，而是系统是否允许它在反馈中调整行为。

### 判断一个系统是不是 Agent 的四个条件

#### 有目标，而不只是有问题

"总结这篇文章"是一次任务；"帮我维护一个知识库，使它能持续反映项目真实状态"才更像 Agent 目标。

目标会带来持续性，也会带来验收标准。没有目标，系统无法判断什么时候继续、什么时候停止。

举个代码审查 Agent 的例子：它的目标不是"找出所有问题"（这是无限任务），而是"确保每次变更不引入已知的危险模式，并在不确定时标记给人审"。这里有明确的边界和停止条件。

#### 有行动能力

Agent 必须能改变某些外部状态，例如写文件、查数据库、调用 API、发消息、操作浏览器、创建任务、触发部署。

行动能力越强，越需要边界。一个只能生成文本的助手主要面对质量问题；一个能修改生产系统的 Agent 还会面对权限、审计、回滚和安全问题。

举例：一个部署 Agent 可以创建 PR、触发 CI、监控构建状态、在失败时回滚、在成功时合并。每一步都是不可逆的状态改变，需要设计权限和确认机制。

#### 有反馈回路

没有反馈，Agent 只是一次性自动化。反馈可以来自工具返回、测试结果、用户确认、监控指标、环境状态或其他智能体的审查。

反馈回路让 Agent 能自我修正，但也可能让系统陷入循环。所以反馈必须配合停止条件、预算限制和错误分类。

举例：一个调试 Agent 运行测试后看到失败（反馈），它可能选择修改代码、添加日志、检查依赖或询问用户。如果连续三次修改后测试仍然失败，它应该停止并请求人工介入，而不是无限循环。

#### 有状态

状态包括当前计划、已完成步骤、失败记录、用户偏好、环境约束、长期记忆和任务产物。没有状态，Agent 就无法跨步骤保持一致。

状态不一定都放进上下文。工程上通常分成：

- 短期上下文：当前任务需要立即使用的信息。
- 工作记忆：本轮执行中的计划、证据、错误和决策。
- 长期记忆：跨会话复用的偏好、项目知识和历史结论。
- 外部事实库：文档、数据库、代码仓库、搜索结果。

举例：一个重构 Agent 需要记住：当前重构的目标范围、已修改的文件列表、遇到的兼容性问题、用户对某些模式的偏好（如"不要改变变量命名"）。这些状态如果丢失，每次操作都可能重复之前的错误或破坏一致性。

## Agent 设计的核心张力

Agent 的价值来自自主性，但风险也来自自主性。设计时要一直平衡三组张力。

### 自主性 vs 可控性

自主性太弱，系统只是脚本；自主性太强，系统可能越权行动。

场景：一个生产环境运维 Agent，如果完全自主，可能在故障时自动重启服务、修改配置、回滚版本。但如果配置错误，它可能把错误配置扩散到所有实例。因此需要分级：观察和诊断可以自主，修改配置需要确认，回滚操作需要双因素确认。

建议：为每个动作设置自主性等级：
- Level 1：完全自主（如读取日志、生成报告）
- Level 2：带预算的自主（如最多重试 3 次）
- Level 3：需要确认（如修改配置）
- Level 4：需要审批（如删除数据）

### 通用性 vs 可验证性

通用工具让 Agent 能做更多事，但行为更难审计；专用工具让系统更可靠，但开发成本更高。

场景：一个代码生成 Agent 可以使用通用"执行命令"工具，也可以使用专用"创建测试文件"工具。通用工具灵活但难以预测（可能执行 rm -rf），专用工具受限但行为明确（只能写测试目录）。

建议：
- 高风险操作（如删除、部署、发消息）必须专用化
- 低风险操作（如查询、格式化）可以通用
- 工具参数必须强类型和结构化，避免自由文本参数

### 探索能力 vs 成本边界

开放式探索能发现新路径，但容易消耗 Token、时间和外部资源。

场景：一个调试 Agent 可以尝试多种修复方案，但每次尝试都包括代码修改、运行测试、等待结果。如果它无限制地探索，可能在数小时内消耗大量 API 调用和计算资源，却仍未找到根本原因。

建议：
- 设置最大迭代次数（如"最多 5 次修复尝试"）
- 设置时间预算（如"单个问题不超过 10 分钟"）
- 设置成本预算（如"单次任务不超过 $1 API 成本"）
- 设计"放弃并升级"的路径，何时停止探索并请求人工介入

## 从 Demo 到系统：落地检查清单

很多 Agent 项目停留在 Demo 阶段，不是因为模型不够聪明，而是因为缺少工程化设计。以下是一个从想法到可上线 Agent 的检查清单。

### 1. 目标与边界

没有清晰目标，Agent 会变成无限循环的"尝试机器"；没有明确边界，它会越权操作。

需要明确：Agent 要完成什么具体目标？成功标准是什么？它明确不做什么？用户输入不完整时，是追问、假设还是拒绝？任务何时结束？

一个常见错误是把"帮我优化代码"当作目标——这是无限任务。更好的做法是"找出并修复代码中的性能瓶颈，每次只处理一个函数"。

### 2. 自主性等级

自主性决定了风险等级和所需的安全机制，高风险动作必须有更强约束。

需要问：它只是给建议还是会执行？能改写哪些外部状态？哪些动作必须人工确认？哪些允许自动重试？哪些必须禁止？

一个典型错误是一开始就给 Agent 生产环境写权限，导致它在调试时修改了关键配置。

### 3. 工作流结构

复杂任务需要分解，但分解方式影响效率和可靠性——线性执行太慢，完全并行又容易冲突。

考虑：是否需要提示链（先分析再生成最后验证）？是否需要任务路由？是否有可并行子任务？是否需要先规划再执行？中间产物是否可检查？

常见问题是让 Agent 串行处理可并行的任务（浪费时间），或并行处理有依赖的任务（导致结果不一致）。

### 4. 工具设计

工具是 Agent 与现实交互的唯一接口，设计不当会让 Agent 的能力无法正确使用。

检查：工具参数是否结构化？失败是否有明确错误码？调用是否有日志？高风险动作是否专用化？是否避免把不可逆操作藏在通用工具里？

一个典型错误是提供"执行任意 shell 命令"工具，然后惊讶于 Agent 执行了危险操作。更好的做法是提供"创建文件"、"读取文件"、"运行测试"等专用工具。

### 5. 知识与上下文

Agent 需要知识才能做出正确决策，但上下文有限且成本高。不合理的知识管理会导致信息不足或成本失控。

考虑：需要哪些外部知识源？RAG 是否有召回、排序、压缩和引用？哪些内容进入短期上下文？哪些进入长期记忆？记忆是否标注来源、时间和可信度？

常见问题是把整个代码库放进上下文（浪费 Token、分散注意力），或完全不给上下文（让 Agent 盲目猜测）。

### 6. 多智能体协作

多 Agent 可以分工，但也会引入协调开销和冲突风险——不是所有任务都需要多 Agent。

问清楚：为什么需要多个 Agent？每个 Agent 的责任边界是什么？谁拥有最终决策权？写入范围是否冲突？子 Agent 输出是否有统一格式？

别为了"看起来智能"而拆分多个 Agent，职责重叠会导致决策冲突和反复修改。

### 7. 安全与护栏

Agent 的行动能力意味着它可能造成真实损害，安全不是可选项。

需要考虑：输入是否需要风险分类？工具权限是否最小化？是否有提示注入防护？是否有敏感信息泄露检查？是否有人工升级路径？

别相信"模型足够聪明，不会做危险事"——模型可能被恶意输入诱导执行有害操作。

### 8. 异常恢复

现实世界充满失败，不能恢复的 Agent 在第一次错误后就变得不可用。

需要设计：工具失败如何重试？计划失败如何重规划？验证失败如何回滚？外部依赖不可用时如何降级？用户目标变化时如何更新状态？

一个常见错误是对所有失败都无脑重试，导致把错误参数重复发送到 API，最终被限流或封禁。

### 9. 评估与监控

无法衡量的系统无法改进——离线评估保证上线质量，在线监控发现问题。

需要：离线评估集覆盖哪些任务（正常、边界、对抗场景）？有没有对抗样本和回归样本？上线后监控哪些指标（成功率、延迟、成本、人工介入率）？失败案例如何沉淀为测试？成本和延迟是否可观测？

只在几个完美案例上测试，上线后可能会发现真实场景的失败率高达 50%。

### 10. 最小可行版本

完整的 Agent 系统很复杂，先做 MVP 可以快速验证价值，再逐步增强能力。

一个可靠的 MVP Agent 至少应该具备：明确目标、有限工具、可见计划、关键动作确认、可运行验证、失败日志、人工接管路径。

先做一个窄而可靠的 Agent，比做一个宽而不可控的 Agent 更有价值。Agent 能力应该随着边界、验证和治理一起扩张，而不是先把权限全部打开。

一开始就追求"全能 Agent"往往结果是样样都能做但样样都做不好，且难以调试和维护。

## 最小可行 Agent

什么是一个窄而可靠的 MVP Agent 应该具备的要素？

### 明确的目标和边界

```python
# 目标太模糊
goal = "优化代码"

# 更清晰的目标
goal = {
    "what": "找出代码中的性能瓶颈",
    "scope": "当前函数，不涉及依赖",
    "success": "找到瓶颈并提供优化建议",
    "stop": "分析超过 3 个函数后停止"
}
```

### 有限且专用的工具

```python
# 工具太危险且难以审计
tools = ["execute_any_command"]

# 更安全的工具设计
tools = [
    "read_file",           # 读取代码
    "analyze_performance", # 分析性能（专用）
    "suggest_refactor",    # 建议重构（不直接修改）
    "create_report"        # 生成报告
]
```

### 可见的执行计划

```python
# 执行前先展示计划
plan = agent.create_plan(task)
if not user.confirm(plan):
    return

# 按计划执行，每步报告进度
for step in plan:
    result = agent.execute(step)
    agent.log_result(result)
```

### 关键动作确认

```python
# 高风险动作必须确认
if action.risk_level == "high":
    if not user.confirm(action):
        return "Action cancelled by user"
```

### 失败恢复机制

```python
# 不同类型的失败，不同的处理策略
if error.type == "transient":
    return retry(action, max_times=3)
elif error.type == "validation":
    return rollback_and_report(error)
elif error.type == "unknown":
    return escalate_to_human(error)
```

### 可观测性

```python
# 记录所有关键事件
logger.log({
    "task": task.id,
    "action": action.name,
    "result": result.status,
    "cost": result.tokens_used,
    "duration": result.time_elapsed
})
```

## 结语

Agent 的本质不是模型，而是一个围绕模型构建的行动系统。

设计 Agent 时，最危险的想法是"让模型更聪明就能解决问题"。实际上，大部分 Agent 项目失败的原因不是模型不够强，而是缺少清晰的目标、合理的边界、可靠的反馈和完善的恢复机制。

一个窄而可靠的 Agent，比一个宽而不可控的 Agent 更有价值。从最小可行版本开始，随着边界、验证和治理能力的增长，逐步扩张 Agent 的能力范围。