Agent 的工具调用设计：schema 定义与失败重试

Agent 的工具调用设计：schema 定义与失败重试

Agent 的能力上限由两个东西决定：模型的推理能力和工具的设计质量。前者我们控制不了，后者是纯工程——而多数团队的工具调用问题出在设计上：schema 描述模糊让模型选错参数、错误信息缺失让模型无法重试、工具粒度混乱让模型该调的不调。本文讲工具调用的完整设计：schema 怎么写、错误怎么返回、重试怎么做、粒度怎么切。

一、Schema：写给模型看的接口文档

工具的 function calling schema 是模型的「使用说明书」，它的质量直接决定调用的准确率。三个设计原则：

描述写给模型而不是人。参数描述不是「用户 ID」而是「查询的目标用户 ID，来自会话上下文的 user_id 字段，不可为空」。模型读描述决定传什么——描述里没说的规则（格式、来源、默认值）模型一定猜错。经验法则：把你给新同事解释这个参数要说的每句话都写进 description。

枚举优于自由文本。参数值空间有限的用 enum（渠道类型枚举列出），日期格式明确写出（ISO 8601），ID 的格式给出正则样例。自由文本参数是幻觉重灾区——模型会编一个「看起来像」的值。

工具间职责正交。两个工具都能完成的事，模型选择的行为不可预测。设计时每个任务只有一个明确入口：查订单是 get_order，不要同时有 search_orders 和 query_order_history（模型会在两者之间随机摇摆）。真有重叠需求，合并成一个带 mode 参数的工具。

二、错误返回：错误消息是给模型的重试指令

工具调用失败时返回什么？多数实现返回一个笼统的 error 字符串——模型读到「调用失败」后要么放弃要么盲目重试（重复同样错误）。

结构化错误设计：错误返回包含四要素——错误码（可重试/不可重试分类）、人可读的消息、机器可操作的重试指引（「参数 user_id 格式应为 UUID」而不是「参数错误」）、可能的修正建议。模型读到「user_id 应为 UUID，你传的是用户名」能在下一轮直接修正——这就是「自我修复」能力的来源：不是模型聪明，是错误信息里包含了修复指令。

可重试与不可重试的区分：参数错误 → 模型可自行修正重试；网络超时 → 可重试但建议指数退避（工具层处理，透明给模型重试结果）；权限不足/数据不存在 → 不可重试，模型应该改变策略（问用户或换路径）。错误码带 retryable 标志，Agent 编排层按标志决定是重试还是上抛。

三、重试的分层设计

重试发生在三层，各管各的：a. 工具层（自愈层）：网络抖动、限流这类瞬时错误，工具实现内部自动重试（指数退避 2~3 次），对 Agent 透明——模型不该为基础设施抖动浪费推理轮次；b. 模型层（纠错层）：参数错误、逻辑错误——模型的下一轮推理读错误信息修正后重调。这一层的重试次数要限制（同一工具连续失败 3 次即停止，防止死循环烧 token），失败超限上抛给用户或降级流程；c. 编排层（兜底层）：整个任务链多次失败后的降级路径——换工具、换模型、或人工接管。

幂等是重试的前提：所有写操作的工具必须幂等（带请求 ID 去重或天然幂等的设计）。不幂等的工具 + 自动重试 = 重复下单事故。这和任何分布式系统的重试设计一致，只是这里「调用方」是模型。

四、工具粒度：平衡的艺术

太粗（一个大工具干十件事）：参数列表长、模型选参错误率飙升。反面案例：execute_task(type, params_json) 这种「万能接口」——params_json 里的内容模型全靠猜。太细（每件小事一个工具）：模型要在几十个工具里规划调用链，每步都可能出错，总成功率是各步乘积——步骤越多越脆弱。

粒度判断标准：以「一次业务动作」为单位。查订单是一个工具（尽管内部查了主表+物流表）；处理退款是一个工具（包含查单、校验、创建退款单——但用户确认环节拆出去是单独工具，因为它需要人工介入）。工具数量控制在 10~20 个以内（GPT-4 级模型在 30+ 工具时的选择准确率开始可测地下降），超过就要分组（Agent 路由到子 Agent，子 Agent 持有小组工具）。

五、可观测与评测

调用链路追踪：每次工具调用记录 trace（调用参数、返回、耗时、错误），串在 Agent 会话的 trace 下。排查「为什么 Agent 没查到数据」的唯一途径——不看调用链，只能靠猜。

工具级评测：每个工具准备 10~20 个「典型正确调用」的测试用例（正确参数 → 期望行为），模型或工具实现更新时回归。再加一层「模型调用评测」：给业务场景，看模型选的工具和参数对不对（这一层测的是 schema 写得好不好——schema 模糊在调用评测里立刻暴露）。

线上指标：工具调用成功率（失败里区分可重试和不可重试）、平均重试次数（高重试说明 schema 有歧义）、工具选择分布（某个工具从未被调用——可能是描述问题或真的冗余）。

结语

工具调用设计的本质是把隐性的工程知识显性化到 schema 和错误消息里——参数的约束、错误的修复路径、调用时机的边界，都写成模型能读的结构化文本。做得好的团队，同样的模型能跑出高一档的 Agent 表现——这不是玄学，是接口设计的工程红利在 LLM 时代的复现。