AI Agent 工程化实战 #03:工具与外部能力:接口化

AI AGENT 工程化实战 · #03

工具与外部能力：接口化

承接 #02 的工具层 · 下一篇讲状态与记忆

先说结论：契约没写进「允许」的写操作，工具箱里就不要有这个方法。能调不等于能挂；挂上去的每一项，都要能在契约里对上号。

上一篇把工具放进了「工具与知识」层：失败时把原因告诉编排，不要自己编给用户看的句子。这一篇继续往下挖：一个工具怎样才算能进门。

① 空白 Tool Spec

② 工具准入清单

01 · 指什么

工具是编排能调用的外部能力：读接口、写接口、查库、跑命令、调 MCP。模型不能直接摸这些能力，只能通过编排去调。

「接口化」不是多写几个 HTTP 路径，而是约定清楚：对应契约哪一条、超时和失败怎么回报、重复调用会不会多写一次、谁能叫、怎么下线。

没有规格的工具，看起来像插件，用起来像暗门。今天能读，明天顺手加了写，契约还没改，线上已经能改数据了。

02 · 现场

用户说「顺便合并」。模型选中了写接口，因为工具列表里本来就挂着它。契约写了不许写，工具箱却没收干净。

拉 diff 超时了。工具把 HTML 错误页塞回上下文，模型据此写出「本次优化了稳定性」。失败原因没有分类，编排没法返回固定的失败句。

网络抖了，同一次操作重试两次。以后若有写回，没有幂等约定，就会写两遍，或者第二遍盖掉第一遍。

下线一个旧接口，提示词里还留着旧名字。模型继续选它，成功路径变成随机失败。

换更强的模型补不上。要补的是：进门有清单，调用有规格，失败有固定原因，下线有收口。

03 · 总规矩

契约没允许的写操作，工具层不要有这个方法

读操作也要登记。不是「能调的都可以挂上去」，而是「挂上去的每一项，都能在契约里找到对应允许」。

变更说明现在

契约允许读 diff、读提交说明 → 工具箱只有这两类读方法。
写操作一律禁止 → 不要挂 merge、发评论、「写回描述」。

以后要加写回：先改契约（允许写，并且必须人工确认）→ 再写 Tool Spec → 再实现 → 最后挂进编排。反过来做，工具会比契约多一只手。

04 · Spec 写什么

一个工具一页短规格。写不下，往往是一个名字下塞了好几件事，该拆开。

名称与对应契约

对不上契约里「允许」的那一条，就不要实现。

输入与输出

成功时返回材料，不要返回「已经写好的说明」。失败时返回原因分类，不要返回业务长文。

超时

毫秒数可以放配置。规格里要钉死：超时算哪一种失败，以及会不会自动重试。读可以有限重试；写默认不自动重试，除非写明了幂等键怎么用。

失败原因名要固定

EMPTY、TIMEOUT、FORBIDDEN、NOT_FOUND、DOWNSTREAM，写工具再加 CONFLICT。编排靠这些名字去配用户看到的那句话。

幂等

读工具写明「重复调用安全」。写工具必须写幂等键。没有键，编排就不要自动重试。

权限、确认、版本

只允许编排调用，模型拿不到客户端。写操作默认要人确认。行为变了就升版本，下线有日期。编排只认登记过的名字，不靠提示词里的口语别名。

变更说明：read_diff 怎么写（节选）

对应契约：允许读本次 diff
成功返回：diff_text（材料，不是说明正文）
超时：3s，TIMEOUT 可重试 1 次
失败：EMPTY / TIMEOUT / FORBIDDEN / NOT_FOUND / DOWNSTREAM
幂等：只读，重复调用安全
权限：仅编排；无需人工确认

05 · 带走

① 空白 Tool Spec

填不出「对应契约条目」，就先停。先改契约，再写规格。

# Tool Spec 名称 / 版本 / 对应契约条目 / 一句话  输入：必填、选填、禁止传入 输出（成功）：字段；只返回材料或回执  超时：默认；自动重试次数与条件；超时原因名  失败原因（名称固定） EMPTY / TIMEOUT / FORBIDDEN / NOT_FOUND DOWNSTREAM / CONFLICT（写工具）  幂等：是否只读；写操作幂等键 无键时禁止自动重试  权限：仅编排 人工确认：是 / 否（写操作默认是）  版本与下线：当前版本；计划下线日期

② 准入清单

有一条是否，不准进箱。

1. 契约「允许」里能找到对应条目。找不到，就是工具比契约多一只手。

2. 有一页 Spec，失败原因名写全了。

3. 失败只返回原因分类，不返回业务长文。

4. 写工具有幂等键；没键就禁止自动重试。

5. 写工具默认要人确认，除非契约明文可自动。

6. 模型拿不到该工具的客户端。拿得到，分层又糊回去了。

7. 读和写的超时、重试策略分开写。

8. 下线或改名时，编排只认登记名，不认提示词别名。

9. 门禁里至少有一条：该工具失败时，走契约规定的失败句。

第 1 条和第 6 条最容易烂：契约没改就加能力；图上分层了，模型却仍能直接调工具。实验工具不要进生产清单，名称上分开。

06 · 看着省事

把供应商的原始错误丢给模型。模型会开始解释错误页，用户看到的话每天不一样。先收成原因名，再让编排配句。

一个工具名又读 diff 又写评论。拆开，读写分开登记。

用提示词写「不要调用写工具」。写方法还在列表里，就总会被选中。没收掉方法，比多写一句「请小心」有效。

全公司一把万能工具箱。最宽的权限会传给最窄的那个 Agent。按契约版本挂工具，不要挂全局大杂烩。

NEXT

AI Agent 工程化实战 #04：状态与记忆——工程视角

工具读回来的内容、对话里说过的话，哪些只活在这一次调用，哪些可以留下。先问该不该记，再问能不能存。

关注 Java宋转AI · 系列持续更新