给Agent一个结构化工具和自然语言描述工具，前者有Schema、状态码、参数类型和幂等键，后者全靠模型“理解”——当“写操作”涉及资金和数据变更时，工具接口到底该多“结构化”才够？

摘要：工具调用（Tool Calling / Function Calling）已经成为大模型智能体（Agent）落地的核心接口形态，但“工具描述”本身存在两种截然不同的范式：一种是以 JSON Schema、HTTP 状态码、强类型参数与幂等键为代表的结构化工具，另一种是以自然语言说明、由模型自行推断参数语义的非结构化工具。当工具只做查询时，两者的差异主要体现为成功率；而当工具执行资金划转、账户冻结、数据删除等“写操作”时，差异会直接转化为资损、越权与不可逆的数据事故。本文提出一条贯穿全文的分析主线：结构化程度应当与写操作的“不可逆性 × 金额量级 × 授权跨度”成正比，并以“可验证的失败模式”而非“模型能力”作为设计基准。围绕这条主线，本文从契约理论、幂等性语义、状态机建模、人工确认阈值、评测基准五个层面展开，给出分级结构化模型（L0–L4）与可落地的工程步骤，并对 2023–2025 年国内外相关规范与研究进行梳理与独立评述。

目录

一、导语：一次“语义正确、契约错误”的转账事故

设想一个典型场景：用户对 Agent 说“把我上个月多付给供应商的那笔钱退回来”。Agent 调用了一个自然语言描述的工具，说明文字是“用于向供应商付款，参数为供应商名称和金额”。模型正确理解了“退款”的语义，却把参数填成了“供应商名称=某供应商，金额=上个月付款额”，而该工具的真实语义是“新增一笔付款”，并不具备“冲正”能力。结果不是退款，而是二次付款。从语言理解角度看，模型没有错；从接口契约角度看，工具描述没有约束“退款”与“付款”的语义差，也没有幂等键防止重复提交。这类事故的根因不在模型能力，而在工具接口的结构化程度不足。

这类问题在 2023 年之后迅速从“实验室趣闻”变成“生产事故”。OpenAI 在 2023 年 6 月发布 Function Calling 能力时，给出的核心卖点正是“用 JSON Schema 约束模型输出”，其官方文档明确要求开发者以 JSON Schema 描述函数参数（OpenAI, 2023）。Anthropic 在 2024 年发布的 Model Context Protocol（MCP）进一步把“工具、资源、提示”抽象为标准化协议，工具定义中同样包含 inputSchema（Anthropic, 2024）。这说明主流厂商已经形成共识：工具不是“给模型看的说明书”，而是“给系统执行的契约”。但共识之下仍有大量工程团队把工具写成一段自然语言，理由是“模型足够聪明”。本文要回答的正是：当写操作涉及资金和数据变更时，这种“聪明”能否被信任，结构化到底要做到什么颗粒度。

二、问题定义：什么是“结构化工具”，边界在哪里

2.1 结构化工具的五个构成要素

笔者认为，讨论“结构化”之前必须先给出可操作的定义，否则容易陷入“有 Schema 就算结构化”的模糊判断。一个真正意义上的结构化工具，至少应包含五个要素：（1）机器可校验的输入 Schema，即参数名、类型、必填性、枚举值、数值范围与嵌套结构；（2）明确的输出契约，包括成功返回结构与错误码枚举；（3）状态码语义，区分可重试错误（如 429、503）与不可重试错误（如 400、403）；（4）幂等键，用于在重试、超时、并发场景下保证同一业务意图只执行一次；（5）副作用声明，即该工具是只读（read-only）、可逆写（reversible write）还是不可逆写（irreversible write）。这五个要素共同构成“契约”，缺一不可。

对照来看，自然语言描述工具通常只提供一段说明文字，参数靠模型从上下文中“猜”，错误靠模型从返回文本中“读”，重试靠模型“判断”。这种范式在查询类任务中尚可接受，因为错误代价低、可重试；但在写操作中，每一次“猜”都可能对应一次真实的资金变动。本文评述：把工具描述写成自然语言，本质上是把“契约校验”的职责从系统层转移到了模型层，而模型层恰恰是概率性的、不可审计的。这是结构性缺陷，不是提示词优化能弥补的。

