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

AI Agent Engineering · Week 03

03-01|Tool 到底是什么

区分 LLM、Tool Schema、Runtime 与 Business System 的责任,把模型的行动建议变成受控能力调用。

Tool Calling · Runtime · Business System

模型说“查询订单”时,订单在哪里被查

模型无法因为生成 lookup_order 这几个字就进入 ERP。应用先向模型描述可用 Tool;模型返回调用请求;Runtime 校验参数和权限;工具处理器调用业务系统;结果再回到 Agent Loop。

Tool 是一项受控能力的接口。它把模型可以提出的意图,连接到应用愿意执行的代码。业务 API、数据库和 Shopify / ERP 仍然是事实与动作的实际来源。

四层职责图

选择
LLM

根据目标和观察提出 Tool Call

描述
Tool Schema

说明能力、参数与使用边界

校验并执行
Runtime

检查白名单、参数、权限与预算

提供事实
Business System

订单、物流和执行结果的真源

LLM → Tool Call → Runtime → API / DB → Tool Result → LLM
图 1|模型负责选择,Schema 负责描述,Runtime 负责执行,业务系统负责事实。

Tool 不等于 API,也不等于函数名

  • API 是业务系统对外提供的接口,例如根据订单 ID 查询订单。
  • Tool handler 是应用中的适配代码,接收经过校验的调用,再访问 API 或数据库。
  • Tool Schema 是给模型看的能力契约,描述名称、用途与参数。
  • Tool Call 是模型提出的一次调用请求。
  • Tool Result 是 Runtime 执行后的结构化结果。

同一个 get_order_summary Tool 可以在教学环境读取安全 Mock,在测试环境调用沙箱 API,在生产环境调用受权限控制的 ERP。对模型保持稳定契约,对后端适配不同实现。

查询 Tool 与动作 Tool

Read Tool

读取订单摘要、查询物流。

  • 仍需身份与租户校验
  • 返回最小必要字段
  • 可以按策略安全重试
Action Tool

取消订单、提交退款、改地址。

  • 需要更高权限
  • 需要幂等、审批和审计
  • 重试可能重复副作用
图 2|“工具可调用”不代表“动作可自动执行”。Week 03 只实现安全查询 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

图 3|模型传递任务参数;可信身份范围由服务端注入,不能从客户文本推断。

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 失败后模型没有可用事实时不会猜结果。

合上正文,试着回答

  1. Tool、Tool Schema、Tool Call 和 API 有什么区别?
  2. 为什么业务系统才是事实来源?
  3. 哪些参数应由 Runtime 注入而不是模型填写?
  4. 查询 Tool 与动作 Tool 为什么要使用不同策略?
  5. Agent 选择正确工具后,任务为什么仍可能失败?

下一课会解剖 Tool Schema:名称、描述、参数类型、枚举和 required 怎样共同影响模型选择与 Runtime 校验。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: 模型提出调用,Runtime 校验执行,业务系统提供事实。当前实现方式: Tool 可以是本地函数、托管工具或远端服务,具体接入将在后续课程展开。