02 工具调用怎么不乱
作者：利威尔xu | CSDN 专栏《Agent 工程方法论》
你好，我是利威尔xu。咱们这个《Agent 工程方法论》专栏，会一篇一篇扎实更，你关注了才不会走丢。
先帮你把路线再捋一遍，免得你走散了。整个专栏是六篇正文加一篇番外：循环怎么跑，工具调用怎么不乱，记忆怎么分层，规划与任务分解，多智能体协作，可观测性与评估，番外做面试突击。上篇咱们把地基打好了，你知道了 Agent 是怎么接单、干活、交活、复盘的，循环那个圈会转了。这篇咱们往上走一层，讲 Agent 的手和脚，也就是工具调用。
为啥紧接着讲工具？循环会让 Agent 动，但手脚乱动照样出事。线上翻车最多的，从来不是模型不会想，而是它调错了工具，传错了参数，拿到了结果还不会用。循环是心脏，工具是手脚，心脏再好，手脚不听使唤，活儿照样干砸。要是觉得这个递进对你有用，记得点赞收藏一下，咱们接着往下走。
配工具箱：工具定义和描述怎么写
咱先从配工具箱说起。你家里装修请了个师傅，你得先给他配个工具箱。箱子里有锤子、扳手、电钻，每样工具上最好贴个标签，写清楚这玩意儿干啥用的，啥时候不能用。你不贴标签，师傅拿起电钻去拧水管，墙都给你打穿了。
Agent 的工具也一样。模型看不懂你的代码，它只认那段自然语言描述。你可能会问，描述随便写两句不行吗？真不行。这里有个坑，描述写得太虚，模型就乱调。你写“可以搜索信息”，它啥都搜，搜出一堆垃圾。你得写成“按关键词搜公司内部文档，返回标题加摘要，适合查规范和流程，不适合查实时股价”。说白了，描述里要讲清能干啥、不能干啥、输入长啥样、输出长啥样、出错会咋样。
工具定义在工程里一般长这样，咱看一眼伪代码：
tool search_docs:
name = "search_internal_docs"
desc = "搜内部文档，按关键词返回标题+摘要"
limits = "不碰外网，不查实时数据"
params = {query: string required, top_k: int default 5}
output = {title: string, snippet: string, doc_id: string}
side_effect = "只读，无副作用"
on_error = "空结果返回空列表，不抛异常"
timeout = "5s，超时返回空结果"
audit = "每次调用记日志，含参数摘要和结果码"
你看，名字、描述、边界、参数、输出、副作用，全写死了。模型照着这个挑，就不容易拿错。讲真，这份定义写得好不好，直接决定 Agent 是靠谱帮工还是破坏大王。
面试官可能追问什么：他爱问，工具描述写不好会导致啥线上问题？你就说，描述模糊会导致误调和幻觉调用，模型会编参数、编工具名。解法是描述里收紧边界，加正反例子，配参数校验兜底。
上锁和贴封条：参数校验和权限分级
工具箱配好了，得上锁。不是每样工具谁都能随便拿。电锯这种危险的，得锁起来，老师傅点头了才能用。
参数校验是第一道锁。模型传过来的参数，你一个都别信。类型不对的拦掉，必填没填的打回去，枚举值之外的拒绝，字符串超长的截断。别急，很多新手觉得模型很聪明，不会传错，线上跑两天就老实了。模型喝多了啥都干得出来，传个负数当数量，传个空字符串当搜索词，太常见了。校验这层必须放在 harness 里做，不指望模型自觉。
权限分级是第二道锁。工具得分三级，只读的随便用，比如查文档、查数据。会改状态的要审批，比如发邮件、下单、写库。高危的要人工确认，比如删数据、调支付。说白了，工具接口是 harness 的对外能力边界，工具编排就是 harness 在管“能做什么”。这句话你记住，面试能用上。
面试官可能追问什么：只读工具和写工具在设计上有啥本质区别？你就咬住副作用和可逆性。只读的随便重试，写的必须做幂等和确认，删库这种不可逆的必须走人工。这能看出你有没有线上敬畏心。
干错了能重来：幂等设计和错误重试
师傅干活难免失手，钻头打歪了，能不能退出来重打？能退出来重打的叫幂等，打一个洞算一个洞、重打就多出个窟窿的，就得小心了。
Agent 调工具也一样。网络抖一下，模型没收到返回，它很可能再调一次。你这个工具要是下单接口，调两次就下了两单，老板要找你算账了。所以写操作必须带幂等键，同样的活儿干两次，结果只算一次。实现上不复杂，请求里带个单号，服务端拿单号去重，见过这个单号直接返回上次的结果，不再干第二次。
错误处理也得分层。参数错了别重试，重试一百遍还是错，直接把报错翻译成人话扔回给模型，让它换个参数。网络超时、限流这种能重试，配退避等一会儿再来。工具挂了切备用，备用也没了再认怂，把失败写进状态，让上层决定回滚还是交卷。咱看一段伪代码感受一下这个分层：
resp = tools.call(name, args, idem_key=state.task_id)
if resp.code == PARAM_ERROR:
state.tell_model("参数不对：" + resp.hint)
return plan_again(state)
if resp.code == RETRYABLE:
wait(backoff(state.retries))
state.retries += 1
return retry_or_switch(resp)
if resp.code == FATAL:
state.mark_failed(name, resp)
return fallback_or_rollback(state)
state.save_result(summary(resp))
你看，错了就分得清清楚楚，啥该重试，啥该换路，啥该认怂。这里有个坑，很多人重试不带次数上限，也不记重试原因，模型就在那儿死磕一个坏工具，把 token 全烧光了。重试必须有上限，超了就换人。
面试官可能追问什么：幂等键怎么设计？标准答法是调用方生成，服务端去重，键里带任务加步骤，超时时间跟业务走。下单这种还得跟业务单号绑定，不能光靠随机数。
活儿多了挑哪个：工具太多怎么选
工具箱越来越大，十几个还好办，上百个模型就挑花眼了。全塞进 prompt，上下文直接爆掉，模型还选不准。
解法是分两步。第一步先粗筛，按任务类型、权限、标签过滤一遍，把明显用不上的扔掉。第二步再让模型细挑，只把候选工具的精简描述给它。说白了，别让模型在五金市场里找螺丝，先帮它缩小到一个货架。还有个偏方，给工具分组，搜索类放一组，写入类放一组，模型先选组再选工具，准确率能高不少。
你可能会问，动态加载会不会让模型忘了有这个工具？会，所以要在循环状态里留个工具清单的摘要，每步提醒它还有哪些组可用，不用全展开，点到为止就行。
面试官可能追问什么：工具太多塞不下 prompt 咋办？就答粗筛加分组加按需加载，再补一句缓存和 embedding 召回也行，但线上最稳的还是规则粗筛，因为可解释，出事能查。
拿回来得会用：结果回灌怎么不翻车
工具调完了，拿回来的东西得喂给模型，这步叫回灌。回灌做不好，前面全白干。
工具返回的东西又长又脏，直接全塞给模型，上下文马上就满了，关键信息还被淹没了。老手都是三步走，裁剪、摘要、标索引。原始结果先裁掉废话，只留关键字段，再翻成一两句人话摘要，最后把原文存下来，给个编号，模型想看细的再按编号取。打个比方，师傅去仓库领料，回来不用把整个货车开进屋，拿张清单回来就行，写着领了啥、放哪了、缺啥，要用再去取。
回灌的时候还得带上状态，上次调了啥、这次拿到了啥、还差啥，一起告诉模型。不然模型金鱼记忆，刚查到的东西转头就忘，又去调一遍，白花钱。
面试官可能追问什么：工具结果太大怎么喂给模型？你就说裁剪加摘要加索引三件套，再补一句敏感字段脱敏。这题考的是 token 成本意识和工程习惯。
聊到这儿，工具这层就算配齐了。你现在手里的 Agent，心脏会跳了，手脚也听使唤了。
下一篇咱们讲记忆系统怎么分层。工具稳了，下一个翻车点就是记性，上下文一长就忘事，重要信息留不住，垃圾信息又舍不得扔。到时候我带你把短期长期记忆那套彻底搞明白。
整个专栏的核心价值就一句话：让 Agent 从 demo 跑起来，到线上稳下来，再到面试时讲明白。你要是冲着转型 AI 应用或者拿大厂 offer 来的，跟紧这个路线就行。我是利威尔xu，真心建议你把这篇点赞收藏了，顺手关注一下，下一篇更新你第一时间就能跟上，咱们评论区见。
💡 本章面试要点
- 工具描述写法：讲清能干啥不能干啥，带输入输出和边界，正反例子越具体误调越少。
- 参数校验位置：放在 harness 里硬拦，不指望模型自觉，类型必填枚举长度全得查。
- 权限与幂等：读写真删三级管，写操作必须带幂等键，同样活儿干两次只算一次。
- 重试分层：参数错直接回灌重想，可重试退避再来，致命错换路或回滚，重试必须有上限。
- 工具选择策略：粗筛加分组加按需加载，别全塞 prompt，可解释比花哨重要。
- 结果回灌三件套：裁剪加摘要加索引，带状态一起喂，敏感字段记得脱敏。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/2604_97047541/article/details/167701926
