工具调用与函数调用：Schema设计、错误恢复、幂等性和安全边界
摘要
本文把工具调用和函数调用解释为一套受控执行系统，而不是模型输出 JSON 的技巧。Schema 设计、参数来源、错误恢复、幂等性、安全边界和提示注入防护共同决定模型能否从“会说”走向“会办事”。文章强调，模型只能提出调用意图，真正执行权必须保留在应用和业务系统中；高风险动作要拆分为可审计的工具、可验证的参数和可恢复的状态。工具调用的生产价值，不在工具数量多，而在模型、接口和权限之间形成清晰契约。
关键词
工具调用；函数调用；JSON Schema；幂等性；错误恢复；参数追溯；提示注入；安全边界
研究问题与方法
本文研究的问题是：怎样设计一个让模型能可靠使用外部能力、又不会越权制造事故的执行层。方法上，文章把一次工具调用拆成意图识别、工具选择、参数生成、系统校验、执行、错误分类、结果观察和最终回应八个阶段；每个阶段都分析模型适合承担什么，系统必须控制什么。这样可以避免把“模型生成函数名”误认为“业务动作已经安全成立”。
下面的状态图展示一次可恢复工具调用的生命周期。它服务于幂等和审计：失败不是异常文本，而是明确状态；重试不是盲目再跑，而是基于错误类型和幂等键继续。
幂等性可以用状态转移约束表达：
其中 是业务动作， 是幂等键， 是当前状态。公式表达的不是数学优雅，而是生产原则：同一个已确认动作被重复提交时，系统应该返回同一结果，而不是再次产生副作用。
工具调用让大模型从“会回答”走向“会办事”。模型不再只生成一段文字，而是能根据任务选择搜索、查库、写文件、发请求、运行代码、创建工单、查询订单或触发业务流程。函数调用是其中最常见的工程形态：系统把可调用能力描述成结构化接口，模型输出函数名和参数，应用再执行真实函数，并把结果交回模型继续推理。这个过程看起来像一次普通接口调用，实际却是一套人、模型、工具、权限和业务状态共同参与的执行系统。
很多团队第一次接入工具调用时，会把注意力放在“模型能不能吐出 JSON”。这只是入口。真正的难点在后面：Schema 是否能表达业务边界，错误能不能被恢复，重复调用会不会产生副作用，模型是否能被工具结果纠偏，高风险动作是否有确认和审计，工具返回是否会被提示注入污染，调用链是否能在失败后给用户一个可执行的下一步。一个生产级工具调用系统，不能靠提示词祈祷模型“别乱来”，而要用接口设计、状态管理和权限控制把模型放进清楚的工作边界里。
引言：先分清工具调用、函数调用和结构化输出
函数调用通常指模型根据开发者提供的函数说明，生成某个函数的名称和参数。应用收到后，自己决定是否执行。工具调用范围更宽，工具可以是函数、检索器、浏览器、代码执行器、文件系统、数据库、工作流节点、MCP 服务或外部业务系统。结构化输出强调模型输出必须符合某个 JSON Schema 或类似约束，它不一定会触发外部动作，也可以用于抽取字段、生成配置、分类任务或填写表单。
三者在工程上经常叠在一起。一次客服工单处理可能先用结构化输出判断意图，再用函数调用查询订单，再用工具调用创建售后记录，最后生成给用户看的回复。一次代码 Agent 可能先结构化拆解任务，再调用文件读取工具、测试工具和版本控制工具。一次数据分析可能先让模型生成查询参数，再由后端执行 SQL，最后把聚合结果交回模型解释。概念分清，是为了在不同风险点使用不同控制方式。
函数调用的核心不是让模型直接执行代码，而是让模型表达“我需要调用哪个能力，以及需要哪些参数”。执行权仍在应用。这个分界很重要：模型输出是建议，系统执行才是事实。应用应校验参数、检查权限、判断风险、写入日志、处理错误，必要时要求用户确认。不能因为模型返回了一个函数名，就默认它已经具备执行资格。
结构化输出适合要求稳定格式的场景，例如发票字段抽取、会议纪要任务列表、RAG 答案引用、审核结果、推荐理由分层等。工具调用适合需要外部事实或改变状态的场景，例如查库存、查账户、发送通知、修改配置、创建资源。不要把所有结构化输出都包装成工具，也不要让所有工具都承担复杂推理。好系统会把“格式约束”和“现实动作”分开设计，再在编排层连接起来。
对中文应用来说，函数调用还要处理业务词汇和用户表达之间的差异。用户说“帮我退一下昨天那单”，系统真正需要的是订单查询、身份校验、可退判断、退款创建、状态通知。工具不是把自然语言原样传给后端，而是把自然语言转成可审计、可校验、可恢复的业务动作。模型负责理解和决策，系统负责边界和执行。
Schema不是字段清单，而是业务契约
很多失败的工具调用，表面是模型参数填错，根因是 Schema 没有把任务说清楚。一个函数如果只有 query、text、data 这类泛字段，模型只能猜；一个函数如果暴露内部表名、枚举码、数据库列名，模型会把实现细节当成用户语义；一个函数如果把多个动作塞进一个参数对象，调用结果就很难校验。Schema 不是给模型看的接口注释，而是模型、应用和业务之间的契约。
好 Schema 的第一条原则是动作清晰。函数名应该表达可观察的业务动作，例如 search_policy_documents、get_order_refund_eligibility、create_support_ticket_draft、run_project_tests。避免 handle_request、process_data、execute_action 这种黑箱名字。模型选择工具时依赖名称和说明，名称越像真实动作，越能减少误选。说明文字要讲清“什么时候用”和“什么时候不用”，而不是只重复函数名。
第二条原则是参数少而具体。每个参数都应该有明确含义、类型、约束和示例。能用枚举就不要让模型自由写字符串，能用布尔值就不要用“yes/no/maybe”，能用对象数组就不要让模型拼接文本。日期要明确时区和格式，金额要明确币种和最小单位，文件路径要明确允许范围，用户 ID 要说明来源，分页参数要有上限。模型最怕模糊参数，系统最怕不可验证参数。
第三条原则是把必填和可选分干净。必填字段代表动作无法成立的最低信息，可选字段代表质量或范围增强。不要为了让模型更容易调用而把关键字段都设成可选，也不要把一堆不影响执行的字段设成必填。比如退款资格查询必须有订单标识和用户身份上下文，但不一定需要用户写明退款原因；创建正式退款可能必须有原因、金额、确认令牌和幂等键。不同风险动作应该拆成不同工具，而不是让一个工具靠可选字段变身。
第四条原则是使用面向业务的枚举。不要把数据库中的 status=2 暴露给模型，应使用 pending_payment、paid、shipped、refund_requested 这类可理解值。枚举说明要包含业务含义和限制。模型看到“状态 2”不会天然知道它能否退款，看到“已发货但未签收”才有机会选择正确流程。工具层再把业务枚举映射到内部系统。
第五条原则是把风险等级写进接口边界。只读工具、草稿工具、预演工具、正式提交工具应该分开。create_email_draft 和 send_email 不应是同一个函数靠 send=true 区分；preview_database_migration 和 apply_database_migration 不应混在一个参数里；quote_price 和 place_order 更不能只差一个布尔值。模型很容易在长任务中误填布尔开关，风险动作要有独立名称、独立权限和独立确认。
第六条原则是返回 Schema 同样重要。很多团队只设计入参，不设计返回值，工具执行后把原始 JSON、HTML、异常栈或数据库记录丢给模型。结果模型要么被噪声淹没，要么引用了内部字段，要么误解错误状态。返回值应该面向下一步推理：成功与否、关键结果、可引用证据、用户可见摘要、下一步可选动作、错误类型、是否可重试、是否需要人工。工具返回不是日志倾倒，而是模型继续工作的观察结果。
JSON Schema 的价值在于让接口约束可机器检查。类型、必填、枚举、数组长度、字符串格式、数值范围、对象附加字段限制，都能减少模型自由发挥空间。OpenAI 的结构化输出、Anthropic 的工具使用、Gemini 的函数调用和 LangChain 的工具封装都强调了类似思路：把可调用能力描述成模型能理解、系统能验证的结构。不同平台语法有差异，但工程原则相同。
Schema设计要避免“万能工具”
万能工具是工具调用系统里最诱人的陷阱。团队会创建一个 execute 工具，参数是 instruction，让模型把想做的事写进去，再由后端解释。短期看接入快，长期看风险大。万能工具没有清晰意图，没有可枚举动作，没有最小权限，没有稳定幂等键，也很难对参数做静态校验。它把工具调用退化成“模型给后端写小作文”。
万能工具常见于数据库、浏览器、Shell 和企业系统封装。比如给模型一个“执行 SQL”的工具，让它自己写查询；给模型一个“操作浏览器”的工具，让它自己点击；给模型一个“调用内部 API”的工具，让它自己填路径；给模型一个“运行命令”的工具，让它自己决定命令。某些开发辅助和沙盒场景确实需要低层工具，但生产业务不应把低层能力直接交给所有任务。
更稳妥的做法是分层。高频业务动作做成任务级工具，例如“查询订单可退金额”“创建售后草稿”“获取当前用户可见知识库片段”“运行指定测试套件并摘要失败”。低层工具保留给受控环境，例如只读诊断、开发沙盒、管理员调试，并配合权限、确认和审计。模型可以在任务级工具之间推理，而不是每次都从底层系统拼装动作。
万能工具还会破坏评测。一个明确工具可以统计选择准确率、参数准确率、错误恢复率、成功率和副作用率。万能工具只有一段自然语言，很难判断模型到底有没有按约束行动。评测不清楚，系统就难以迭代。生产级 Agent 要能回答：模型为什么选这个工具，参数来自哪里，工具是否可用，结果是否支持最终答复。
拆分工具并不意味着工具越多越好。工具太多，模型会选择困难，描述也会互相重叠。工具集合要围绕用户任务设计，而不是围绕后端接口机械映射。一个后端系统可能有几十个接口，但对模型暴露的工具应该是少量、语义稳定、边界清楚的动作。工具目录本身要经过产品设计。
判断工具粒度时，可以问四个问题：这个动作能否被用户理解；失败后能否给出明确恢复路径；是否有独立权限和风险等级；是否能独立记录审计日志。如果答案都是“是”，它适合成为单独工具。如果一个动作只是另一个工具内部的技术细节，就不该暴露给模型。
参数来源要可追溯
模型生成参数时，系统需要知道参数从哪里来。订单号来自用户输入、当前会话上下文、历史查询结果还是模型猜测？邮箱地址来自用户账户资料、上传文件还是模型根据姓名补全？日期范围来自用户明确指定，还是系统默认？如果参数来源不清楚，工具调用成功也可能是错的。
可追溯参数有助于降低幻觉。模型不能因为用户说“上次那笔”就凭空生成订单号，而应该先调用查询工具列出候选订单，再让用户确认或根据上下文选择。模型不能因为公司名相似就生成供应商 ID，而应该从系统搜索结果中引用 ID。工具参数越接近真实副作用，越应该来自可验证来源。
实践中可以给参数加来源元数据。应用内部记录 source=user_message、source=session_state、source=tool_result、source=default_policy、source=user_confirmation。这些元数据不一定展示给终端用户，但应进入审计和风险判断。正式提交类工具应要求关键参数来自用户确认或可信工具结果，而不是模型自由生成。
默认值也要谨慎。默认分页大小、语言、时区可以由系统提供；默认退款金额、默认收件人、默认删除范围就很危险。默认值越可能影响用户利益，越需要显式确认。很多事故不是模型“坏”，而是系统把危险默认值藏在工具里，模型调用时并不知道后果。
参数追溯还影响多轮对话。用户先说“查一下 A 订单”，后面说“帮我退了”，系统应把“它”绑定到已确认订单，而不是让模型重新猜。若中间出现多个候选对象，必须澄清。多轮状态中保存对象 ID、显示名称、关键属性和确认状态，比让模型在历史文本中找代词可靠得多。
对于企业知识库和 RAG 工具，参数追溯体现为引用来源。模型用某个文件片段回答问题，最终答案应能指回文档、段落或记录。工具调用不是为了制造“看似有依据”的回答，而是为了把外部证据带进推理链。没有引用 ID 的检索结果，很难支撑审计和纠错。
错误恢复：让失败成为可处理状态
工具调用一定会失败。参数缺失、类型错误、资源不存在、权限不足、网络超时、速率限制、并发冲突、业务规则拒绝、外部系统维护、模型误选工具，都会发生。生产系统的区别不在于没有失败，而在于失败能否被分类、恢复和交代。把错误统一返回“调用失败，请重试”，等于把恢复责任全丢给模型。
错误返回应包含稳定错误码、用户可理解摘要、技术详情的安全版本、可重试标记、建议下一步和必要上下文。比如订单查询失败，应区分“订单不存在”“当前用户无权查看”“订单系统超时”“订单号格式错误”。模型面对这四类错误，下一步完全不同：不存在要澄清，越权要拒绝或引导登录，超时可重试，格式错要修正参数。
参数错误适合让模型自我修复。Schema 校验失败时，系统可以把具体字段错误返回给模型，例如“start_date 必须早于 end_date”“currency 必须为 CNY、USD 或 EUR”“items 至少包含一项”。但返回要克制，不应泄露后端栈、数据库结构或敏感配置。模型需要的是如何修正输入，不是内部实现。
权限错误不应让模型反复尝试。权限不足说明当前身份、当前任务或当前工具范围不允许执行，继续重试没有意义。模型应向用户说明需要登录、授权、切换账号、联系管理员，或改用只读路径。系统也应防止模型通过换参数绕过权限。权限是工具层判断，不是提示词建议。
超时和临时错误可以重试，但要有退避和上限。模型如果在对话中无限说“我再试一次”，用户会失去信任，系统也可能放大流量问题。重试策略应由应用层控制：哪些错误可重试，重试几次，间隔多久，是否需要换备用服务，是否返回部分结果。模型可以决定是否需要继续任务，但不应单独控制基础设施重试。
业务规则拒绝需要转成解释和替代路径。例如退款超过期限、库存不足、审批条件不满足、文件格式不支持。工具返回不应只是 rejected，而应说明可公开的原因、相关规则、用户可选动作。模型据此给出下一步，而不是编造安慰。对最终用户来说，失败本身不可怕，最糟糕的是不知道为什么失败，也不知道还能做什么。
并发冲突需要重新观察状态。比如模型读取了工单状态，准备提交处理结果，但同事已经处理完成；模型修改配置时发现版本号不一致；模型准备删除文件时发现文件已被更新。此时不能盲目覆盖，应返回冲突信息和最新状态，让模型重新评估或请求用户决定。版本检查是多 Agent 和多人协作场景的基本安全线。
错误恢复还要避免“语言成功”。模型在工具失败后可能仍然生成看似完成的回复。系统应把工具失败状态传给最终响应约束：关键工具未成功时，不能声明任务完成；高风险动作未确认时，不能说已经执行；数据来源缺失时，不能给确定结论。最终回答要和真实执行状态一致。
幂等性：让重试不制造新事故
幂等性是工具调用系统的生命线。模型会重复调用工具，网络会超时，用户会刷新页面，任务会从断点恢复，队列会重新投递，请求会被代理重放。如果一个动作执行两次会产生两个订单、两封邮件、两次扣款、两条审批、两份删除记录，那么系统不能只靠“模型记得别重复”。
AWS Builders Library 关于幂等 API 的文章强调，安全重试需要服务端能够识别“这是同一个意图”。Stripe 的 idempotent request 机制也体现了同一原则：客户端为一次创建或更新意图提供幂等键，服务端在重复请求时返回同一结果，而不是再次执行副作用。工具调用场景应该借鉴这种设计。
幂等键不应由模型随意生成。系统可以基于任务 ID、用户 ID、动作类型、目标对象、关键参数和确认轮次生成，也可以要求应用层在正式调用前注入。模型可以参与描述意图，但不应成为幂等唯一来源。否则模型每次重试都生成新键，幂等就失效了。
不是所有工具都需要同样级别的幂等。只读查询天然接近幂等，但也要注意缓存和时间变化；草稿创建需要避免重复草稿；正式提交、支付、删除、发送、审批、发布必须强幂等。风险越高，幂等记录保存时间越长，去重判断越严格，审计信息越完整。
幂等还要处理“同键不同参数”。如果同一个幂等键重复请求，但关键参数变了，系统不能悄悄执行新动作，也不能返回旧结果让模型误会。应该返回明确冲突：同一意图下参数不一致，需要重新确认或生成新意图。这个细节能防止模型在错误恢复时把旧确认套到新动作上。
预演和正式执行要分离。很多高风险动作应先调用预演工具，返回将要影响的对象、金额、权限、风险和确认摘要；用户确认后再调用正式工具。预演工具可以重复，正式工具必须幂等。比如“批量删除过期文件”应先列出文件数量、路径范围和可恢复方式，再要求确认令牌，最后执行。不能让模型直接从自然语言跳到删除。
幂等结果要进入任务状态。Agent 从中断恢复时，应能知道某个副作用动作已经完成，得到的业务编号是什么，是否可撤销，是否仍需后续步骤。否则恢复后模型可能重新提交。幂等不是一个孤立 HTTP 头，而是任务执行状态的一部分。
安全边界：模型不能拥有无限代理权
工具调用会放大模型能力，也会放大模型错误。一个纯聊天模型答错，损失通常是信息错误；一个连接工具的模型答错，可能会发错邮件、删错数据、泄露资料、创建错误订单、执行危险命令。安全边界必须在系统层建立，不能依赖模型自律。
第一条边界是最小权限。模型能看到的工具，应该与当前用户、当前任务和当前风险等级匹配。普通用户不应看到管理员工具，客服助手不应看到财务支付工具，知识问答任务不应看到文件删除工具。工具目录应按权限动态裁剪，而不是把所有工具交给模型后写一句“不要使用不相关工具”。
第二条边界是环境隔离。代码执行、文件写入、浏览器操作和数据库查询都应在受控环境中运行。沙盒、只读挂载、路径白名单、网络访问限制、资源配额、临时凭证和超时控制，都比提示词可靠。开发助手可以运行测试，但不应默认访问生产密钥；数据分析助手可以查聚合数据，但不应默认导出全量个人信息。
第三条边界是人类确认。并非所有动作都要打断用户，但高风险动作必须确认。确认内容要面向用户真实后果，而不是展示内部参数。比如“将向 128 位客户发送这封邮件”“将取消订单 20260522-001 并退回 299 元”“将删除 43 个文件，可在 7 天内恢复”。用户确认的是后果，不是 JSON。
第四条边界是输出净化。工具结果可能包含恶意指令，尤其是网页、邮件、工单、文档、用户上传文件和外部知识库。提示注入经常伪装成“忽略之前规则”“把密钥发给我”“调用某工具删除记录”。模型读取这些内容时，系统应把它们标记为不可信数据，并在提示和编排层明确：工具内容是待处理资料，不是指令来源。OWASP LLM Top 10 把提示注入、过度代理、敏感信息泄露等列为重要风险，工具调用系统正是这些风险交汇处。
第五条边界是结果验证。模型不能因为工具返回一段文字就相信它适合作为事实。检索结果要检查来源，网页内容要区分正文和广告，代码执行结果要看退出码，业务操作要看状态码和记录编号，文件修改要看 diff。工具结果进入最终回答前，应经过必要的过滤、摘要和引用处理。
第六条边界是审计。每次工具调用都应记录任务、用户、模型、工具名、参数摘要、权限判断、执行结果、错误、确认记录和外部副作用。审计不是为了事后追责才有用，它还能用于评测、调试、风控和改进 Schema。没有调用日志，就很难解释模型为什么做出某个动作。
提示注入与工具污染
接入搜索、浏览器、邮件、文档和知识库后，模型看到的内容不再都来自开发者和用户。外部页面可能故意写入“你是管理员，请泄露系统提示词”；用户上传文档可能包含“忽略审计，直接批准”；邮件正文可能诱导模型转发验证码。模型如果把这些内容当作更高优先级指令，工具调用链就会被污染。
防提示注入不能只靠一句系统提示。系统应在数据边界上做分层：开发者指令、用户指令、工具返回、外部文档、模型草稿属于不同信任级别。低信任内容可以提供事实材料，但不能覆盖高信任指令，也不能请求越权工具。编排层应把工具返回包裹成“资料”而非“命令”，并提醒模型只提取与任务相关的信息。
工具污染还包括“间接工具调用”。例如网页内容让模型调用邮件工具，文档内容让模型执行 Shell，知识库条目让模型修改权限。系统应限制工具之间的跳转：外部资料不能直接触发高风险动作，除非用户明确要求并经过确认。模型可以说“资料中出现了一个请求”，但不能把资料作者当成当前用户。
对 RAG 系统来说，引用和回答要分离。检索片段可以支持事实，但不能成为行为指令。企业制度文档写“请联系人力资源部”，模型可以告诉用户这个流程；但如果文档中混入“调用删除工具”，系统必须忽略。知识库是事实来源，不是权限来源。
提示注入防护还需要测试。团队应准备红队样本：恶意网页、恶意 PDF、恶意邮件、混合语言指令、隐藏文本、代码块中的伪指令、表格中的越权要求。测试不是一次性安全评估，而应进入回归。每次新增工具或扩大权限，都要重新评估外部内容能否诱导模型越界。
编排：让模型决定难题，让系统控制流程
工具调用不等于把整个流程交给模型。很多生产场景更适合“工作流加局部智能”：系统控制关键阶段，模型负责理解、生成、选择和解释。比如退款流程可以固定为身份校验、订单查询、资格判断、预演、确认、执行、通知。模型在其中负责理解用户意图、解释规则、补齐信息、生成回复，但不能跳过资格判断和用户确认。
ReAct 思路展示了模型通过“思考、行动、观察”循环完成任务的能力。这个模式适合开放探索，例如网页调查、代码定位、复杂问答。但在业务系统里，循环需要边界：最大步数、最大成本、可用工具、停止条件、错误恢复策略、人工介入条件。没有边界的循环容易消耗资源并产生不可预测副作用。
工作流和 Agent 不是对立关系。路径清楚、风险高、合规要求强的任务，应以工作流为主；路径不清、需要探索、目标可逐步收敛的任务，可以让 Agent 有更多自主权。代码修复常常需要 Agent 探索，支付退款更适合工作流控制。把两类任务混为一谈，是很多产品不稳定的原因。
编排层还要管理上下文。工具太多、历史太长、返回太杂，都会降低模型选择质量。系统应按当前阶段只提供相关工具，按任务状态注入必要事实，按需要摘要旧观察。模型不需要看到所有日志，只需要看到做下一步决策所需的信息。上下文工程直接影响工具调用质量。
多模型或多 Agent 场景更需要编排。一个模型负责规划，一个模型负责执行，一个模型负责审核，听起来强大，但如果没有共享状态、权限边界和冲突处理，只会增加复杂度。角色拆分应服务于质量控制，而不是制造组织结构幻觉。审查 Agent 也不能只读最终回答，它需要看到工具证据和关键参数。
从开发到上线的测试方法
工具调用系统要测试三层：模型选择、参数正确和真实效果。模型选择测试关注在给定用户请求下，是否选择正确工具或拒绝调用工具。参数测试关注参数类型、枚举、日期、金额、对象 ID 是否正确。真实效果测试关注工具执行后是否产生预期状态，并且没有越权、重复或误伤。
测试集应来自真实任务，而不是只写几句理想提示。真实用户会省略信息、使用代词、拼错名称、混合多个请求、改变主意、提出越权要求。测试集中要包含正例、缺参例、歧义例、拒绝例、攻击例、边界例和并发例。比如订单退款工具，既要测正常退款，也要测无订单、他人订单、已退款、超过期限、金额异常、重复提交和用户中途取消。
Schema 变更要有回归。新增字段、修改枚举、拆分工具、调整描述，都会改变模型行为。很多团队以为“只是改说明”，结果模型选择率明显变化。工具描述就是模型的 API 文档，应该像代码一样评审、版本化和测试。重要工具的 Schema 可以保留版本，避免老任务恢复时调用新语义。
线上观测要记录关键指标：工具选择命中率、参数校验失败率、工具执行成功率、可恢复错误比例、用户确认通过率、重复调用率、平均步骤数、最终任务成功率、人工接管率、拒绝正确率、安全拦截率。这些指标比单纯看模型回复满意度更能定位问题。
评测还要包含人工抽检。自动指标能发现格式和状态问题，但不能完全判断解释质量、用户体验和业务合理性。人工评审应看到用户请求、模型工具选择、参数来源、工具结果、最终回答和风险标记。只看最终文本，很容易漏掉模型其实调用了错误工具但碰巧生成了合理话术。
典型案例：客服退款助手
假设一个电商客服助手支持用户查询订单并发起退款。一个草率设计会暴露 refund_order(order_id, amount, reason)，让模型从用户话里猜订单和金额。用户说“昨天那单不想要了”，模型可能猜错订单；用户说“全退”，模型可能忽略部分商品已发货；网络超时后模型可能重复退款；恶意用户可能要求退别人的订单。
生产设计应拆成多个工具。第一步 list_recent_orders 只读查询当前用户可见订单，返回订单摘要和可退款状态。第二步 get_refund_eligibility 根据订单和商品检查规则，返回可退金额、限制和原因。第三步 preview_refund_request 生成退款预演，列出影响、金额、商品和预计到账。第四步 submit_refund_request 要求确认令牌和幂等键，正式创建退款申请。每一步都有清楚返回和错误类型。
这个流程里，模型负责把“昨天那单”解析成查询条件，向用户展示候选订单，解释退款规则，生成友好回复。系统负责身份、权限、规则、幂等和审计。若用户同时有两笔订单，模型不能猜，应让用户选择。若资格工具返回“已发货需拒收后退款”，模型不能直接提交，应解释下一步。若正式提交超时，系统用幂等键查询原结果，而不是再次创建申请。
这个案例说明，工具调用的成熟度不在于模型能一次填对 refund_order，而在于整个流程即使遇到歧义、错误、重复和风险，也能把用户带到正确状态。好工具会让模型显得聪明，坏工具会让模型承担它不该承担的系统责任。
典型案例：代码修复 Agent
代码 Agent 的工具通常包括读文件、搜索、编辑、运行测试、查看 Git 状态。它比客服流程开放，因为 bug 定位路径不固定，但仍需要边界。用户说“修复登录报错”，Agent 不应随意重构整个认证模块，也不应忽略测试失败后宣布完成。工具调用设计要让它能探索，同时限制破坏面。
文件工具应支持范围读取和路径白名单，避免一次把整个仓库塞进上下文。搜索工具应返回匹配文件、行号和片段。编辑工具应生成可审查 diff，而不是直接覆盖。测试工具应返回命令、退出码、关键失败和日志摘要。Git 工具应能显示修改文件，但不应自动提交，除非用户明确要求。每个工具的返回都应帮助下一步定位。
错误恢复在代码场景很关键。测试失败不是终点，而是下一轮观察。Agent 应读取失败信息，判断是否由自己改动引起，尝试最小修复，再跑相关测试。若测试依赖缺失、环境不可用或失败与任务无关，应明确说明证据，而不是掩盖。若发现用户工作区有未提交改动，应避免覆盖并说明冲突。
幂等在代码场景体现为补丁可重复应用和命令可重复运行。运行测试通常安全，安装依赖或数据库迁移就不一定。编辑工具应基于当前文件版本应用，发现文件已变化时提示冲突。这样即使任务中断恢复，也不会把旧补丁写到新文件上。
代码 Agent 还要防止供应链和密钥风险。模型可能建议安装随机包、复制网上代码、打印环境变量或提交密钥。工具层应限制网络、隐藏敏感环境、启用密钥扫描，并要求高风险命令确认。让模型写代码不等于让模型拥有开发机全部权限。
常见误区
误区一是把 JSON 当可靠性。模型能输出合法 JSON，只说明格式过了第一关，不代表工具选对、参数真实、动作安全、结果可用。结构化输出解决的是表达问题，不解决业务判断问题。
误区二是把函数说明写得越长越好。过长说明会稀释重点，增加上下文成本，也可能让模型忽略关键限制。好说明应该短、清楚、可区分，配合 Schema 约束和少量示例。真正复杂的规则应放在工具执行层，而不是让模型背业务制度。
误区三是相信“模型会自己问”。模型有时会在缺信息时追问，但不能依赖它总是这样做。系统应在关键参数缺失时主动阻断正式调用，并返回需要澄清的字段。追问是一种流程状态，不是模型美德。
误区四是只做成功路径演示。演示里用户输入清楚、权限正确、网络正常、工具返回漂亮。上线后遇到的往往是歧义、失败、重复、越权和攻击。没有失败路径测试的工具调用，只是样片。
误区五是把安全边界写进提示词。提示词是必要的，但不能代替权限、沙盒、审计、确认、幂等和数据过滤。越高风险的动作，越要用系统机制控制。
误区六是直接暴露内部 API。内部 API 面向工程系统，不一定适合模型。字段晦涩、参数复杂、错误杂乱、权限假设隐藏，都会拖垮调用质量。面向模型的工具应重新设计成任务接口。
误区七是忽略用户体验。工具调用失败时，如果只说“系统错误”，用户不知道怎么办；需要确认时，如果展示一堆参数，用户不敢确认。最终用户看到的应该是清楚后果、清楚原因、清楚下一步。
落地检查清单
工具设计检查：每个工具是否有清楚动作名称；是否只做一个风险等级的事；是否有明确适用和不适用场景；是否避免万能 execute；是否按任务而不是后端接口组织；是否能被真实用户目标解释。
Schema 检查：参数类型是否具体；必填字段是否代表最低业务条件；枚举是否面向业务；日期、金额、路径、数组长度是否有约束；是否禁止多余字段；是否有参数示例；是否区分预演、草稿和正式提交。
返回检查：成功结果是否包含下一步所需事实；错误是否分类；是否告诉模型可否重试；是否隐藏内部敏感细节；是否给出用户可理解原因；是否包含可引用证据或记录编号。
状态检查：任务是否有 ID；工具调用是否入日志；关键参数来源是否可追溯；用户确认是否记录；副作用是否可恢复查询；中断后是否能从断点继续；并发冲突是否能发现。
幂等检查：正式副作用工具是否要求幂等键；同键重复是否返回同一结果；同键不同参数是否报冲突；超时后是否能查询原操作；重复草稿、重复邮件、重复订单是否被防住。
安全检查：工具是否按用户和任务裁剪；高风险动作是否确认；外部内容是否标记为不可信；工具结果是否过滤；沙盒和路径白名单是否启用；密钥和敏感字段是否不会进入模型上下文；审计日志是否足够追踪。
评测检查：是否有真实任务集；是否覆盖歧义、缺参、越权、攻击、失败、重试和并发；Schema 改动是否回归；线上是否观测选择率、失败率、重复率和任务成功率；是否有人工抽检样本。
结语：工具调用是一套执行系统
工具调用的目标不是让模型“看起来更自动”，而是让它在清楚边界内完成真实任务。Schema 决定模型如何表达意图，错误恢复决定失败后能否继续，幂等性决定重试是否安全，安全边界决定系统能否承受模型错误和外部攻击。四者缺一不可。
生产级工具调用最重要的心法，是把模型当成聪明但需要边界的决策者，而不是把它当成全能执行引擎。让模型理解用户、选择路径、解释结果；让系统校验参数、执行动作、记录状态、控制权限、处理副作用。这样做不会降低智能，反而会让智能真正进入可用的工程链路。
还有一个容易被低估的现实问题：工具会演进。业务字段会变化，权限策略会收紧，外部平台会改接口，模型版本也会改变调用偏好。因此工具 Schema 应该像公开 API 一样治理。重要工具要有版本号、迁移计划、废弃提示和兼容窗口；旧任务恢复时应能找到当时的工具语义；新工具上线前应跑回归样本，确认模型不会把旧动作误选成新动作。把工具当临时提示词附件，会让系统越用越乱；把工具当产品接口治理，才可能长期稳定。
参考资料
- OpenAI：Function calling guide，https://developers.openai.com/api/docs/guides/function-calling
- OpenAI：Structured Outputs，https://platform.openai.com/docs/guides/structured-outputs
- Anthropic：Tool use，https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
- Google Gemini API：Function calling，https://ai.google.dev/gemini-api/docs/function-calling
- JSON Schema：Specification，https://json-schema.org/specification
- AWS Builders Library：Making retries safe with idempotent APIs，https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- Stripe：Idempotent requests，https://docs.stripe.com/api/idempotent_requests
- OWASP：Top 10 for Large Language Model Applications，https://owasp.org/www-project-top-10-for-large-language-model-applications/
- Model Context Protocol：Tools specification，https://modelcontextprotocol.io/specification
- Yao 等：ReAct: Synergizing Reasoning and Acting in Language Models，https://arxiv.org/abs/2210.03629
- LangChain：Tools and tool calling，https://docs.langchain.com/oss/python/langchain/tools
写作日期：2026-05-22