从模型 API 到 Coding Agent:工具系统与 Agent Loop
Coding Agent 并不是“把代码仓库发给模型”这么简单。真正让它能够持续工作的,是一套围绕模型 API 建立的消息协议、工具系统、执行循环、权限控制和上下文管理。
消息协议是运行时的地基
大多数模型 API 都把对话表示为消息数组。用户输入、模型回复、工具请求和工具结果需要按照协议组织,否则模型无法判断当前处于哪一步。
一次带工具调用的对话可以抽象为:
user: 修改登录接口的参数校验assistant: 请求读取控制器文件user: 返回工具执行结果assistant: 请求编辑文件user: 返回编辑结果assistant: 请求运行测试user: 返回测试输出assistant: 汇总改动和验证结果工具结果虽然由程序产生,但在很多 API 中仍作为一类输入消息回传。运行时需要保证工具调用 ID、结果和原始请求正确对应。
为什么需要流式响应
模型生成可能持续数秒甚至更久。流式响应可以让界面及时显示文本,也能更早接收到工具调用参数。
实现流式处理时需要区分:
- 文本增量;
- 工具调用的开始与参数增量;
- 完成原因;
- Token 使用量;
- 网络中断和不完整事件。
不要把收到的每个片段直接当成完整 JSON。运行时通常需要先聚合事件,再形成一条可保存的 assistant 消息。
Coding Agent 的核心工具
Read:读取文件
读取工具应支持 offset 和 limit,避免把超大文件一次性塞入上下文。返回内容最好带行号,便于后续精确修改。
还应明确处理:文件不存在、权限不足、二进制文件和超出工作区等错误。
Glob 与 Grep:定位内容
Glob 根据文件名模式找文件,Grep 根据文本或正则找内容。它们比让模型遍历目录更节省上下文。
搜索工具应默认排除 .git、依赖目录、缓存和构建产物,并限制最大结果数。输出采用“路径、行号、匹配行”的稳定格式。
Write 与 Edit:改变文件
覆盖写入适合创建新文件,但修改现有文件更适合使用精确替换:要求旧文本唯一匹配,找不到或匹配多处时拒绝执行。
这种设计看似保守,却能避免模型在不了解完整文件时覆盖用户内容。
Shell:执行命令
Shell 工具让 Agent 能够构建、测试和格式化代码,也是风险最高的常用工具之一。运行时至少需要:
- 限制工作目录;
- 设置超时;
- 截断过长输出;
- 返回标准输出、错误输出和退出码;
- 对高风险命令进行权限判断。
退出码非零并不总意味着程序异常,例如搜索工具可能用特定退出码表示“没有匹配”。工具层应保留事实,由 Agent 根据命令语义判断。
Agent Loop 如何运行
一个最小循环可以写成:
while 未结束: 组织当前上下文 调用模型 保存模型响应
if 响应包含工具调用: 校验权限与参数 执行工具 保存工具结果 else: 返回最终文本真正的工程复杂度出现在边界:一次响应可能包含多个工具调用;多个只读工具可以并发,写工具通常需要串行;用户可能中止任务;工具可能超时;模型也可能陷入重复调用。
因此循环还需要:最大轮数、取消信号、重复调用检测、工具并发规则和统一错误结构。
权限检查应该位于执行侧
不能依赖模型“自觉”避免危险操作。权限检查必须发生在工具真正执行之前。
一个工具可以携带这些元信息:
readOnly: 是否只读destructive: 是否可能造成不可恢复影响category: file / search / shell / externalconfirmation: 是否需要人工确认判断时还要结合实际参数。同一个文件工具,读取工作区文件与读取系统凭证目录的风险完全不同。
上下文为什么需要压缩
对话历史、工具输出和代码片段会持续增长。当上下文接近上限时,简单删除最早消息可能丢失任务目标和关键决策。
更稳妥的压缩流程是:
- 保留系统指令和当前用户目标;
- 把已完成步骤、关键修改和验证结果压缩为结构化摘要;
- 保留仍未解决的问题及其证据;
- 丢弃可重新获取的冗长工具输出;
- 用摘要开启后续循环。
压缩不是一般意义的聊天总结,而是一次状态迁移。摘要必须足以让下一轮继续执行。
可观测性决定是否可调试
Coding Agent 至少应记录:
- 每轮模型请求和结束原因;
- 工具名称、耗时、退出码与结果大小;
- 权限拒绝和人工确认;
- 上下文 Token 使用量;
- 压缩发生时间及摘要版本;
- 最终验证命令和结果。
没有这些信息时,失败只能被描述为“Agent 没做好”,而无法定位到模型、工具、权限、环境还是上下文。
总结
Coding Agent 的核心不是某一段提示词,而是一个受约束、可观察、可恢复的执行循环。模型提出动作,工具执行动作,权限系统约束动作,反馈系统验证动作,上下文管理保证循环能够持续。把这些部分拆开,系统才具备工程上的可维护性。