Tools：能力、Schema 与执行边界
Tool 把读取、计算或行动封装成有名称、输入、输出、权限和错误契约的能力。
学习目标
- 能说明Tools：能力、Schema 与执行边界解决什么问题，以及何时适用。
- 能解释为什么“自然语言描述代替 Schema”是误区。
学习前需要掌握
背景与问题
语言模型能描述如何查询库存或计算总额，却不能仅凭生成文字获得最新业务数据。Tool 把任务与真实执行能力连接起来，让系统通过受控接口读取、计算或改变外部世界。
工具可能是本地函数、远程 API、文件操作或另一个 Agent。形式不同，但都要回答同样的实际问题：能做什么、参数是什么、结果如何判断、允许影响哪些资源。
概念定义
Tool 是 Agent 可以请求调用、由宿主或服务执行的具体能力。它可以是内置工具、函数工具、API、本地文件/搜索/代码/计算工具，或另一个 Agent。
直观理解
Skill 是操作手册，Tool 是真正完成动作的仪器；说明书不会自己钻孔，电钻也不会决定项目流程。
核心原理
工具契约至少描述名称、用途、输入结构和返回结构。名称帮助识别，描述帮助选择，Schema 帮助检查参数形状；这些信息不应夸大工具能力，例如一个搜索工具不能保证其结果覆盖全部资料。
真实实现负责执行，并返回可判定的状态、数据与错误信息。模型提出调用不代表已经执行，执行返回成功也不保证满足用户任务；调用者仍要核对对象、范围、版本和证据。
按副作用区分只读、幂等写入与可能重复产生效果的动作，可以指导审批与重试。只读也有信息泄露风险，写入则还要考虑并发冲突、重复调用与无法撤销的后果。
工具边界应落实超时、权限和资源限制，并记录调用标识与必要摘要。适度粒度有助于验证：过大的“自动完成所有工作”工具隐藏失败位置，过细的工具又可能让模型承担本可由确定性代码处理的重复步骤。
案例：计算订单总额与提交订单是两种工具
报价工具输入商品、数量与地区，返回带币种和有效期的价格明细；它只计算候选金额，不创建订单。提交工具则需要已确认的报价标识、账户与幂等键，成功后返回真实订单号。
Agent 可以多次比较报价，但不能把报价成功当成下单成功。若报价过期，提交前应重新获取并处理金额变化；若下单响应丢失，应查原请求状态而不是直接再下单。把两个能力拆清楚，能让用户确认与系统重试都绑定到正确动作。
理解与实践步骤
- 定义单一职责工具
- 编写输入输出 Schema
- 标记只读或写入与权限
- 执行前验证和审批
- 设置超时与有限重试
- 返回结构化成功或错误
- 验证结果并记录日志
实际应用
- 内置搜索
- 函数与 API
- 本地文件
- 代码与数学计算
- Agent as Tool
常见错误
- 只提供一句自然语言介绍，没有明确参数、结果状态与失败契约。
- 把工具描述中的只读或安全标记当作执行权限，不检查真实实现和访问范围。
- 不区分查询与写入，对所有失败统一重试，或直接把工具原始输出当作最终答案。
输入、输出与执行边界
输入
- 工具名
- 结构化参数
- 授权与调用上下文
输出
- 结构化数据
- 副作用确认
- 可分类错误
能力
- 内置搜索
- 函数与 API
- 本地文件
- 代码与数学计算
- Agent as Tool
权限
- 每次调用按身份与资源重新授权
- 敏感或写入操作默认审批
安全风险与信任边界
读取、计算与写入工具的后果不同，接口说明应明确输入对象和副作用。即便结果来自工具，也可能受过期数据、错误记录或外部文本影响；模型需要验证业务含义，不能把工具包装当成结果真实性的担保。
性能与失败模式
测量工具本身的执行耗时之外，还要计入参数准备、返回解析与失败恢复。批处理和并行只适用于独立操作，庞大返回内容会增加模型后续成本；评价应依据是否完成实际任务，而非工具调用数量越多越好。
推荐学习资料
OpenAI Agents SDK 文档
系统介绍 Agent、工具、Handoff、Guardrail、Session 与追踪等核心组件。
OpenAI · OpenAI
资料笔记
OpenAI Tools Guide
说明模型如何调用函数、搜索、计算机操作及其他工具，并展示结构化参数。
OpenAI · OpenAI Platform
资料笔记
openai/openai-agents-python
OpenAI Agents SDK 的 Python 源码、文档、示例与集成测试仓库。
OpenAI · GitHub
仓库信息
构建和研究多 Agent 工作流
主要语言：Python包含数据集或实验需要额外环境