Agent：让 AI 围绕目标执行任务

Agent 是 AI 学习路线的第六章。

前面几章已经分别解决了表达、结构化、工具、知识和评估问题。Prompt 让 AI 理解任务，Structured Output 让结果可解析，Tool Calling 让 AI 可以调用外部能力，RAG 让 AI 可以使用私有知识，Eval 让我们能判断效果好不好。到了第六章，我们要把这些能力组合起来，让 AI 围绕一个目标连续执行任务。

在简单问答里，用户问一次，AI 回答一次就够了。但真实项目里，很多任务需要多步完成。例如分析启动失败原因，要读配置、跑命令、看日志、定位错误、提出修复方案、再验证结果。Agent 的价值，就是让 AI 可以在目标驱动下持续规划、行动、观察和修正。

这一章要解决的问题是：

如何把模型、工具、记忆和执行循环组合起来，让 AI 能完成多步骤任务。

学完这一章，你应该能做到三件事：

• 设计一个基础 Agent 执行循环
• 让 Agent 按目标规划步骤、调用工具、观察结果并继续推进
• 为 Agent 增加失败恢复、人工确认和质量评估机制

1. Agent 是什么

Agent 可以理解成具备目标、工具和执行循环的 AI 程序。

普通 AI 问答通常是：

用户输入
  ↓
模型回答

Agent 的流程更像这样：

用户给出目标
  ↓
Agent 制定计划
  ↓
Agent 调用工具执行动作
  ↓
Agent 观察工具结果
  ↓
Agent 根据结果调整下一步
  ↓
重复执行，直到任务完成或需要人工确认

一个基础 Agent 通常包含：

• 目标
• 模型
• 工具
• 状态
• 执行循环
• 观察结果
• 失败处理
• 人工确认
• 最终输出

Agent 的核心特点，是可以围绕目标进行多步骤执行。

2. 为什么需要 Agent

很多真实任务无法通过一次回答完成。

常见例子：

• 分析项目启动失败原因
• 根据需求生成测试点并补充缺口问题
• 读取代码后生成接口文档
• 检查部署状态并定位异常服务
• 根据日志找出错误来源
• 自动整理目录中的文件
• 对一组接口执行巡检
• 生成方案、执行验证、输出报告

这些任务通常具备几个特点：

• 需要多次读取信息
• 需要调用多个工具
• 中间结果会影响下一步
• 可能出现失败和重试
• 关键操作需要人工确认
• 最终结果需要汇总和解释

Agent 可以把这些步骤串起来，让 AI 从单次回答升级为连续执行。

3. Agent 的基本组成

一个可用 Agent 通常包含这些模块：

• planner：负责规划任务步骤
• tools：负责执行外部动作
• memory/state：负责保存上下文和进度
• executor：负责调度执行
• observer：负责读取工具返回和环境变化
• reflector：负责检查结果并调整策略
• guardrails：负责权限、安全和风险控制
• evaluator：负责判断任务是否完成

可以用一个简化结构表示：

目标
  ↓
Planner 生成计划
  ↓
Executor 选择动作
  ↓
Tool 执行动作
  ↓
Observer 读取结果
  ↓
Reflector 判断是否继续
  ↓
完成 / 重试 / 请求人工确认

Agent 由模型、工具、状态和执行循环共同组成，是一套围绕任务执行的控制流程。

4. planning

planning 指的是让 Agent 先拆解任务。

好的计划能减少盲目调用工具，也能让用户理解 Agent 准备怎么做。

示例任务：

帮我分析这个 Node.js 项目为什么启动失败。

可能计划：

1. 查看 package.json，确认启动脚本。
2. 查看项目依赖和配置文件。
3. 执行启动命令，收集错误日志。
4. 根据日志定位相关文件。
5. 给出原因和修复建议。
6. 必要时执行验证命令。

planning 常见形式：

• 先列计划，再执行
• 边执行边规划下一步
• 根据工具结果动态调整计划
• 对高风险操作先请求确认

计划不需要过度复杂，但要能指导行动。

4.1 计划粒度

计划太粗，Agent 容易乱走。计划太细，会消耗过多上下文和时间。

合适的计划通常满足：

• 每一步都能执行
• 每一步都有明确目的
• 每一步能产生可观察结果
• 后续步骤可以根据结果调整

问题计划：

1. 解决问题。

更清楚的计划：

1. 读取启动脚本。
2. 运行启动命令复现错误。
3. 根据错误栈定位文件。
4. 修改或给出修复建议。
5. 运行验证命令。

5. action

action 指的是 Agent 执行的具体动作。

常见 action 包括：

• 调用文件读取工具
• 调用搜索工具
• 调用命令执行工具
• 调用数据库查询工具
• 调用接口请求工具
• 写入文件
• 生成报告
• 请求用户确认