2.2 写操作与读操作的风险不对称

读操作与写操作在风险结构上存在根本不对称。读操作失败的最坏结果是“没查到”或“查错了”，可以通过重试、交叉验证、人工复核来兜底；写操作失败的最坏结果是“钱转错了”“数据删了”“账户被冻结了”，其中相当一部分不可逆。金融行业对此有成熟认知：支付系统普遍采用“幂等 + 对账 + 冲正”三重机制，其前提是每一笔交易都有唯一业务流水号。本文评述：Agent 工具接口若不具备幂等键，就等于放弃了这三重机制的第一重，后续对账与冲正的成本会被显著放大。

更隐蔽的风险来自“语义漂移”。自然语言描述中的“退款”“冲正”“撤销”“调账”在人类语境中含义相近，但在账务系统中对应完全不同的操作与会计分录。模型基于语义相似性选择工具时，极易把“退款”映射到“付款”。结构化工具通过枚举值（如 operation_type 只能取 REFUND、REVERSAL、ADJUSTMENT）把这种语义差异固化为机器可校验的约束，从而在接口层消灭歧义。这是结构化最直接的价值，也是本文后续分级模型的出发点。

三、理论主线：结构化程度与写操作风险的三元函数

3.1 三元函数的提出

本文的核心主张可以形式化为一个设计准则：工具所需的结构化程度 S，应当与三个变量正相关——不可逆性 I（操作能否被撤销）、金额量级 M（单次操作涉及的资金或数据规模）、授权跨度 A（Agent 被授予的权限范围与人类监督的介入程度）。可写作 S = f(I, M, A)，且三者均为单调递增。这个函数不是精确的数学公式，而是一个设计基准：当 I、M、A 中任一变量升高时，接口的结构化要素必须相应增加，而不能以“模型能力提升”为由降低要求。

本文评述：这一准则的合理性来自工程实践中的“失败代价不对称”。结构化带来的成本是开发复杂度与调用灵活性下降，收益是失败模式可枚举、可拦截。当失败代价低时，收益小于成本，自然语言描述是理性选择；当失败代价高时，收益远大于成本，结构化是必要投入。把这一权衡显式化，比笼统地说“结构化更好”更有指导意义。它也解释了为什么查询类工具可以“轻结构化”，而支付类工具必须“重结构化”。

3.2 与经典契约理论的对应

这一思路与软件工程中的“契约式设计”（Design by Contract）一脉相承。Bertrand Meyer 在 1980 年代提出的契约式设计强调前置条件、后置条件与不变式（Meyer, 1992），其核心思想是：调用方与被调用方之间的责任必须显式声明，并由运行时校验。本文评述：把这一经典概念迁移到 Agent 工具接口，前置条件对应输入 Schema 与权限校验，后置条件对应输出契约与状态码，不变式对应幂等键与账务平衡约束。经典理论的价值在于提醒我们——契约不是文档，而是可执行的断言。自然语言描述恰恰缺少“可执行”这一属性，因此不能称为契约。

另一个可对应的概念是“能力安全”（capability safety）。在操作系统领域，能力（capability）是不可伪造的访问令牌，持有能力即拥有对应权限。Agent 工具接口的授权跨度 A，本质上就是能力授予的粒度问题。若一个工具既能查询余额又能发起转账，其能力粒度过粗，模型一旦误用，损失被放大。结构化工具通过拆分工具、细化参数枚举、引入二次确认，实际上是在做“能力最小化”。这与 Saltzer 和 Schroeder 在 1975 年提出的最小权限原则完全一致（Saltzer & Schroeder, 1975）。

3.3 为什么“模型能力提升”不能替代结构化

一个常见反驳是：随着模型能力提升，语义理解会越来越准，结构化就不再必要。本文认为这一推论存在两个漏洞。第一，概率正确不等于确定正确。即便模型在基准测试上达到 99% 的工具选择准确率，剩余 1% 在日均百万次调用下仍是万次量级的错误，而写操作的错误不可用“平均准确率”来摊销。第二，语义理解无法消除接口歧义。当两个工具的自然语言描述高度相似时，任何模型都可能混淆，这不是能力问题，而是信息论意义上的不可区分。结构化通过枚举值与类型约束把“不可区分”变为“可区分”，这是模型能力无法替代的系统层改进。

