koyomi315的头像
koyomi315
北京邮电大学硕士,关注后端开发、AI Agent 与 Agent Evaluation。
1497 字
7 分钟

从模型 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 / external
confirmation: 是否需要人工确认

判断时还要结合实际参数。同一个文件工具,读取工作区文件与读取系统凭证目录的风险完全不同。

上下文为什么需要压缩#

对话历史、工具输出和代码片段会持续增长。当上下文接近上限时,简单删除最早消息可能丢失任务目标和关键决策。

更稳妥的压缩流程是:

  1. 保留系统指令和当前用户目标;
  2. 把已完成步骤、关键修改和验证结果压缩为结构化摘要;
  3. 保留仍未解决的问题及其证据;
  4. 丢弃可重新获取的冗长工具输出;
  5. 用摘要开启后续循环。

压缩不是一般意义的聊天总结,而是一次状态迁移。摘要必须足以让下一轮继续执行。

可观测性决定是否可调试#

Coding Agent 至少应记录:

  • 每轮模型请求和结束原因;
  • 工具名称、耗时、退出码与结果大小;
  • 权限拒绝和人工确认;
  • 上下文 Token 使用量;
  • 压缩发生时间及摘要版本;
  • 最终验证命令和结果。

没有这些信息时,失败只能被描述为“Agent 没做好”,而无法定位到模型、工具、权限、环境还是上下文。

总结#

Coding Agent 的核心不是某一段提示词,而是一个受约束、可观察、可恢复的执行循环。模型提出动作,工具执行动作,权限系统约束动作,反馈系统验证动作,上下文管理保证循环能够持续。把这些部分拆开,系统才具备工程上的可维护性。

从模型 API 到 Coding Agent:工具系统与 Agent Loop
https://example.com/posts/coding-agent-loop/
作者
koyomi315
发布于
2026-06-22
许可协议
CC BY-NC-SA 4.0

一只小鲸鱼正在游过来…

ⓘ
DeepSeek 同人鲸鱼娘

角色原作:上善无形
二次设计:ZipZipPipe
Live2D:氵六青

素材未修改 · CC BY-NC-SA 4.0

模型来源 ↗