AI Agent Engineering · Week 03
03-02|Tool Schema:模型凭什么知道工具怎么用
解剖 Tool Schema 的名称、描述、参数、枚举与 strict 约束,设计模型和 Runtime 都能正确消费的能力接口。
模型看到的不是你的函数实现
模型选择 Tool 时,通常看到名称、描述和参数 Schema。它不知道函数内部查哪个数据库,也不知道某个缩写在团队里的隐含含义。Schema 写得含糊,模型就会在错误时机调用、传错参数,或选择相邻工具。
Tool Schema 同时服务两类消费者:模型用它理解能力,Runtime 用它校验调用形状。
解剖一个订单查询 Schema
nameget_order_summary
稳定、动作明确、避免宽泛词
description读取当前登录客户的一笔订单摘要
说明何时用、不会做什么
propertiesorderId: string
字段含义、格式与来源
required[orderId]
调用时必须提供的字段
additionalPropertiesfalse
拒绝未声明参数
stricttrue
让函数参数遵守兼容 Schema
{
"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 从会话注入。使用 enum 可以阻止不可能状态,例如物流查询的 detailLevel 只允许 summary 或 events。可选字段在 strict Schema 中可以通过包含 null 表达,同时仍列为 required;这样调用形状稳定。
Schema 只校验形状,handler 仍需业务验证
orderId 是字符串不代表格式合理,更不代表订单存在或属于客户。Tool handler 还要:
- 规范化允许的格式,拒绝超长或控制字符。
- 从可信会话取得 tenantId 与 customerId。
- 在查询条件中强制租户和客户范围。
- 将上游响应映射成稳定 Tool Result。
- 对日志脱敏,不回传内部错误栈给模型。
Tool Call
↓
Gate 1 · JSON Schema
字段、类型、枚举、额外属性
↓
Gate 2 · Business Validation
格式、身份、租户、权限、当前状态
↓
Execute or Reject
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。
合上正文,试着回答
- 模型选择 Tool 时通常能看到什么?
- Name、Description 和 Parameters 分别解决什么问题?
- 为什么 strict Schema 仍不能证明订单归属?
- 哪些参数不应暴露给模型?
- 怎样判断一个 Tool 责任过宽?
下一课处理 Tool 失败:invalid input、not found、unauthorized、timeout、empty result 与 malformed result 必须引导不同恢复路径。
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI API:Function calling。用于核对函数名称、描述、parameters、strict 和最佳实践。
- JSON Schema:Understanding JSON Schema。用于核对类型、required、enum 与 additionalProperties。
- OpenAI Agents SDK:Tools。用于核对函数工具的 Schema 生成与运行方式。
长期有效的原理: Tool Schema 描述能力和参数形状,服务端仍负责身份、权限与业务有效性。当前实现方式: strict mode 的兼容要求和 SDK Schema helper 会更新。