2024 年多项研究也支持这一判断。例如在工具调用基准测试中，研究者发现即使是最强模型，在参数类型复杂、工具数量多的场景下错误率仍显著上升（Qin et al., 2024；Li et al., 2024）。这说明模型能力与接口设计是两个独立变量，不能互相替代。本文评述：正确的做法是“双管齐下”——用更强的模型提升语义理解，用更严的结构化约束兜住底线，二者是互补而非替代关系。

四、技术路线：从 Schema 到幂等键的五层契约

4.1 第一层：输入 Schema 的强类型化

输入 Schema 是结构化的第一道防线。工程上应做到：参数名语义明确（避免 amount 与 value 混用）、类型严格（金额用整数分而非浮点）、枚举封闭（operation_type 只允许有限取值）、范围约束（amount 最小值与最大值）、必填性明确（避免模型省略关键参数后由服务端猜测默认值）。以下是一个面向资金操作的 Schema 片段示例：

{
  "name": "transfer_funds",
  "description": "向指定收款方发起一笔不可逆的资金划转",
  "parameters": {
    "type": "object",
    "properties": {
      "payee_id":   { "type": "string", "pattern": "^P[0-9]{8}$" },
      "amount_cents": { "type": "integer", "minimum": 1, "maximum": 5000000 },
      "currency":   { "type": "string", "enum": ["CNY", "USD"] },
      "operation_type": { "type": "string", "enum": ["TRANSFER", "REFUND"] },
      "idempotency_key": { "type": "string", "minLength": 16, "maxLength": 64 },
      "reason_code": { "type": "string", "enum": ["PURCHASE", "REFUND", "ADJUSTMENT"] }
    },
    "required": ["payee_id", "amount_cents", "currency",
                 "operation_type", "idempotency_key"]
  }
}

这段 Schema 的关键设计在于：金额用整数分避免浮点误差；operation_type 用枚举区分“转账”与“退款”，从接口层消灭语义漂移；idempotency_key 设为必填，强制调用方提供去重依据。本文评述：很多团队把幂等键设为可选，理由是“模型不一定能生成”。这是本末倒置——幂等键本就不应由模型生成，而应由编排层（orchestrator）基于会话 ID 与业务流水号生成后注入，模型只负责传递。把生成职责放对位置，必填就不会成为负担。

4.2 第二层：输出契约与状态码语义

输出契约的重要性常被低估。若工具返回一段自由文本，模型需要“阅读理解”才能判断成功与否，这又引入一次概率性判断。结构化输出应包含：明确的成功标志、业务错误码枚举、可重试标志、以及用于对账的交易流水号。HTTP 状态码的语义应被严格使用：200 表示成功，400 表示参数错误（不可重试），401/403 表示鉴权失败（不可重试），409 表示幂等冲突（需查询原结果），429 表示限流（可重试），500/503 表示服务端故障（可重试但需幂等保护）。

本文评述：状态码语义的价值在于把“是否重试”这一决策从模型转移到编排层。模型不应被要求理解“503 意味着可以重试但必须带同一幂等键”，这属于系统职责。编排层根据状态码自动决策，模型只负责发起意图。这种职责分离是结构化设计的精髓——让确定性的逻辑走确定性通道，让概率性的理解走概率通道。

4.3 第三层：幂等键的生成与生命周期

幂等键是写操作安全的核心。其工程要点包括：生成位置（编排层而非模型）、生成依据（会话 ID + 业务意图哈希 + 时间窗口）、存储位置（服务端去重表，带 TTL）、冲突处理（返回首次执行结果而非报错）、以及跨重试一致性（同一意图的所有重试必须携带同一键）。一个常见的错误是让模型“想一个唯一 ID”，这既不可靠也不可审计。正确做法是由编排层在解析出业务意图后生成，并在整个重试链路中保持不变。

本文评述：幂等键的设计还涉及“意图粒度”问题。若粒度过粗（如整个会话一个键），则同一会话内的多笔合法交易会被误判为重复；若粒度过细（如每次调用一个新键），则失去去重意义。合理的粒度是“一次业务意图一个键”，即用户说“退那笔钱”对应一个键，用户说“再退一次”则对应新键。这个边界需要产品与工程共同定义，无法由模型自行判断。

