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

1. Agent 是什么#

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

普通 AI 问答通常是：

1
用户输入
2
  ↓
3
模型回答

Agent 的流程更像这样：

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

一个基础 Agent 通常包含：

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

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

2. 为什么需要 Agent#

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

常见例子：

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

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

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

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

3. Agent 的基本组成#

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

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

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

1
目标
2
  ↓
3
Planner 生成计划
4
  ↓
5
Executor 选择动作
6
  ↓
7
Tool 执行动作
8
  ↓
9
Observer 读取结果
10
  ↓
11
Reflector 判断是否继续
12
  ↓
13
完成 / 重试 / 请求人工确认

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

4. planning#

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

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

示例任务：

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

可能计划：

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

planning 常见形式：

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

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

1
1. 解决问题。

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

5. action#

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

常见 action 包括：

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

action 要尽量小而明确。

示例：

1
{
2
  "action": "read_file",
3
  "arguments": {
4
    "path": "package.json"
5
  },
6
  "reason": "需要确认项目启动脚本"
7
}

每次 action 最好记录：

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

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

6. observation#

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

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

示例：

1
Action：运行 npm run dev
2

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

Agent 根据 observation 可以判断：

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

observation 要尽量保留事实。

建议区分：

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

示例：

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

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

7. reflection#

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

常见 reflection 问题：

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

示例：

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

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

8. retry#

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

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

常见失败原因：

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

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

建议设计：

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

示例：

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

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

9. task loop#

task loop 是 Agent 的执行循环。

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

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

伪代码：

1
while (!done && stepCount < maxSteps) {
2
  const nextAction = await model.planNextAction({
3
    goal,
4
    state,
5
    availableTools
6
  });
7

8
  if (nextAction.requiresConfirmation) {
9
    await requestHumanConfirmation(nextAction);
10
  }
11

12
  const observation = await executeTool(nextAction);
13

14
  state = updateState(state, nextAction, observation);
15

16
  done = await evaluateDone(goal, state);
17
}

task loop 需要几个保护：

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

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

10. human-in-the-loop#

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

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

适合人工确认的场景：

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

确认前应该展示：

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

示例：

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

7
请确认是否继续。

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

11. 多步骤任务执行#

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

1
分析服务启动失败原因。

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

1
审查某次代码改动。

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

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

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

1
检查线上服务是否正常。

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

12. 失败恢复#

Agent 必须考虑失败恢复。

常见失败场景：

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

失败恢复策略包括：

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

示例：

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

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

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

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

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

13. Agent 状态管理#

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

常见状态包括：

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

示例状态：

1
{
2
  "goal": "分析项目启动失败原因",
3
  "plan": [
4
    "查看 package.json",
5
    "运行启动命令",
6
    "分析错误日志"
7
  ],
8
  "completed_steps": [
9
    "查看 package.json"
10
  ],
11
  "observations": [
12
    {
13
      "tool": "read_file",
14
      "summary": "启动命令为 npm run dev"
15
    }
16
  ],
17
  "next_step": "运行启动命令",
18
  "failure_count": 0,
19
  "done": false
20
}

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

14. Agent 的完成条件#

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

常见完成条件：

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

示例：

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

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

15. Agent 的安全边界#

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

需要重点控制：

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

常见安全策略：

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

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

16. Agent Eval#

Agent 需要单独评估。

常见评估指标：

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

示例 Eval 样例：

1
{
2
  "id": "agent-debug-001",
3
  "goal": "分析项目启动失败原因",
4
  "expected_steps": [
5
    "读取 package.json",
6
    "运行启动命令",
7
    "分析错误日志"
8
  ],
9
  "expected_findings": [
10
    "缺少依赖 @hono/node-server"
11
  ],
12
  "forbidden_actions": [
13
    "删除文件",
14
    "修改生产配置"
15
  ]
16
}

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

17. Agent Prompt 示例#

基础 Agent Prompt：

1
你是一个项目排障 Agent。
2

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

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

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

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

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

18. 常见 Agent 问题#

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 能围绕一个目标推进多步骤任务，同时让每一步都有依据、有边界、可恢复、可评估。