一个常见的场景:团队给内部系统接了个 Agent,模型换了两轮,从便宜的小模型换到最强的旗舰模型,任务成功率从六成涨到七成多,然后就不动了。复盘时大家盯着 prompt 和模型版本,却很少有人去看那十几个工具函数的签名。
我判断 Agent 能不能干活,先看的不是模型卡上的分数,而是工具接口长什么样。工具是模型和真实世界之间唯一的通道,通道窄了,模型再聪明也只能在里面挤。这不是比喻,是工程上可以拆开看的约束:模型每一步能选的动作集合、每个动作能表达的参数范围、执行失败后能拿到的信息,全部由接口定义决定。
一个工具塞五个功能,模型就学会了乱猜
最常见的坏接口,是把后端已有的 CRUD(增删改查)接口原样暴露给模型。比如一个 manage_order 函数,参数是 action(create/update/cancel/query)、order_id、payload。从工程师角度看这很优雅,一个函数覆盖全场景。从模型角度看,这是四件不同的事被压进一个动作里,而且 payload 是个自由 JSON,模型得靠猜字段名。
后果是可预测的:模型会漏传必填字段、会在 cancel 时顺手带上 update 的字段、会把 action 拼成 modify。这些错误不是模型理解力不够,是接口没给它明确的落点。同一个动作空间里,模糊度越高,采样出错的概率越高,这跟模型大小关系不大。
我的做法是把工具按“用户意图”切,而不是按“数据表”切。取消订单和修改地址是两个意图,就应该是两个工具,参数各自收敛到三五个必填项。工具数量会涨,但每个工具的调用正确率会明显好于合并版。这里有个反直觉的点:工具变多,模型的选择难度会上升,所以要在“意图粒度”和“工具总数”之间取舍。我的默认是单个 Agent 暴露的工具控制在十个上下,超过就说明该拆 Agent,或者该把一部分动作收进更高层的组合工具里。
参数设计:别让模型填它推不出来的东西
第二类问题在参数层面。有些接口要求传 tenant_id、operator_id、内部枚举码,这些字段对人来说是上下文里现成的,对模型来说是它推不出来的。它只能从对话里翻,翻不到就编一个。
判据很简单:这个参数,一个刚入职三天、只读过需求文档的同事,能不能在没有任何额外提示的情况下填对?填不对的,就不该出现在工具签名里。租户和操作人应该由服务端从会话上下文注入,而不是让模型转述。枚举值要么在参数描述里列全,要么改成自然语言字段由服务端做映射。
还有一种隐性坑:时间。让模型填 start_time 和 end_time,它会算错相对时间,会把“上周”算成哪一周搞混,时区更是重灾区。可行的做法是让模型只传相对表达(last_7_days、yesterday)或者干脆不传,由服务端按固定规则解析。把不确定的计算从模型侧挪到确定性代码里,这类错误基本能清零。
1 | { |
上面这个签名里没有用户 ID、没有时间戳、没有分页游标。这些都由运行时补。接口越窄,模型要做的判断越少,出错面也越小。有人担心这样灵活性不够,但 Agent 场景里绝大部分失败不是“能力不足”,是“自由度用错了地方”。
报错信息写给人看,模型才有机会自我修正
工具调用失败后的返回,是最容易被忽略的一段。很多实现直接 return str(e),模型收到一句 KeyError: 'order_no',除了重试同一个调用,它做不了别的。
我更倾向把错误分成三类,并且都显式返回给模型:参数不合法(哪个字段、期望什么格式)、业务规则拒绝(为什么拒、什么条件下可以)、系统故障(暂时不可用、建议换路径或停手)。这三类对应模型三种完全不同的后续动作:改参数、换方案、放弃并告知用户。如果不区分,模型只能一律重试,于是你会看到它在一个注定失败的调用上转五圈。
这里有个容易做错的细节:业务规则拒绝时,别把内部规则原文抛出去。既要让模型知道“为什么不行”,又不能泄露风控策略。可行的是给一个稳定的错误码加一句面向用户的话术,让模型转述。判据是:这条错误信息如果被原样打到前端,会不会造成问题。会,就得在返回层做过滤。
另一个细节是返回值形状要稳定。同一个工具,有时返回数组,有时返回 {data: [...]},有时查不到就返回空字符串,模型每次都要重新猜结构,长任务里这种不稳定会累积成跑偏。统一成固定字段、固定类型、查不到就返回空数组加明确的 count: 0。这些是工程常识,但恰恰是模型能不能连续多步工作的分水岭。
工具描述是 prompt 的一部分,但它不负责兜底
工具描述写得含糊,模型就会选错工具。我见过把描述写成“处理订单相关操作”的,五个工具都这么写,模型只能靠名字猜。描述应该写清三件事:什么时候用它、什么时候不要用它、调用后会发生什么副作用。
副作用这条尤其重要。只读工具和写工具混在一起,模型没有理由更谨慎。可行的做法是在描述里直接标注“只读”或者“会修改数据,调用前需确认”,同时在运行时对写操作加一层确认。这不是靠 prompt 求模型小心,是靠接口把风险等级显性化。
但要划清边界:工具描述写得好,只能提升选择正确率,不能替代参数校验和权限控制。把安全寄托在“模型会看描述”上,是把责任放错了地方。接口层面的硬约束(权限、幂等、金额上限)必须由服务端兜住,模型只负责在约束内选路。
改接口比换模型便宜,但改之前先量一下
判断该不该动接口,我一般先看失败分布,而不是整体成功率。把失败样本按“参数错、选错工具、该停手没停、工具本身报错、模型推理错”归类,如果前四类占大头,换模型基本是浪费钱。
flowchart TD
A[失败样本] --> B{错在哪一层}
B -->|参数不合法| C[收窄参数 服务端注入]
B -->|选错工具| D[拆意图 重写描述]
B -->|该停手没停| E[错误分三类返回]
B -->|工具报错| F[修实现 补幂等]
B -->|推理错| G[再谈模型]这张图回答的是排查顺序问题:只有在接口层的四类都被排掉之后,剩下的失败才归模型。我的经验是,一个刚接完工具的 Agent,接口类失败往往占一半以上,把这部分压下去,成功率提升幅度通常比换一次模型大,而且成本只是几个函数签名和返回结构的改动。
还有一个边界要说清:接口收窄是有代价的。工具越专用,跨场景复用越差,遇到没预设过的用户意图,Agent 会显得“不会变通”。这不是设计失败,是取舍。我的默认是先把高频路径做成专用工具跑稳,长尾用一两个受限的通用查询兜底,并且明确告诉模型“通用工具只用于查询,不要用它做写入”。等长尾意图积累够了,再提升为专用工具。
做到第十年,我越来越觉得 Agent 的能力上限不是一个模型指标,而是一份接口清单。模型决定了它能理解多复杂的话,接口决定了它能把理解变成多少个正确的动作。前者你买得到,后者只能自己设计。
下次成功率卡住的时候,先别急着换模型,把工具列表打出来,逐个问一句:这个函数如果交给一个聪明但没有背景知识的新人,他会不会用错?会的话,问题就在这里。
评论