4.4 第四层：状态机与前置条件校验

资金与数据变更本质上是状态迁移。以退款为例，订单状态需从“已支付”迁移到“退款中”再到“已退款”，每一步都有前置条件（如退款金额不得超过原支付金额、退款时限未过期）。结构化工具应把这些前置条件编码为服务端校验，而非依赖模型在提示词中“记住”。状态机建模的好处是：非法迁移会被服务端拒绝并返回明确错误码，模型据此可以给出可解释的失败反馈，而不是产生“看起来成功实则失败”的幻觉。

本文评述：状态机与幂等键结合，可以覆盖绝大多数重复提交与并发冲突场景。例如两个并发请求携带同一幂等键，服务端通过唯一约束保证只有一个成功，另一个返回首次结果；若两个请求携带不同幂等键但业务上重复，则需状态机的前置条件（如“订单已退款则拒绝再次退款”）兜底。两层防护叠加，才能把写操作的风险降到可接受水平。

4.5 第五层：副作用声明与人工确认阈值

副作用声明要求工具显式标注自己是只读、可逆写还是不可逆写。这一元数据可被编排层用于自动决策：只读工具直接执行；可逆写工具执行后记录回滚点；不可逆写工具在超过阈值时触发人工确认。阈值可以按金额、数据条数、权限跨度设定。例如单笔超过 1 万元、单次删除超过 100 条记录、或涉及跨主体授权时，强制人工二次确认。这一机制在金融与医疗行业已有成熟实践，迁移到 Agent 场景只需把“人工”从柜员换成“用户确认卡片”。

本文评述：人工确认阈值的设计需要避免两个极端。阈值过低会导致确认疲劳，用户习惯性点击“同意”，防护形同虚设；阈值过高则失去保护意义。合理做法是“动态阈值 + 风险分级”：低风险操作静默执行并留痕，中风险操作要求一次确认，高风险操作要求二次确认并展示关键参数（收款方、金额、不可逆提示）。这种分级与本文的三元函数一致，是结构化程度在交互层的体现。

五、关键数据与案例：失败模式的可观测证据

5.1 工具调用基准测试中的错误分布

2024 年以来，工具调用评测成为研究热点。伯克利函数调用排行榜（Berkeley Function Calling Leaderboard, BFCL）持续跟踪主流模型的工具选择与参数填充准确率，其评测涵盖简单调用、多函数选择、参数类型复杂等场景（UC Berkeley, 2024）。公开结果显示，模型在单工具简单调用上准确率较高，但在多工具、参数嵌套、类型约束复杂的场景下错误率明显上升。需要说明的是，具体数值随模型版本与评测集更新而变化，本文不引用单一静态数字，而强调其趋势：接口复杂度与错误率正相关。

另一类证据来自工具调用数据集的研究。ToolBench、API-Bank 等工作构建了大规模真实 API 调用任务，发现模型在参数缺失、参数类型不匹配、以及需要多步推理的场景下失败率较高（Qin et al., 2024；Li et al., 2023）。本文评述：这些基准的共同局限是“以查询类 API 为主”，对写操作、幂等、并发冲突的覆盖不足。这意味着现有基准可能高估了模型在真实写操作场景下的可靠性。工程团队不能直接拿基准分数作为上线依据，而应构建自己的写操作评测集。

5.2 真实事故的共性模式

公开报道与行业交流中，Agent 写操作事故可归纳为四类共性模式。第一类是语义混淆，如把“退款”执行为“付款”，根因是工具描述缺少操作类型枚举。第二类是重复提交，如超时后模型自行重试导致二次扣款，根因是缺少幂等键。第三类是参数幻觉，如模型编造不存在的收款方 ID，根因是缺少格式校验与存在性校验。第四类是越权操作，如 Agent 在未获授权时调用了高权限工具，根因是能力粒度过粗、缺少前置鉴权。

本文评述：这四类模式恰好对应本文五层契约中的不同层——语义混淆对应枚举约束，重复提交对应幂等键，参数幻觉对应 Schema 校验，越权操作对应副作用声明与鉴权。这说明结构化不是抽象原则，而是可以逐条映射到具体失败模式的工程手段。团队在复盘事故时，可以用这四类模式作为检查清单，逐项确认接口是否具备对应防护。

