1. 工具调用Agent 从“会说”到“会做”的分水岭很多人做 Agent 做到第七篇的时候手里已经有一个能聊天、能记住上下文、能按角色设定回复的“对话体”了。但只要你稍微往真实场景里推一步立刻就会发现一个尴尬的事实它除了说话什么都干不了。你问它“帮我查一下今天北京的天气”它会一本正经地编一个温度给你你让它“把这段代码跑一下”它会告诉你“我无法直接执行代码”。这不是 Agent这只是一个套了壳的聊天机器人。工具调用Tool Calling / Function Calling就是那道分水岭。它让 Agent 第一次拥有了“手”——能去查真实数据、能去操作外部系统、能去执行具体动作。从架构上讲工具调用把 Agent 从“纯文本生成器”升级成了“决策 执行”的闭环系统。这个转变的意义比很多人想象的要大得多。我见过不少刚入门的朋友卡在工具调用这一环很久。不是概念不懂而是一到落地就出问题模型不调用工具、调用了但参数传错、工具执行报错后 Agent 直接崩掉、多个工具之间不知道怎么编排。这些问题在文档里往往一笔带过但在实际项目里每一个都能让你调半天。这篇就把我从零构建 Agent 系列第八篇的完整思路和踩坑记录摊开讲从设计原则到代码落地从单工具到多工具编排尽量把每个“为什么”都说清楚。适合谁看如果你已经写过一个能对话的 Agent现在想让它真正干活这篇就是为你准备的。如果你还没写过 Agent建议先把前面的对话循环和上下文管理搞定否则工具调用会让你更晕。下面所有代码示例我用 Python 写但思路是跨语言的你用任何框架都能套。2. 工具调用的整体设计与核心思路拆解2.1 为什么工具调用不是“加个 API 请求”那么简单初学者最容易犯的错是把工具调用理解成“模型输出一个函数名我去执行然后把结果拼回去”。这个理解在 demo 阶段能用但一上真实场景就散架。原因在于模型并不知道你的工具有什么、参数长什么样、什么时候该调、调失败了怎么办。这些信息全部需要你在系统层面设计好再通过提示词和结构化输出喂给模型。所以工具调用的本质是一套协议设计。你要定义清楚三件事工具的描述格式模型怎么知道有这个工具、调用的触发机制模型怎么表达“我要调这个”、结果的回传格式执行完怎么告诉模型。这三件事任何一件没设计好Agent 就会表现得像个“听不懂指令的新人”。我个人的经验是把工具调用拆成四个层次来看思路会清晰很多描述层每个工具的名称、用途、参数 schema这是给模型看的“说明书”决策层模型根据用户意图和工具说明决定调不调、调哪个、传什么参数执行层你的代码真正去执行工具处理超时、异常、权限回传层把执行结果成功或失败结构化地塞回对话历史让模型继续推理很多人只做了决策层和执行层忽略了描述层和回传层的设计结果就是模型乱调、调完不知道怎么接。下面逐个拆。2.2 工具描述模型能不能用对工具八成看这里工具描述写得好不好直接决定模型调用准确率。我做过对比测试同一个工具描述写得粗糙和写得精细调用成功率能差出 40% 以上。什么叫写得精细不是堆形容词而是把“什么时候用、什么时候不用、参数什么含义、边界在哪”都说清楚。举个例子一个查询天气的工具粗糙的描述是“查询天气”。精细的描述是“查询指定城市当天的天气情况包括温度、湿度、风力。仅用于查询实时天气不用于历史天气或未来预报。城市参数使用中文城市名如‘北京’‘上海’”。后者模型一看就知道边界不会拿它去查历史数据。参数 schema 同样关键。用 JSON Schema 定义参数类型、是否必填、取值范围模型会严格遵守。我习惯给每个参数都写 description哪怕参数名已经很明显。因为模型对参数名的理解可能和你想的不一样加一句说明能省掉大量调试时间。提示工具描述里不要出现“可能”“大概”这类模糊词模型会跟着模糊。用确定的、指令性的语言。2.3 调用触发结构化输出是唯一靠谱的路早期有人用正则去解析模型输出里的函数名这种做法在 demo 里能跑生产环境必崩。因为模型的自然语言输出格式不稳定今天用call: get_weather明天可能变成Ill call get_weather。正确做法是用模型厂商提供的结构化工具调用能力比如 OpenAI 的 tools 参数、Anthropic 的 tool_use 块让模型直接输出结构化的调用请求而不是让你去猜。如果用的模型不支持原生工具调用退而求其次的方案是强制 JSON 输出在提示词里明确要求“只输出 JSON格式为 {tool, args}”。但这种方式稳定性差一些需要加校验和重试。我的建议是能用原生工具调用就用原生省心太多。2.4 结果回传失败也是一种有效信息新手常犯的另一个错是工具执行失败后直接抛异常整个 Agent 挂掉。正确的做法是把失败信息也结构化回传给模型让它自己决定下一步。比如工具返回{status: error, message: 城市名无效}模型看到后可能会换个城市名重试或者告诉用户“这个城市我没查到”。这就是 Agent 和普通程序的区别普通程序遇到错误要中断Agent 遇到错误要能“思考着继续”。所以回传层要设计成统一的格式成功和失败都走同一个通道模型才能一致地处理。3. 核心细节解析与实操要点3.1 工具注册表把工具管起来当工具只有一两个时你可以硬编码。但一旦超过五个就需要一个注册表来管理。注册表的作用是统一注册工具、统一生成描述、统一分发调用。我通常用一个字典结构key 是工具名value 包含描述、参数 schema、执行函数。TOOL_REGISTRY {} def register_tool(name, description, parameters): def decorator(func): TOOL_REGISTRY[name] { name: name, description: description, parameters: parameters, func: func } return func return decorator register_tool( nameget_weather, description查询指定城市当天实时天气仅用于实时天气查询, parameters{ type: object, properties: { city: {type: string, description: 中文城市名如北京} }, required: [city] } ) def get_weather(city): # 实际查询逻辑 return {status: success, data: {...}}这样设计的好处是新增工具只需要加一个装饰器描述和 schema 自动进入给模型的工具列表不用手动维护两份。我踩过的坑是早期把描述写在两个地方改了一处忘了另一处导致模型拿到的描述和实际执行对不上调了半天才发现。3.2 参数校验别信模型传的参数模型传的参数不一定合法。它可能传个空字符串、传个不存在的城市、传个超出范围的数字。所以执行前必须校验。校验分两层一层是 schema 层面的类型校验一层是业务层面的合法性校验。类型校验可以用jsonschema库自动做业务校验得自己写。比如城市名要在你的支持列表里数字要在合理区间。校验失败不要抛异常而是返回结构化的错误信息给模型。我一般返回{status: error, message: 具体原因}模型看到原因后往往能自己纠正。注意校验失败的信息要具体不要只说“参数错误”。说“城市名‘北金’不在支持列表中请使用标准中文城市名”模型纠正的成功率会高很多。3.3 超时与重试工具调用不能无限等外部工具调用可能很慢甚至卡死。如果不设超时整个 Agent 就挂在那了。我给每个工具调用都设超时一般 10 到 30 秒看工具性质。超时后返回{status: error, message: 调用超时}让模型决定是重试还是放弃。重试要谨慎。读操作查询类可以自动重试一两次写操作下单、发消息绝对不能自动重试否则可能重复执行。这个区分很重要我见过有人给所有工具都加了自动重试结果用户被重复扣款这是生产事故。3.4 多工具编排模型自己会排序当你有多个工具时不需要你手动编排顺序模型会根据用户意图自己决定先调哪个后调哪个。比如用户说“查一下北京天气如果下雨就提醒我带伞”模型会先调天气工具拿到结果后判断是否下雨再决定要不要调提醒工具。这个能力是模型自带的你要做的是把工具描述写清楚让模型知道每个工具能干什么。但有个坑模型有时会并行调用多个工具如果你的工具之间有依赖关系并行会出问题。解决办法是在工具描述里写明依赖比如“此工具必须在获取用户 ID 之后调用”。模型看到这种说明会乖乖按顺序来。4. 实操过程与核心环节实现4.1 完整调用循环的代码骨架下面是一个完整的工具调用循环我把它拆成几个关键步骤。这个骨架我用了很多次稳定可靠。def run_agent(user_input, max_turns10): messages [{role: user, content: user_input}] for turn in range(max_turns): # 1. 调用模型带上工具列表 response call_model(messages, toolsget_tool_schemas()) # 2. 如果模型没有调用工具直接返回文本 if not response.tool_calls: return response.content # 3. 把模型的调用请求加入历史 messages.append(response.message) # 4. 逐个执行工具 for tool_call in response.tool_calls: result execute_tool(tool_call) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result) }) return 达到最大轮次限制这个循环的核心是max_turns防止模型陷入无限调用。我一般设 10 轮够处理绝大多数场景。如果 10 轮还没结束说明要么工具描述有问题要么用户意图太模糊需要人工介入。4.2 execute_tool 的完整实现execute_tool是执行层的核心要处理查找、校验、超时、异常。def execute_tool(tool_call): name tool_call.function.name args json.loads(tool_call.function.arguments) # 查找工具 if name not in TOOL_REGISTRY: return {status: error, message: f未知工具 {name}} tool TOOL_REGISTRY[name] # 参数校验 try: jsonschema.validate(args, tool[parameters]) except jsonschema.ValidationError as e: return {status: error, message: f参数错误{e.message}} # 执行带超时 try: result run_with_timeout(tool[func], args, timeout15) return {status: success, data: result} except TimeoutError: return {status: error, message: 工具执行超时} except Exception as e: return {status: error, message: f执行失败{str(e)}}这里每个分支都返回结构化结果模型拿到后能继续推理。我特别强调run_with_timeout这个包装Python 里可以用concurrent.futures实现别用信号量那套跨平台容易出问题。4.3 参数计算与选择以天气工具为例假设天气工具需要经纬度而不是城市名但用户只给了城市名。这时候有两种方案一是让模型自己转换二是加一个地理编码工具。我选后者因为模型转换经纬度经常出错。于是工具链变成先调geocode把城市名转经纬度再调get_weather查天气。模型看到两个工具的描述会自动先调 geocode。这就是多工具编排的典型场景。参数传递上geocode 返回的经纬度要能被 get_weather 接收所以两个工具的 schema 要设计成兼容的。我实测下来这种链式调用模型处理得很好前提是每个工具的描述里写清楚输入输出。比如 geocode 的描述里写“返回经纬度可用于天气查询工具”模型就知道怎么串了。4.4 实操现场记录一次完整的天气查询用户输入“北京今天天气怎么样”。第一轮模型返回 tool_callget_weather({city: 北京})。执行层查到北京天气返回{status: success, data: {temp: 25, condition: 晴}}。第二轮模型拿到结果生成回复“北京今天晴气温 25 度”。整个过程两轮结束耗时不到 3 秒。如果用户输入“北京今天适合穿什么”模型会先调天气拿到温度后再结合自己的知识给出穿衣建议。这里没有第二个工具模型直接用推理完成。所以工具调用不是越多越好能用推理解决的就不调工具这样更快也更省。5. 常见问题与排查技巧实录5.1 模型不调用工具怎么办这是最高频的问题。原因通常有三个工具描述不清楚、提示词没引导、模型能力不够。排查顺序是先看描述再看提示词最后换模型。描述问题最常见。比如工具名叫query描述是“查询数据”模型根本不知道查什么数据。改成query_order_status描述“根据订单号查询订单当前状态”调用率立刻上去。提示词方面可以在系统提示里加一句“当用户问题涉及实时数据时优先使用工具查询不要凭记忆回答”。如果都改了还不调可能是模型本身工具调用能力弱。换个支持原生工具调用的模型问题往往迎刃而解。5.2 参数传错怎么排查参数传错的表现是工具执行报错或者返回结果不对。排查方法是把模型传的原始参数打印出来和 schema 对比。常见错误有类型不对传了字符串但 schema 要数字、字段名拼错、必填字段缺失。我遇到最多的是日期格式。模型可能传2024-1-1但你的工具要2024-01-01。解决办法是在参数 description 里写明格式比如“日期格式 YYYY-MM-DD”。写清楚后基本不会再错。5.3 工具执行失败后 Agent 卡住这通常是回传层没设计好。如果工具失败后你返回的是空或者抛异常模型拿不到有效信息就不知道下一步怎么办。正确做法是返回结构化的错误让模型看到“哦失败了原因是这个”。模型往往会自己重试或换方案。还有一种情况是模型反复调同一个失败的工具陷入死循环。这时候max_turns就起作用了到轮次上限强制退出。同时你可以在错误信息里加一句“请勿重复调用此工具”模型看到会停止。5.4 常见问题速查表问题现象可能原因排查方向解决手段模型不调工具描述不清检查工具描述和参数说明细化描述加使用场景参数类型错schema 不严对比传入值和 schema加类型校验和格式说明执行超时工具太慢看工具本身耗时加超时返回错误让模型决策死循环调用失败信息不明看回传内容返回具体错误加轮次上限多工具顺序乱依赖没写明检查工具描述在描述里写明依赖关系5.5 独家避坑技巧第一个技巧给工具加“使用示例”。在描述里写一个调用示例比如“示例get_weather({city: 北京})”模型模仿能力很强看到示例后调用准确率明显提升。第二个技巧工具数量控制在 10 个以内。工具太多模型会挑花眼调用准确率下降。如果确实需要很多工具可以分组每组给一个“路由工具”先让模型选组再选具体工具。第三个技巧日志要记全。每次工具调用的输入、输出、耗时都记下来出问题时这是唯一的排查依据。我习惯用结构化日志方便后续分析哪些工具调用失败率高。第四个技巧给写操作加确认。涉及下单、发消息、改数据的工具执行前让模型先向用户确认用户同意后再执行。这个在提示词里加一句“执行写操作前必须先征得用户同意”就能实现。6. 工具调用的安全边界与扩展方向6.1 权限控制不是所有工具都能随便调工具调用打开了 Agent 的操作能力也打开了风险。一个能执行 shell 命令的工具如果被恶意提示词诱导可能造成严重后果。所以权限控制必须做。我的做法是给工具分级只读工具查询类可以直接调写工具修改类需要确认危险工具执行命令、删除数据需要额外授权。授权可以是用户显式确认也可以是白名单机制。比如 shell 工具只允许执行特定命令其他一律拒绝。这个分级在注册工具时就标记好执行层根据级别决定是否放行。别等到出事才想起来加那时候已经晚了。6.2 工具调用的可观测性Agent 调了哪些工具、传了什么参数、花了多久、成功还是失败这些信息必须可观测。否则线上出问题你两眼一抹黑。我一般用 OpenTelemetry 做链路追踪每次工具调用是一个 span记录输入输出和耗时。这样能清楚看到瓶颈在哪、哪个工具失败率高。对于调试阶段简单的日志就够了。但上生产一定要有完整的可观测性这是血的教训。我曾经有个工具偶发超时没有监控用户投诉了才发现排查花了整整一天。6.3 从单 Agent 到多 Agent 的工具共享当系统扩展到多个 Agent 时工具怎么共享是个问题。我的方案是工具注册表做成全局的每个 Agent 按需订阅自己需要的工具子集。这样工具只维护一份Agent 各取所需。多 Agent 协作时一个 Agent 调用的工具结果可能需要传给另一个 Agent。这时候工具调用的结果要能被序列化传递所以回传格式统一很重要。我坚持用{status, data/message}的格式就是为了跨 Agent 传递时不出错。6.4 工具调用的性能优化工具调用是 Agent 响应时间的大头。优化方向有几个一是并行调用无依赖的工具模型支持并行工具调用时一次返回多个 tool_call你并行执行能省不少时间二是缓存高频查询结果比如天气查同一个城市短时间内可以复用三是给工具本身做优化比如数据库加索引、外部 API 加连接池。我实测过把三个无依赖的查询工具改成并行执行整体响应时间从 4 秒降到 1.5 秒。这个提升在用户体验上是质变的。6.5 后续可以怎么扩展工具调用跑通后下一步可以往几个方向走。一是加工具调用的评估统计每个工具的调用成功率、平均耗时持续优化描述。二是加动态工具根据用户权限动态决定给模型看哪些工具。三是加工具组合把常用的工具链封装成一个复合工具减少模型编排负担。我个人在实际操作中的体会是工具调用这一块描述设计占七分代码实现占三分。很多人把精力花在写执行逻辑上忽略了描述结果模型用不好工具还以为是模型不行。把描述当产品文档来写把模型当新员工来带工具调用的成功率自然就上去了。