action 要尽量小而明确。

示例：

{
  "action": "read_file",
  "arguments": {
    "path": "package.json"
  },
  "reason": "需要确认项目启动脚本"
}

每次 action 最好记录：

• 为什么执行
• 调用了什么工具
• 参数是什么
• 结果是什么
• 是否成功
• 下一步依据是什么

这些记录后续可以用于调试、审计和 Eval。

6. observation

observation 指的是 Agent 获取执行结果。

工具调用后，Agent 需要观察结果，再决定下一步。

示例：

Action：运行 npm run dev

Observation：
Error: Cannot find module '@hono/node-server'

Agent 根据 observation 可以判断：

• 缺少依赖
• 需要查看 package.json
• 需要检查 lockfile
• 需要运行安装命令或给出修复建议

observation 要尽量保留事实。

建议区分：

• 工具原始输出
• Agent 的解释
• 下一步推断

示例：

观察到的事实：启动命令报错 Cannot find module '@hono/node-server'。
初步判断：项目缺少该依赖，或依赖没有安装成功。
下一步：检查 package.json 中是否声明该依赖。

事实和推断分开，能降低误判风险。

7. reflection

reflection 指的是 Agent 对当前结果进行反思和校验。

常见 reflection 问题：

• 当前步骤是否完成了预期目标
• 工具结果是否可信
• 是否需要补充信息
• 是否出现了新的风险
• 是否需要调整计划
• 是否可以结束任务
• 是否需要人工确认

示例：

当前计划是定位启动失败原因。
已经复现错误，并确认缺少依赖声明。
还需要检查项目是否使用 pnpm、npm 或 yarn，避免给出错误安装命令。

reflection 的作用，是防止 Agent 一直机械执行原计划。

7.1 什么时候需要 reflection

适合加入 reflection 的节点：

• 工具失败后
• 计划执行到一半时
• 出现多种可能原因时
• 准备修改文件前
• 准备执行危险操作前
• 准备输出最终结论前

reflection 不需要每一步都很长。关键是让 Agent 停下来检查方向。

8. retry

retry 指的是失败后的重试策略。

工具调用和多步骤任务都可能失败。

常见失败原因：

• 网络超时
• 文件不存在
• 参数错误
• 权限不足
• 命令执行失败
• 外部 API 限流
• 检索结果为空
• 模型选择了错误工具

retry 不能简单无限重试，需要有规则。

建议设计：

• 最大重试次数
• 可重试错误类型
• 不可重试错误类型
• 重试间隔
• 重试前参数修正
• 失败后用户提示

示例：

重试策略：
1. 网络超时最多重试 2 次。
2. 参数校验失败不自动重试，先修正参数。
3. 权限不足不重试，提示用户授权。
4. 删除、发布、付款类操作不自动重试。

重试的目标是恢复临时失败，同时避免扩大风险。

9. task loop

task loop 是 Agent 的执行循环。

一个简化 task loop 可以这样表示：

while 任务未完成:
  观察当前状态
  判断下一步动作
  调用工具
  读取结果
  更新状态
  检查是否完成

伪代码：

while (!done && stepCount < maxSteps) {
  const nextAction = await model.planNextAction({
    goal,
    state,
    availableTools,
  });

  if (nextAction.requiresConfirmation) {
    await requestHumanConfirmation(nextAction);
  }

  const observation = await executeTool(nextAction);

  state = updateState(state, nextAction, observation);

  done = await evaluateDone(goal, state);
}

task loop 需要几个保护：

• 最大步数
• 最大执行时间
• 最大工具调用次数
• 失败次数上限
• 上下文长度控制
• 危险操作确认
• 最终完成条件

没有这些保护，Agent 容易陷入重复调用、成本失控或风险操作。

10. human-in-the-loop

human-in-the-loop 指的是在关键节点让人参与判断。

Agent 可以自动执行很多步骤，但有些动作需要人工确认。

适合人工确认的场景：

• 修改文件
• 删除数据
• 执行部署
• 重启服务
• 修改生产配置
• 发送通知
• 调用付款接口
• 批量处理用户数据
• 访问敏感信息

确认前应该展示：

• 当前目标
• 已完成步骤
• 将要执行的动作
• 具体参数
• 影响范围
• 风险说明
• 可回滚方式

示例：

当前目标：修复项目启动失败。
已确认原因：缺少 @hono/node-server 依赖。
准备执行：npm install @hono/node-server
影响范围：修改 package.json 和 lockfile。
风险说明：会改变依赖树。

请确认是否继续。

human-in-the-loop 能让 Agent 在效率和安全之间取得平衡。

11. 多步骤任务执行

Agent 最适合处理多步骤任务。

