AI Agent Engineering · Week 03
03-01|Tool 到底是什么
区分 LLM、Tool Schema、Runtime 与 Business System 的责任,把模型的行动建议变成受控能力调用。
模型说“查询订单”时,订单在哪里被查
模型无法因为生成 lookup_order 这几个字就进入 ERP。应用先向模型描述可用 Tool;模型返回调用请求;Runtime 校验参数和权限;工具处理器调用业务系统;结果再回到 Agent Loop。
Tool 是一项受控能力的接口。它把模型可以提出的意图,连接到应用愿意执行的代码。业务 API、数据库和 Shopify / ERP 仍然是事实与动作的实际来源。
四层职责图
LLM
根据目标和观察提出 Tool Call
Tool Schema
说明能力、参数与使用边界
Runtime
检查白名单、参数、权限与预算
Business System
订单、物流和执行结果的真源
Tool 不等于 API,也不等于函数名
- API 是业务系统对外提供的接口,例如根据订单 ID 查询订单。
- Tool handler 是应用中的适配代码,接收经过校验的调用,再访问 API 或数据库。
- Tool Schema 是给模型看的能力契约,描述名称、用途与参数。
- Tool Call 是模型提出的一次调用请求。
- Tool Result 是 Runtime 执行后的结构化结果。
同一个 get_order_summary Tool 可以在教学环境读取安全 Mock,在测试环境调用沙箱 API,在生产环境调用受权限控制的 ERP。对模型保持稳定契约,对后端适配不同实现。
查询 Tool 与动作 Tool
读取订单摘要、查询物流。
- 仍需身份与租户校验
- 返回最小必要字段
- 可以按策略安全重试
取消订单、提交退款、改地址。
- 需要更高权限
- 需要幂等、审批和审计
- 重试可能重复副作用
V0.3 的两个 Tool
get_order_summary
输入由模型提供 orderId,客户身份与店铺范围由 Runtime 从可信会话注入,不让模型填写。输出只含后续需要的状态、物流号或稳定错误。
get_tracking_status
输入使用前一个工具返回的可信 trackingId。输出包含承运商状态、更新时间和预计送达时间。没有数据时返回 empty_result,不能用语言模型补齐。
Customer Message
↓
Agent selects get_order_summary
↓
Runtime injects tenant + customer scope
↓
Order System returns trackingId
↓
Agent selects get_tracking_status
↓
Carrier returns verified status
Failure Lab
把整张订单对象返回给模型
为什么诱人: 以后需要什么字段都有。
为什么失败: 增加隐私暴露、Context 和错误使用风险,内部字段还可能没有稳定语义。
更好的设计: Tool 返回完成当前任务的最小字段,并给每个字段明确含义。
让模型提供 customerId 与 tenantId
为什么诱人: Schema 看起来完整。
为什么失败: 模型可能从不可信消息中提取别人的身份,形成越权查询。
更好的设计: Runtime 从已验证会话注入身份和租户,Tool handler 再做服务端授权。
把 Tool Call 当成 Tool Success
为什么诱人: 模型已经正确选择了工具。
为什么失败: API 可能超时、拒绝或返回空结果。
更好的设计: 只有结构化 Tool Result 才能产生事实;最终回复必须依据结果状态。
实践:写两个 Tool Contract
分别为订单和物流查询写 Name、Purpose、When to use、Inputs、Trusted server context、Output、Errors、Side effects。明确哪些字段模型提供、哪些字段 Runtime 注入、哪些错误可以重试。
Acceptance Criteria
- ☐ 能解释 LLM、Schema、Runtime 与 Business System 四层责任。
- ☐ 两个 Tool 都有最小且明确的输入输出。
- ☐ tenantId、customerId 不由模型提供。
- ☐ 订单 Tool 不返回与物流任务无关的敏感字段。
- ☐ 查询与动作 Tool 的风险策略分开。
- ☐ Tool Call、Tool Result 与 final response 在 Trace 中可区分。
- ☐ Tool 失败后模型没有可用事实时不会猜结果。
合上正文,试着回答
- Tool、Tool Schema、Tool Call 和 API 有什么区别?
- 为什么业务系统才是事实来源?
- 哪些参数应由 Runtime 注入而不是模型填写?
- 查询 Tool 与动作 Tool 为什么要使用不同策略?
- Agent 选择正确工具后,任务为什么仍可能失败?
下一课会解剖 Tool Schema:名称、描述、参数类型、枚举和 required 怎样共同影响模型选择与 Runtime 校验。
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI API:Function calling。用于核对 Tool、Tool Call、Tool Output 和应用执行的分工。
- OpenAI Agents SDK:Tools。用于核对函数工具、Schema 生成与错误处理能力。
- OWASP:Authorization Cheat Sheet。用于核对服务端授权与最小权限原则。
长期有效的原理: 模型提出调用,Runtime 校验执行,业务系统提供事实。当前实现方式: Tool 可以是本地函数、托管工具或远端服务,具体接入将在后续课程展开。