Agent 工程样板：任务规划、工具调用与失败恢复#

Agent 不是“让模型自由发挥”。一个可靠 Agent 应该有明确目标、可控工具、执行边界、日志和失败恢复机制。

这个案例会搭一个最小 Agent 工作流。

Agent 最小结构#

1
用户目标
2
  ↓
3
任务规划
4
  ↓
5
选择工具
6
  ↓
7
执行工具
8
  ↓
9
观察结果
10
  ↓
11
反思修正
12
  ↓
13
最终输出

项目结构#

1
agent-template/
2
├─ src/
3
│  ├─ agent.ts
4
│  ├─ tools.ts
5
│  ├─ planner.ts
6
│  └─ logger.ts
7
└─ .env

第一步：定义目标#

Agent 的输入不要太泛。好的目标应该包含任务、限制和成功标准。

1
目标：整理三篇关于 RAG 的笔记，输出一份学习计划。
2
限制：只使用本地文档，不要联网搜索。
3
成功标准：输出 5 个学习主题、每个主题的摘要和下一步练习。

第二步：定义工具#

工具要小而清楚。

1
type Tool = {
2
  name: string;
3
  description: string;
4
  run: (input: Record<string, unknown>) => Promise<string>;
5
};
6

7
const tools: Tool[] = [
8
  {
9
    name: "search_notes",
10
    description: "在本地笔记中搜索相关内容。",
11
    run: async ({ query }) => {
12
      return `和 ${query} 相关的笔记片段...`;
13
    },
14
  },
15
];

工具描述要说明：

能做什么。
什么时候用。
输入参数是什么。
不应该用来做什么。

第三步：让模型先规划#

不要让 Agent 一上来就执行。先让它输出计划：

1
你是一个谨慎的任务规划 Agent。
2

3
目标：
4
{goal}
5

6
可用工具：
7
{tools}
8

9
请先输出：
10
1. 任务拆解
11
2. 每一步需要的工具
12
3. 成功标准
13
4. 可能失败点
14
5. 是否需要用户确认

第四步：执行循环#

最小循环可以这样写：

1
for (let step = 0; step < maxSteps; step++) {
2
  const action = await chooseNextAction(goal, history, tools);
3

4
  if (action.type === "final") {
5
    return action.answer;
6
  }
7

8
  const tool = tools.find((item) => item.name === action.toolName);
9
  if (!tool) throw new Error(`未知工具：${action.toolName}`);
10

11
  const observation = await tool.run(action.input);
12
  history.push({ action, observation });
13
}
14

15
throw new Error("超过最大执行步数");

第五步：记录执行日志#

Agent 必须可观察。每一步都记录：

当前目标。
模型选择的工具。
工具输入。
工具输出。
模型下一步判断。

日志不是装饰，它是排查 Agent 失控的核心工具。

第六步：失败恢复#

常见失败包括：

失败	处理方式
重复调用同一工具	检测重复 action，要求换策略
工具返回空	让模型缩小或改写查询
工具报错	返回错误信息，让模型选择备用方案
步数过多	设置 maxSteps，要求汇总已有结果
权限过大	工具权限最小化，只开放必要路径