1 / 4概念
Agent 与工具调用
一个 agent 不是"更聪明的模型",而是模型 + 工具 + 循环 + 上下文预算。模型只负责下一步决策,其余三样是我们写的代码,也是绝大多数故障的来源。
1 概念
1.1 本页范围
属于这一页:
- agent 循环:观察 → 决策 → 调用工具 → 用结果更新上下文。
- 工具契约:名称、参数、返回、错误、副作用。
- 上下文管理:什么进上下文、什么落盘、什么时候压缩。
- 人工介入点:审批、确认、回滚。
不属于这一页:
| 主题 | 去哪 |
|---|---|
| 模型能力、上下文窗口、计费 | AI 桶的模型页(待写) |
| 推理服务、网关、GPU 容量 | 平台象限 + AI 平台页(待写) |
| 提示词技巧与评测 | 技术上属于方法层,模型页或技术象限 |
2 机制
2.1 工具的写法
工具是 agent 唯一的执行面,所以工具描述就是接口文档,而不是注释。
| 项 | 规则 | 反例 |
|---|---|---|
| 名称 | 动词 + 对象,一个工具只做一件事 | manage、utils |
| 参数 | 必填项真的有默认值吗?枚举优于自由文本 | path: string 无约束 |
| 返回 | 结构化、可截断、带单位 | 返回一整份 10 MB 日志 |
| 错误 | 区分"可重试"与"需要人改" | 所有失败都抛同一句 failed |
| 副作用 | 写操作要能在描述里被看见 | 读接口偷偷落盘 |
| 幂等 | 重试安全,或明确标注不可重试 | 每次调用都追加一行 |
参数校验放在工具内部,不要指望模型遵守提示。模型给错参数是常态,校验失败要返回可执行的修正信息,而不是一句"invalid"。
2.2 上下文预算
- 工具返回只保留决策需要的字段;大结果落盘,上下文里放路径与摘要。
- 长对话要压缩,但压缩不能丢"已经改过什么、还差什么"。
- 检索结果不要整篇塞入,先给标题与摘要,需要时再取正文。
3 实践
3.1 仓库里的落地
| 位置 | 作用 |
|---|---|
仓库根 .agents/ | 跨包约定:agent、架构、设计、任务、词表、流程 |
docs/.agents/ | 文档站自己的约定,与根目录保持同一套结构 |
.agents/skills/ | 可复用的作业包,一个技能一个 SKILL.md |
约定写在文件里、由 agent 读取,而不是写在提示词里:提示词会漂移,文件可以被评审和校验。
3.2 评审清单
- 每个工具都有唯一职责,且描述里写清了副作用。
- 参数有枚举或范围,非法输入返回修正提示。
- 有步数、调用次数、token 三个预算上限。
- 写操作、外部请求、不可逆动作需要人工确认。
- 连续无进展会停止,而不是继续重试。
- 工具返回可以截断,大结果落盘。
4 边界
4.1 循环怎么停
| 停止条件 | 做法 |
|---|---|
| 任务完成 | 工具返回终态,循环显式退出 |
| 预算耗尽 | 限制步数、工具调用次数、总 token,任一触发即停 |
| 无进展 | 连续两步没有新信息就停,不要让它"再想想" |
| 需要人 | 写操作、外部副作用、不可逆动作,先问 |
失败的 agent 通常不是错在某一跳,而是没有停止条件:它在同一个错误上反复重试,把上下文烧完。
4.2 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 同一错误反复重试,上下文被烧完 | 没有步数、调用次数、token 预算 | 三个上限任一触发即停 |
| 模型给出非法参数后继续执行 | 工具内部不校验,只返回 invalid | 工具内校验,返回可执行的修正信息 |
| 写操作被重复执行 | 工具没有幂等约定,重试不安全 | 标注不可重试,或加幂等键 |
| 长任务中途丢失目标 | 压缩丢掉了"改过什么、还差什么" | 压缩保留进度与未完成项 |
| 不可逆动作已经发生 | 没有人工介入点 | 写操作与外部副作用先确认 |