跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 03

03-02|Tool Schema:模型凭什么知道工具怎么用

解剖 Tool Schema 的名称、描述、参数、枚举与 strict 约束,设计模型和 Runtime 都能正确消费的能力接口。

Tool Schema · Function Calling · JSON Schema

模型看到的不是你的函数实现

模型选择 Tool 时,通常看到名称、描述和参数 Schema。它不知道函数内部查哪个数据库,也不知道某个缩写在团队里的隐含含义。Schema 写得含糊,模型就会在错误时机调用、传错参数,或选择相邻工具。

Tool Schema 同时服务两类消费者:模型用它理解能力,Runtime 用它校验调用形状。

解剖一个订单查询 Schema

name
get_order_summary

稳定、动作明确、避免宽泛词

description
读取当前登录客户的一笔订单摘要

说明何时用、不会做什么

properties
orderId: string

字段含义、格式与来源

required
[orderId]

调用时必须提供的字段

additionalProperties
false

拒绝未声明参数

strict
true

让函数参数遵守兼容 Schema

图 1|Schema 的每个字段都在减少模型与 Runtime 之间的猜测空间。
{
  "type": "function",
  "name": "get_order_summary",
  "description": "Read the minimal summary for one order owned by the authenticated customer. Use for order or delivery questions. This tool does not refund, cancel, or modify an order.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Order identifier explicitly supplied by the customer, for example XB-1024."
      }
    },
    "required": ["orderId"],
    "additionalProperties": false
  },
  "strict": true
}

名称和描述决定“何时选”

order_tool 太宽泛,模型不知道它是查订单、改订单还是取消订单。get_order_summary 表明读取行为和结果范围。描述要补充使用条件、限制和易混淆边界,例如“用于客户询问订单或配送;不会执行退款或修改”。

如果同时有 get_order_summary 与 get_tracking_status,要说明前者根据订单号取得订单与物流号,后者根据可信物流号查询承运商状态。工具之间的输入链应清晰。

参数 Schema 决定“怎样调用”

含糊
{
"query": "string",
"user": "string"
}
query 的格式未知;user 可能被模型伪造。
清晰
{
"orderId": "XB-1024"
}
模型只传任务参数;身份由 Runtime 从会话注入。
图 2|不要让模型填写应用已经知道或必须可信的字段。

使用 enum 可以阻止不可能状态,例如物流查询的 detailLevel 只允许 summary 或 events。可选字段在 strict Schema 中可以通过包含 null 表达,同时仍列为 required;这样调用形状稳定。

Schema 只校验形状,handler 仍需业务验证

orderId 是字符串不代表格式合理,更不代表订单存在或属于客户。Tool handler 还要:

  1. 规范化允许的格式,拒绝超长或控制字符。
  2. 从可信会话取得 tenantId 与 customerId。
  3. 在查询条件中强制租户和客户范围。
  4. 将上游响应映射成稳定 Tool Result。
  5. 对日志脱敏,不回传内部错误栈给模型。

Tool Call
↓
Gate 1 · JSON Schema
字段、类型、枚举、额外属性
↓
Gate 2 · Business Validation
格式、身份、租户、权限、当前状态
↓
Execute or Reject

图 3|Strict Schema 减少参数漂移,服务端业务校验守住真实权限。

Failure Lab

Description 只写“查询订单”

为什么诱人: 名称已经看起来很清楚。

为什么失败: 模型不知道何时调用、需要什么前提,也不知道它不能退款或修改。

更好的设计: 写清用途、适用场景、关键限制和相邻工具差异。

一个 Tool 包办查询、退款和取消

为什么诱人: 工具数量少,Schema 集中。

为什么失败: 参数组合产生无效状态,高风险动作与只读查询共享权限。

更好的设计: 按清晰责任和风险拆分;Week 03 只开放查询能力。

把权限字段暴露给模型

为什么诱人: 所有参数都在一个 Schema 里。

为什么失败: 模型可以从客户文本生成 tenantId 或 customerId,绕过可信身份来源。

更好的设计: Schema 只含模型需要决定的任务参数,权限上下文由 Runtime 注入。

实践:评审两个 Schema

为 get_order_summary 与 get_tracking_status 写完整 Schema。让同伴扮演没有项目背景的开发者,只看名称、描述和参数,回答何时使用、需要什么、不会做什么。无法回答的地方就是契约缺口。

Acceptance Criteria

  • ☐ Tool 名称使用明确动词与业务对象。
  • ☐ Description 写清何时用、结果是什么、不会做什么。
  • ☐ 参数字段含类型、含义和必要格式说明。
  • ☐ required、additionalProperties 与 strict 配置一致。
  • ☐ 身份和租户不出现在模型可填写参数中。
  • ☐ 相邻两个 Tool 的使用边界无歧义。
  • ☐ Schema Validation 后仍有业务授权与格式校验。
  • ☐ 至少用 6 个正确/错误调用样例测试 Schema。

合上正文,试着回答

  1. 模型选择 Tool 时通常能看到什么?
  2. Name、Description 和 Parameters 分别解决什么问题?
  3. 为什么 strict Schema 仍不能证明订单归属?
  4. 哪些参数不应暴露给模型?
  5. 怎样判断一个 Tool 责任过宽?

下一课处理 Tool 失败:invalid input、not found、unauthorized、timeout、empty result 与 malformed result 必须引导不同恢复路径。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: Tool Schema 描述能力和参数形状,服务端仍负责身份、权限与业务有效性。当前实现方式: strict mode 的兼容要求和 SDK Schema helper 会更新。