5.3 行业规范的收敛趋势

国际层面，多家机构在 2024–2025 年发布了 Agent 安全相关指引。OWASP 在其大模型应用风险清单中把“过度代理”（Excessive Agency）列为重要风险，强调应限制 Agent 的工具权限与自主决策范围（OWASP, 2024）。NIST 的 AI 风险管理框架（AI RMF）则提供了风险识别、评估、治理的通用流程（NIST, 2023）。国内方面，全国网络安全标准化技术委员会发布的生成式人工智能服务安全相关要求，以及金融行业对智能客服、智能投顾的规范，均强调“可追溯、可干预、可审计”。

本文评述：这些规范的共同指向是“人类监督不可缺位”，但多数停留在原则层面，缺少对工具接口结构化程度的具体要求。这正是本文提出分级模型（L0–L4）的动机——把原则转化为可检查的接口设计清单。笔者认为，未来规范很可能沿着“按风险分级、按操作类型设定最低结构化要求”的方向演进，类似支付行业对 PCI DSS 的分级合规思路。

六、分级结构化模型 L0–L4 与落地步骤

6.1 五级模型定义

为把三元函数转化为可执行标准，本文提出分级结构化模型。L0 为纯自然语言描述，无 Schema、无状态码、无幂等；L1 提供基础 Schema 与类型校验；L2 增加输出契约与状态码语义；L3 增加幂等键与状态机前置条件；L4 增加副作用声明、人工确认阈值与完整审计日志。级别越高，结构化程度越强，适用场景的风险容忍度越低。下表给出各级别的要素与适用边界：

本文评述：分级模型的价值在于“可按工具逐一评级”，而非“一刀切要求全部 L4”。一个 Agent 系统往往同时包含查询、草稿、提交、审批等多类工具，逐级配置既保证安全又保留效率。评级应由风险负责人而非模型开发者决定，并随业务变化定期复核。这与数据分级分类的治理思路一致，便于纳入现有安全体系。

6.2 落地步骤：从现状评估到灰度上线

落地可按六步推进。第一步，工具盘点：列出全部工具，标注读写属性、涉及资金或数据规模、权限范围。第二步，风险定级：按三元函数为每个工具定级，确定目标 L 级。第三步，契约补齐：按目标级别补齐 Schema、状态码、幂等键、状态机与副作用声明。第四步，编排层改造：把幂等键生成、重试决策、人工确认触发从模型移到编排层。第五步，评测集构建：针对四类失败模式构造对抗测试用例，覆盖参数缺失、语义混淆、重复提交、越权调用。第六步，灰度上线：先小额、低频、可回滚场景，逐步放量，并持续监控错误码分布与人工确认通过率。

本文评述：第三步与第四步是最容易被跳过的，也是收益最大的。很多团队只补 Schema 不改编排层，结果幂等键仍由模型生成，防护形同虚设。另需强调评测集的“写操作导向”——现有公开基准偏查询，团队必须自建包含幂等冲突、并发重试、越权调用的用例。评测集应版本化管理，随工具变更同步更新，否则会迅速失效。

6.3 一个可复用的编排层伪代码

为便于工程落地，以下给出编排层处理写操作的伪代码，体现“幂等键生成、状态码决策、人工确认”三项职责的分离：

def execute_write(intent, tool, args):
    key = make_idempotency_key(intent.session_id, intent.business_hash)
    args["idempotency_key"] = key

    if tool.risk_level >= L4 and exceeds_threshold(args):
        if not request_human_confirm(args):
            return Rejected("human_confirm_required")

    resp = tool.call(args)

    if resp.status in (429, 503):
        return retry_with_same_key(tool, args, key)
    if resp.status == 409:
        return query_by_key(key)          # 幂等冲突，取首次结果
    if resp.status in (400, 401, 403):
        return Fail(resp.error_code)        # 不可重试
    return Success(resp.transaction_id)