11.1 日志分析 Agent

任务：

分析服务启动失败原因。

执行流程：

1. 读取启动命令。
2. 执行启动命令或读取日志文件。
3. 提取关键错误。
4. 搜索相关配置或源码。
5. 判断可能原因。
6. 给出验证方法。
7. 输出修复建议。

关键能力：

• 文件读取
• 命令执行
• 错误提取
• 代码搜索
• 结论自检

11.2 代码审查 Agent

任务：

审查某次代码改动。

执行流程：

1. 获取 diff。
2. 识别改动文件和风险模块。
3. 阅读关键代码。
4. 检查空值、权限、边界、事务、并发和错误处理。
5. 检查测试覆盖。
6. 输出按严重程度排序的问题。

关键能力：

• diff 分析
• 代码阅读
• 风险识别
• 测试检查
• 结构化输出

11.3 接口测试 Agent

任务：

根据接口文档生成测试点，并检查实际代码是否一致。

执行流程：

1. 读取接口文档。
2. 读取路由和 DTO。
3. 对比字段、状态码、鉴权和错误码。
4. 生成正常、异常、边界测试点。
5. 标出文档和代码不一致之处。
6. 输出待确认问题。

关键能力：

• 文档读取
• 代码检索
• 结构化测试设计
• 差异分析

11.4 部署巡检 Agent

任务：

检查线上服务是否正常。

执行流程：

1. 检查服务进程。
2. 检查健康接口。
3. 检查错误日志。
4. 检查磁盘、内存和 CPU。
5. 检查最近部署记录。
6. 汇总当前状态和风险。

关键能力：

• 命令执行
• 日志读取
• 健康检查
• 指标汇总
• 风险报告

12. 失败恢复

Agent 必须考虑失败恢复。

常见失败场景：

• 工具不可用
• 命令超时
• 检索无结果
• 文件读取失败
• 权限不足
• 用户拒绝确认
• 中间判断错误
• 外部系统返回异常

失败恢复策略包括：

• 换一种工具尝试
• 缩小问题范围
• 请求用户补充信息
• 输出已确认事实和未完成部分
• 回滚已执行动作
• 停止危险流程
• 记录失败原因

示例：

已完成：
1. 找到启动脚本。
2. 运行命令并复现错误。

失败点：
读取 .env 文件时权限不足。

当前可以确认：
启动失败与 DATABASE_URL 缺失有关。

需要用户补充：
是否允许读取当前环境变量配置。

失败恢复的重点，是保留已获得的信息，并清楚说明卡在哪里。

13. Agent 状态管理

Agent 执行多步骤任务时，需要管理状态。

常见状态包括：

• 用户目标
• 当前计划
• 已执行步骤
• 工具调用结果
• 中间结论
• 失败次数
• 用户确认记录
• 任务完成条件

示例状态：

{
  "goal": "分析项目启动失败原因",
  "plan": ["查看 package.json", "运行启动命令", "分析错误日志"],
  "completed_steps": ["查看 package.json"],
  "observations": [
    {
      "tool": "read_file",
      "summary": "启动命令为 npm run dev"
    }
  ],
  "next_step": "运行启动命令",
  "failure_count": 0,
  "done": false
}

状态可以放在内存、数据库、文件或工作流引擎中。任务越长，状态管理越重要。

14. Agent 的完成条件

Agent 需要知道什么时候结束。

常见完成条件：

• 已回答用户问题
• 已完成所有计划步骤
• 已达到明确验收标准
• 已生成最终报告
• 已运行验证命令并通过
• 已遇到不可继续的阻塞点
• 已达到最大步数或最大时间

示例：

完成条件：
1. 找到启动失败的直接错误。
2. 给出最可能根因。
3. 给出验证命令。
4. 如果能修改，则修复后运行验证。
5. 如果不能修改，则说明缺少的信息。

完成条件越清楚，Agent 越不容易无意义循环。

15. Agent 的安全边界

Agent 能连续调用工具，风险也更高。

需要重点控制：

• 文件写入
• 文件删除
• 数据库修改
• 生产环境命令
• 付款和扣费接口
• 消息发送
• 敏感数据读取
• 外部网络请求
• token 和密钥处理

常见安全策略：

• 工具白名单
• 参数校验
• 路径限制
• 只读默认模式
• 高风险动作确认
• 最大执行步数
• 最大成本预算
• 审计日志
• 权限分级
• 沙箱执行

Agent 的安全边界要靠程序保证，不能只靠模型自觉。

16. Agent Eval

Agent 需要单独评估。

常见评估指标：

• 任务完成率
• 平均步骤数
• 工具调用成功率
• 错误恢复率
• 人工确认触发准确率
• 危险操作误调用率
• 最终回答正确率
• 平均成本
• 平均延迟

