1. 为什么工具调用是 Agent 从玩具到生产力的分水岭很多人做 Agent 做到第七篇就卡住了模型能聊天、能规划、能输出漂亮的 JSON但一到真正干活就露馅——它没法查天气、没法读文件、没法调接口只能靠训练数据里那点陈旧知识硬编。这就是会说不会做的典型症状。工具调用Tool Calling解决的正是这个问题让模型在推理过程中主动声明我需要调用某个函数由外部执行环境真正跑一遍再把结果喂回模型继续推理。这一圈走通Agent 才算长出手脚。我见过太多项目在execute这一步翻车。有人把工具执行写成同步阻塞模型一调外部接口整个 Agent 就卡死有人不做参数校验模型幻觉出一个不存在的字段直接让后端 500还有人忘了把执行结果按协议格式回传模型收到一堆裸文本直接懵掉。这些坑我在下面会一个个拆开讲。这篇内容适合三类人一是跟着 Agent 系列一路做下来、准备给 Agent 接真实能力的开发者二是被failed to execute这类报错折磨过、想搞清执行链路到底哪一环出问题的人三是正在选型 Agent 框架、想弄明白ToolCall、AgentTool这些概念背后到底怎么落地的人。读完你应该能自己从零写出一套可用的工具调用层而不是只会调别人封装好的黑盒。2. 工具调用的整体设计与核心思路拆解2.1 一次完整的工具调用到底经历了什么先把链路讲清楚不然后面全是空中楼阁。一次标准的工具调用分五个阶段工具注册把可用工具的元信息名称、描述、参数 schema告诉模型。这一步决定了模型知不知道有这个工具。模型决策模型在生成回复时如果判断需要外部能力就输出一个结构化的调用请求而不是普通文本。这个请求通常包含工具名和参数。调用解析Agent 运行时解析模型输出识别出这是一个工具调用意图提取工具名和参数。实际执行运行时找到对应工具函数校验参数执行拿到结果或异常。结果回传把执行结果按协议格式塞回对话历史再次请求模型让它基于结果继续推理。这五步里第 2 步和第 5 步是模型侧的事第 1、3、4 步是工程侧的事。绝大多数 bug 都出在工程侧——因为模型侧的行为你控制不了只能约束和兜底。2.2 为什么用结构化 ToolCall 而不是让模型输出文本再解析早期很多人图省事让模型输出类似调用 get_weather(北京)这样的文本然后用正则去抠。我实测下来这套方案在 demo 阶段能跑一上生产就崩。原因有三个格式不稳定模型今天用双引号明天用单引号后天加个好的我来帮你调用正则根本兜不住。参数类型丢失文本里true和true分不清数字和字符串混在一起解析出来还得猜。无法表达复杂结构嵌套对象、数组参数用文本表达极其容易出错。所以现在主流做法都是让模型直接输出结构化的ToolCall对象参数用 JSON Schema 约束。模型厂商在训练时就强化了这种输出格式稳定性比自由文本高一个数量级。你要做的就是把 schema 定义清楚剩下的交给模型。2.3 工具描述写得好不好直接决定调用成功率这是最容易被忽视、但性价比最高的一环。模型选不选某个工具、参数填得对不对几乎全看你写的工具描述。我踩过的坑是描述写得太简略模型压根不知道这工具能干嘛描述写得太啰嗦模型又被干扰。我的经验是描述要包含四要素做什么、什么时候用、参数含义、返回什么。举个例子一个查订单的工具差的描述是查询订单好的描述是根据订单号查询订单的当前状态和物流信息当用户询问订单进度、是否发货、预计到达时间时使用。参数 order_id 为 18 位数字字符串返回状态码和物流节点列表。后者能让模型调用准确率明显提升。参数 schema 也要写description别偷懒。模型对参数的理解完全依赖这个字段。一个status参数如果不写清楚取值范围模型可能填已完成也可能填completed后端直接挂掉。3. 核心细节解析与实操要点3.1 工具注册的数据结构怎么设计工具注册本质上是给模型一份能力清单。我一般用一个统一的注册表来管理每个工具包含这些字段字段作用注意事项name工具唯一标识用下划线命名别用中文和特殊字符description功能描述决定模型是否选用必须写清楚使用场景parameters参数 JSON Schema每个参数都要有 type 和 descriptionhandler实际执行函数接收解析后的参数返回结果timeout超时时间外部调用必须设防止卡死retry重试策略幂等操作才重试写操作慎用这里有个细节name一定要稳定别今天叫get_weather明天改成query_weather。模型在对话历史里可能引用了旧名字改名会导致调用失败。如果非要改做好别名映射。3.2 参数校验为什么不能省模型幻觉是常态不是异常。它可能给你传一个不存在的参数、传错类型、传空值。如果你直接把参数透传给后端轻则报错重则产生脏数据。我的做法是在执行前做三层校验必填校验schema 里标了 required 的参数缺一个直接返回错误给模型让它重新生成。类型校验数字、字符串、布尔、数组、对象类型不对就拒绝。业务校验比如订单号必须是 18 位、日期不能是过去时这些 schema 表达不了的在 handler 里做。校验失败时不要抛异常中断整个流程而是把错误信息作为工具结果回传给模型。模型看到参数 order_id 格式错误应为 18 位数字之后大概率会自己修正重试。这比直接崩掉体验好太多。3.3 执行结果的格式约定结果回传格式不统一是导致模型看不懂执行结果的头号原因。我建议统一成这样的结构{ success: true, data: { ... }, error: null }失败时{ success: false, data: null, error: 订单不存在请确认订单号是否正确 }关键点是error字段要写人话因为它是给模型看的模型会基于这句话决定下一步。写Error 500模型一脸懵写订单不存在请确认订单号模型就知道该让用户核对订单号了。注意结果里不要塞超大文本。有些工具返回几万字的日志直接回传会撑爆上下文窗口还会稀释模型的注意力。该截断就截断该摘要就摘要。3.4 同步还是异步这是个架构问题工具执行分同步和异步两种。同步就是调用后阻塞等结果异步是发起后继续做别的、结果回来再处理。对于单轮对话式 Agent同步就够了逻辑简单。但如果你的 Agent 要并发调多个工具或者工具体是耗时操作比如跑一个几分钟的数据分析就必须上异步。我踩过的坑早期用同步方式调一个外部接口接口偶尔抽风要 30 秒才返回整个 Agent 就卡在那里用户以为死机了。后来加了超时和异步体验立刻不一样。超时是必须的异步是推荐的尤其是工具体涉及网络请求的时候。4. 实操过程与核心环节实现4.1 从零搭一个工具注册与执行的最小闭环先定义工具注册表。我用 Python 举例思路通用class ToolRegistry: def __init__(self): self.tools {} def register(self, name, description, parameters, handler, timeout10): self.tools[name] { name: name, description: description, parameters: parameters, handler: handler, timeout: timeout, } def get_schema(self): return [ { name: t[name], description: t[description], parameters: t[parameters], } for t in self.tools.values() ] def execute(self, name, arguments): if name not in self.tools: return {success: False, error: f工具 {name} 不存在} tool self.tools[name] try: result tool[handler](**arguments) return {success: True, data: result, error: None} except Exception as e: return {success: False, data: None, error: str(e)}这段代码看着简单但每个设计点都有讲究。get_schema返回的是给模型看的清单只暴露必要字段handler这种内部实现不暴露。execute里做了工具存在性检查和异常兜底保证任何工具出错都不会让整个 Agent 崩掉。4.2 注册一个真实工具并跑通调用注册一个查天气的工具def get_weather(city: str, unit: str celsius): # 实际项目里这里是真实 API 调用 mock_data {北京: 25, 上海: 28, 广州: 30} temp mock_data.get(city) if temp is None: raise ValueError(f暂不支持查询 {city} 的天气) if unit fahrenheit: temp temp * 9 / 5 32 return {city: city, temperature: temp, unit: unit} registry.register( nameget_weather, description查询指定城市的当前天气温度。当用户询问某地天气、气温时使用。, parameters{ type: object, properties: { city: { type: string, description: 城市名称如 北京、上海, }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认摄氏度, }, }, required: [city], }, handlerget_weather, )注意unit参数用了enum约束这样模型只会从两个值里选不会瞎填。required只标了city因为unit有默认值。这些细节直接决定调用成功率。4.3 解析模型返回的 ToolCall模型返回的调用请求结构因厂商而异但核心都是工具名加参数。以常见的结构为例def parse_tool_call(model_output): # model_output 里可能包含 tool_calls 字段 tool_calls model_output.get(tool_calls, []) parsed [] for call in tool_calls: parsed.append({ id: call[id], name: call[function][name], arguments: json.loads(call[function][arguments]), }) return parsed这里有个坑arguments是 JSON 字符串需要json.loads解析。但模型偶尔会输出非法 JSON比如多一个逗号、少一个引号。所以解析要包 try-except解析失败时把原始字符串和错误信息回传给模型让它重试而不是直接崩。4.4 把执行结果回传并驱动下一轮推理执行完工具后要把结果按协议格式追加到对话历史def build_tool_result_message(call_id, result): return { role: tool, tool_call_id: call_id, content: json.dumps(result, ensure_asciiFalse), }tool_call_id必须和模型发起的调用 id 对应上否则模型不知道这个结果是回应哪次调用的。多工具并发调用时这个 id 就是唯一的关联键。回传后再次请求模型模型就会基于结果生成最终回复。整个闭环跑通后你会看到模型先输出一个工具调用执行后拿到结果再输出北京现在 25 摄氏度这样的自然语言回复。这一圈走通Agent 就真正能干活了。4.5 多工具并发调用的处理当模型一次返回多个工具调用时可以并发执行提升效率import concurrent.futures def execute_tool_calls(tool_calls): results [] with concurrent.futures.ThreadPoolExecutor(max_workers5) as executor: future_map { executor.submit(registry.execute, c[name], c[arguments]): c for c in tool_calls } for future in concurrent.futures.as_completed(future_map): call future_map[future] result future.result() results.append(build_tool_result_message(call[id], result)) return results并发执行要注意两点一是线程安全注册表读取是只读的没问题但 handler 内部如果有共享状态要加锁二是结果顺序回传时顺序不重要因为每个结果都带tool_call_id模型能对上号。5. 常见问题与排查技巧实录5.1 模型不调用工具只输出文本怎么办这是新手最常遇到的问题。模型明明有工具可用却直接编了个答案。排查顺序如下检查工具描述是不是写得太模糊模型没意识到该用。把使用场景写具体。检查系统提示有没有明确告诉模型需要外部信息时必须调用工具不要编造。检查工具数量工具太多超过 20 个会让模型选择困难考虑分组或按场景动态加载。检查模型能力不是所有模型都支持工具调用确认你用的模型有这个能力。我实测下来把工具描述和使用场景写清楚加上系统提示的约束不调用的问题能解决八成。5.2 参数填错、类型不对怎么兜底模型填错参数是常态。除了前面说的三层校验我还会在错误信息里给出明确指引。比如模型传了city: 123返回参数 city 应为字符串类型的城市名称如 北京模型下一轮大概率会改成正确的。关键是错误信息要可操作别只说参数错误。5.3 执行超时和异常怎么处理外部调用超时是必然事件不是意外。我的处理策略是场景处理方式网络超时返回调用超时请稍后重试让模型决定是否重试接口报错返回具体错误信息模型可据此调整参数参数校验失败返回校验错误引导模型修正工具不存在返回可用工具列表让模型重新选择注意写操作下单、转账失败后不要自动重试可能造成重复操作。读操作可以重试。5.4 上下文被工具结果撑爆怎么办工具返回大结果时直接塞进上下文会出问题。我的做法是结果超过一定长度比如 2000 字符就截断并在末尾加结果已截断。如果模型需要完整结果让它用更精确的参数重新调用。另一种做法是把大结果存到外部只回传一个引用 id 和摘要模型需要细节时再调工具取。5.5 常见报错速查表报错关键词可能原因排查方向failed to executehandler 抛异常看 handler 内部日志确认参数和依赖tool not found工具名不匹配检查注册名和模型输出的名字是否一致invalid arguments参数 JSON 解析失败打印原始 arguments 字符串看格式timeout执行超时检查外部依赖调大 timeout 或改异步context length exceeded上下文超限截断工具结果或精简历史这些报错我在不同项目里都遇到过排查思路基本通用。核心原则是任何工具执行失败都不能让 Agent 整体崩掉要把错误变成模型能理解的信息回传。6. 工具调用的安全边界与工程化建议6.1 权限控制不能只靠模型自觉模型可能被诱导调用不该调用的工具。比如一个删除文件的工具如果模型被用户话术带偏可能真的去删。所以权限控制必须在工程侧做不能指望模型。我的做法是给工具打权限标签执行前检查当前会话是否有权限没有就直接拒绝并返回无权限执行此操作。敏感工具还要加二次确认让用户明确授权后才执行。6.2 工具粒度怎么把握工具粒度太粗模型不好用太细模型要调很多次。我的经验是一个工具做一件事但这件事要有业务意义。比如查订单是一个工具而不是查订单状态查订单物流查订单金额三个工具。粒度合适时模型一次调用就能拿到完整信息减少往返。6.3 日志和可观测性工具调用必须打日志记录谁调的、调了什么、参数是什么、结果是什么、耗时多少。出问题时这些日志就是救命稻草。我一般会记录调用链 id把一次对话里的所有工具调用串起来方便回溯。没有日志的 Agent 系统排查问题基本靠猜。6.4 工具版本管理工具会迭代参数会变。如果直接改现有工具可能影响正在跑的会话。我的做法是工具名带版本号比如get_weather_v2新会话用新版本老会话继续用老版本平滑过渡。等老会话都结束了再下线老版本。7. 我在实际项目里踩过的几个坑第一个坑是忘了给工具设超时。有个查数据库的工具某次慢查询跑了 60 秒整个 Agent 卡死用户端一直转圈。后来所有工具强制设超时默认 10 秒外部接口 30 秒超时就走错误回传。第二个坑是工具描述里写了内部实现细节。比如描述里写调用内部 API /v1/order/query模型有时候会把这个路径当参数传进来。工具描述是给模型看的只写业务语义别写技术细节。第三个坑是结果回传格式不统一。早期有的工具返回字符串有的返回字典模型处理起来很混乱。统一成{success, data, error}结构后模型的理解准确率明显提升。第四个坑是并发调用时的结果错位。多工具并发时如果按完成顺序回传模型可能对不上号。后来每个结果都带tool_call_id问题解决。这些坑说到底都是工程细节但正是这些细节决定了一个 Agent 是能演示还是能上线。工具调用这一层做扎实了后面接记忆、接多 Agent 协作才有稳固的地基。我个人的体会是别急着堆功能先把这一圈调用闭环打磨到稳定比什么都重要。