这段伪代码的关键在于：模型不参与重试决策，也不生成幂等键；它只负责把用户意图转化为工具调用请求。所有确定性逻辑由编排层承担。本文评述：这种分层与微服务架构中的“网关职责”高度相似——网关负责鉴权、限流、重试，业务服务只负责业务逻辑。把 Agent 编排层视为“智能网关”，有助于复用成熟的工程经验。

七、对比与局限：结构化不是万能药

7.1 结构化的成本与边界

结构化并非没有代价。第一，开发成本上升：每个工具都要设计 Schema、错误码、状态机，工作量显著增加。第二，灵活性下降：过度结构化会把工具拆得过细，模型需要在更多工具间选择，反而增加选择错误。第三，维护负担：Schema 与业务逻辑需同步演进，否则会出现“契约与实现不一致”的隐性缺陷。第四，对开放式任务的适配性差：创意生成、探索式分析等任务难以预先定义 Schema，强行结构化会限制模型能力。

本文评述：这些成本说明结构化应“按风险配置”，而非“全面拉满”。这也回到本文主线——结构化程度与风险成正比。对只读、低价值、开放式任务，L0–L1 足够；对资金与数据变更，L3–L4 必要。把“结构化”当成普适教条，与把它当成可有可无的装饰，同样是错误的。

7.2 与自然语言工具的对比

为清晰呈现差异，下表从六个维度对比两种范式。需要说明的是，这里的对比是“典型形态”对比，实际系统常处于两者之间：

本文评述：表格中最值得关注的是“可审计性”一行。在受监管行业，审计要求往往比效率要求更刚性——监管方需要能够还原“谁在何时以何参数调用了什么工具、结果如何”。结构化工具天然满足这一要求，自然语言工具则需要额外的日志解析与人工复核。这意味着即便模型能力足够，合规成本也会推动写操作工具走向结构化。

7.3 尚未解决的问题

本文认为至少有三个问题尚无成熟答案。第一，多工具组合的契约一致性：当一次业务需要调用多个工具（如先冻结再扣款）时，如何保证跨工具的原子性与幂等性？分布式事务的经典方案（Saga、TCC）可以借鉴，但与 Agent 的动态编排结合仍有挑战。第二，动态工具生成的治理：部分系统允许 Agent 在运行时生成或组合工具，这会让预先定义的 Schema 失效，需要新的运行时校验机制。第三，评测标准的缺失：目前缺少公认的“写操作工具调用”基准，团队各自为战，难以横向比较。

本文评述：这三个问题恰好对应工程、治理、学术三个层面。工程层面可先借鉴微服务的 Saga 模式，把长事务拆为可补偿的短事务；治理层面应限制运行时工具生成，至少要求生成结果经过 Schema 校验与人工审批；学术层面则需要社区共同构建写操作基准，覆盖幂等、并发、越权等场景。这些都不是单点优化能解决的，需要生态协作。

八、结论与展望：把“理解”留给模型，把“约束”留给接口

回到文章开头的问题：工具接口到底该多结构化才够？本文给出的答案是——以写操作的不可逆性、金额量级与授权跨度为标尺，分级配置结构化要素；对资金划转与不可逆数据变更，至少达到 L3，涉及大额或跨主体授权时达到 L4。这一结论不是“越结构化越好”的口号，而是基于失败代价不对称的工程判断。自然语言工具在查询与探索场景仍有价值，但在写操作场景，其概率性本质与资金安全要求存在结构性冲突。

展望未来，笔者认为三个方向值得关注。其一，协议层的标准化：MCP 等协议正在把工具定义标准化，若能在协议层内置幂等键、副作用声明与风险等级，将大幅降低团队的实施成本。其二，运行时验证的强化：除了静态 Schema，未来可能出现基于形式化方法的运行时契约检查，对关键写操作做前置条件证明。其三，人机协作界面的演进：人工确认不应是简单的“是/否”弹窗，而应展示关键参数、风险提示与可回滚选项，让确认本身成为一次有效的风险沟通。

最后需要强调，结构化解决的是“接口层”问题，不能替代“模型层”的持续优化，也不能替代“组织层”的权限治理与审计制度。三者缺一不可。把“理解”留给模型，把“约束”留给接口，把“监督”留给人——这或许是 Agent 走向生产环境时最务实的分工。

九、主要参考文献与拓展资源