示例 Eval 样例：

{
  "id": "agent-debug-001",
  "goal": "分析项目启动失败原因",
  "expected_steps": ["读取 package.json", "运行启动命令", "分析错误日志"],
  "expected_findings": ["缺少依赖 @hono/node-server"],
  "forbidden_actions": ["删除文件", "修改生产配置"]
}

评估时要看最终结果，也要看中间步骤。

17. Agent Prompt 示例

基础 Agent Prompt：

你是一个项目排障 Agent。

目标：
帮助用户定位项目启动失败原因，并给出可验证的修复建议。

可用工具：
1. read_file：读取工作区文件。
2. search_files：搜索文件名或文本内容。
3. run_command：执行允许列表中的命令。

执行规则：
1. 先制定简短计划。
2. 每次只执行一个明确动作。
3. 工具返回后，先总结观察到的事实。
4. 根据事实决定下一步。
5. 修改文件、删除文件、安装依赖、执行部署前必须请求用户确认。
6. 如果信息不足，请说明缺少哪些信息。
7. 最终输出直接原因、证据、修复建议和验证方法。

安全规则：
1. 不要执行删除、上传、发布、付款类操作。
2. 不要读取工作区外文件。
3. 不要输出密钥、token 或隐私数据。

这个 Prompt 明确了目标、工具、执行规则、安全边界和最终输出。

18. 常见 Agent 问题

18.1 计划太空

问题表现：

• 计划只有“分析问题”“解决问题”
• 每一步没有可执行动作
• 工具调用缺少依据

处理方式：

• 要求每一步有明确动作
• 要求说明每一步目的
• 要求每一步产生可观察结果

18.2 工具调用过多

问题表现：

• 重复读取同一个文件
• 重复执行相同命令
• 不断搜索相似关键词
• 成本和耗时升高

处理方式：

• 设置最大步骤数
• 记录已执行动作
• 禁止重复无收益调用
• 每次调用前说明目的

18.3 不会停止

问题表现：

• 已经得到答案仍继续查找
• 反复追加无关检查
• 任务边界不断扩大

处理方式：

• 设置完成条件
• 设置最大执行时间
• 要求达到目标后输出结论
• 把可选优化放到后续建议

18.4 失败后乱重试

问题表现：

• 权限不足仍重复执行
• 参数错误仍重复调用
• 高风险操作失败后自动重试

处理方式：

• 区分可重试和不可重试错误
• 限制重试次数
• 重试前必须改变参数或策略
• 高风险操作禁止自动重试

18.5 跳过人工确认

问题表现：

• 直接修改文件
• 直接删除数据
• 直接执行部署
• 直接发送通知

处理方式：

• 在工具层强制确认
• 给高风险工具加权限控制
• 记录确认日志
• Eval 中检查确认触发准确率

19. Agent 实战练习

可以按下面顺序练习：

1. 文件整理 Agent
2. 日志分析 Agent
3. 代码审查 Agent
4. 接口测试 Agent
5. 部署巡检 Agent
6. 给 Agent 增加最大步骤数
7. 给 Agent 增加工具调用日志
8. 给 Agent 增加失败恢复
9. 给高风险动作增加人工确认
10. 给 Agent 设计 Eval 测试集

每个练习都可以检查三个问题：

• Agent 是否能完成目标
• Agent 是否能解释每一步依据
• Agent 是否在风险动作前请求确认

20. 阶段验收标准

学完这一章，可以用下面的问题检查自己：

• 我能不能说明 Agent 和单次问答的差异？
• 我能不能设计一个基础 task loop？
• 我能不能让 Agent 先规划再行动？
• 我能不能让 Agent 根据 observation 调整下一步？
• 我能不能设计 retry 规则？
• 我能不能设置完成条件，避免无限循环？
• 我能不能在危险操作前加入 human-in-the-loop？
• 我能不能保存 Agent 的执行状态？
• 我能不能处理工具失败和权限不足？
• 我能不能评估 Agent 的任务完成率和工具调用成功率？

如果这些问题大多数都能做到，说明 Agent 阶段已经基本合格。

21. 本章总结

Agent 的核心是围绕目标进行持续执行。

一套可用的 Agent 设计，建议至少包含：

• 明确目标
• planning
• action
• observation
• reflection
• retry
• task loop
• human-in-the-loop
• 多步骤任务执行
• 失败恢复
• 状态管理
• 完成条件
• 安全边界
• Agent Eval

Agent 是 AI 工程化路线中的执行能力升级。它把模型、工具、知识、状态和评估组合起来，让 AI 可以连续完成任务。

这一章的目标很明确：让 AI 能围绕一个目标推进多步骤任务，同时让每一步都有依据、有边界、可恢复、可评估。