OpenAI API Tools（OpenAI API 工具）
OpenAI API Tools（OpenAI API 工具） 是 OpenAI API 中把模型连接到外部能力的一组接口：模型可以搜索网页、检索文件、按需加载工具定义、请求应用执行自定义函数，或通过 Model Context Protocol（模型上下文协议）访问第三方服务。
这个词条是本库的综述视角，用来归纳 OpenAI 官方 Using tools 文档里的平台能力。它不是单个工具或单个协议，而是 Responses API（响应 API） 和 OpenAI Agents SDK 共同暴露的工具层。
API 层的统一入口
在 Responses API 中，开发者通常通过 tools 参数启用工具能力。每个工具有自己的配置结构，但模型端语义一致：模型根据当前输入判断是否需要调用工具；开发者也可以用 tool_choice 明确控制或引导工具选择。
OpenAI 官方文档把可用工具分成几类：
| 层级 | 能力 | 作用 | 工程含义 |
|---|---|---|---|
| 主工具 | Web search | 在生成回答时引入互联网信息 | 适合需要时效性和引用的任务 |
| 主工具 | File search | 从上传文件或向量存储中检索上下文 | 适合企业知识库、文档问答、RAG |
| 主工具 | Tool search | 运行时按需加载延迟定义的工具 | 降低大工具集对上下文和选择准确率的压力 |
| 主工具 | Function Calling（函数调用） | 调用应用自定义函数 | 让模型请求业务系统执行真实查询或动作 |
| 主工具 | Programmatic Tool Calling（程序化工具调用） | 让模型生成 JavaScript 编排可用工具 | 在托管运行时过滤和聚合中间结果，减少上下文与模型往返 |
| 主工具 | Remote MCP | 连接远程 MCP 服务器 | 把第三方工具服务器接入模型工具层 |
| 主工具 | OpenAI API Connectors | 通过内置 connector 访问常见 SaaS 服务 | 省去自建 remote MCP server，但仍要处理 OAuth、审批和数据边界 |
| 主工具 | Shell / Computer use / Image generation 等托管工具 | 由平台或运行时提供执行能力 | 需要更明确的权限、沙箱和审计边界 |
| Shell 环境能力 | Skills | 把版本化 SKILL.md 文件束挂载到 Shell 环境 | 复用团队流程、脚本、模板和资产 |
其中 tool_search 只由 gpt-5.4 及后续模型支持。它解决的不是“模型会不会调用工具”，而是“工具定义什么时候进入上下文”：常用工具可以直接暴露，低频或大量工具可以延迟加载。
与 Function Calling 的关系
Function Calling（函数调用） 是 OpenAI 工具层里最基础的自定义扩展机制。开发者定义函数名、说明、JSON Schema 和 strict mode；模型返回结构化调用请求；应用执行真实函数后，再把工具结果回填给模型。
OpenAI API Tools 的范围比 Function Calling 更大：Web search、File search、Remote MCP、Shell、Computer use 等都属于工具层，但不都需要开发者自己写函数执行逻辑。可以把 Function Calling 理解为“应用自定义能力”的工具形态，把托管工具和 MCP 理解为“平台或外部服务提供能力”的工具形态。
Programmatic Tool Calling（程序化工具调用）位于直接工具调用之上：它不增加外部能力，而是让模型在隔离 V8 runtime 中用 JavaScript 对已授权工具做并行、循环和结果缩减。只有数据流可预测的阶段应交给它；写入、审批、语义判断和最终核验仍应走直接调用，保留清晰的授权和审计边界。
与 MCP 的关系
Remote MCP 让模型通过远程 Model Context Protocol（模型上下文协议）服务器获得新能力。在 Responses API 请求中，它表现为 type: "mcp" 的工具配置，包含服务器标签、说明、URL 和审批策略等字段。
这说明 MCP 与 OpenAI 工具调用不是替代关系，而是上下两层的组合：
- MCP 负责外部工具服务器如何发现、描述和暴露能力
- Responses API 工具层负责把这些能力呈现给模型，让模型在当前 turn 中选择是否调用
- 应用或平台仍要处理审批、权限、日志和失败恢复
OpenAI 的 MCP 工具支持两种接入形态：一种是用 server_url 指向 remote MCP server；另一种是用 connector_id 调用 OpenAI API Connectors这类平台内置连接器。两者在 response output 中都表现为 mcp_list_tools 和 mcp_call 等结构，差别主要在能力来源、授权和信任边界。
工程上还有三个容易被忽略的点：
- Responses API 会先列举 MCP server 暴露的工具，成功后返回
mcp_list_tools；只要这个 item 留在对话上下文里，后续 turn 不必重复列举工具，可降低延迟 allowed_tools可以只导入一部分工具，defer_loading: true可以配合 tool search 延迟加载大 MCP server 的函数定义，减少上下文和选择成本authorization常用于传 OAuth access token；OpenAI 不会在 Response 对象中保存或回显这个字段值，因此每次创建 response 都要重新传入
因此，MCP 的安全问题不会因为接入 OpenAI API 而消失。远程服务器暴露了什么工具、工具描述是否可信、工具调用是否需要人工审批，仍然是 Agent Guardrails（Agent 护栏） 和 Agent Sandbox（Agent 沙箱） 需要覆盖的边界。
Agents SDK 中的工具语义
在 OpenAI Agents SDK 中，工具语义不变，但接线位置从单次 Responses API 请求移动到 Agent 定义和工作流设计里。常见做法有三种：
- 把托管工具、函数工具或 MCP 工具直接挂到某个 specialist agent 上
- 把一个 specialist agent 暴露成另一个 manager agent 可调用的工具
- 把 shell、apply patch、computer use 等执行 harness 保留在运行时，由 SDK 负责建模工具决策
这对应 Harness Engineering（驾驭工程）中的一条关键分工：SDK 可以描述“谁能调用什么工具”，但真实执行、权限审批、日志审计和回滚策略仍然属于应用运行时。
Skills 作为 Shell 环境能力
Skills 在 OpenAI API 工具层里处于 prompt 和工具之间，但它不是和 Web search、Function Calling、MCP 并列的独立 tools[].type。它必须依附于 Responses API 的 Shell 工具：开发者把 Skill bundle 挂到 Shell 的 environment.skills 下，模型在 Shell 环境中按需读取 SKILL.md、运行脚本、使用模板和资产。Shell 可由 OpenAI 以托管容器方式运行，也可由开发者自管本地 runtime；这两种模式的 Skill 挂载方式不同。
Cookbook 把 Skills 称为 prompts、tools、system prompts 之间的“middle layer”：prompt 定义常驻行为，工具提供原子能力和副作用，Skill 封装可复用流程、脚本和资产。
这使 Skills 特别适合稳定但不该每轮常驻的知识：公司报告格式、数据清洗脚本、发布检查清单、复杂文件转换流程。它和 Tool search 解决的问题相似，都是减少低频能力对上下文的干扰；差别在于 Tool search 延迟加载工具定义，Skills 延迟加载任务过程和支持文件。
SKILL.md 和需要的脚本/资产；OpenAI 托管容器 Shell 用 POST /v1/skills 上传目录或 zip，然后在 Responses API 的 Shell 工具里写 environment.skills: [{"type": "skill_reference", "skill_id": "...", "version": 2}]；local shell 则在 environment.skills 里提供本地 name、description 和 path。使用时要注意三个边界：
- Skill 的
description是模型是否加载它的路由信号，要写清楚触发场景和不适用场景。 - Skill 正文作为用户 prompt 输入进入上下文，不等同于 system prompt；需要确定性触发时，应在任务输入里明确要求使用某个 Skill。
- 生产环境应固定 Skill 版本，并把写入、联网和高影响动作交给 Agent Guardrails（Agent 护栏）处理。
设计取舍
OpenAI API Tools 的核心取舍不是“工具越多越好”。每个工具定义都会消耗上下文，也会增加模型选择错误、权限误用和 prompt injection 的攻击面。
实践上更稳的做法是：
- 常用、高置信、低风险工具直接暴露给模型
- 大量低频工具用 tool search 延迟加载
- 高风险动作通过
tool_choice、审批策略和应用侧权限控制收窄 - 工具描述、参数 schema 和错误返回按 Agent-Computer Interface（智能体计算机接口） 来设计
- 对工具调用轨迹做 trace，和 Evals（评估）一起形成回归数据
换句话说，OpenAI API Tools 把模型“能做事”的入口平台化了；系统是否可靠，仍取决于工具接口、上下文管理、执行环境和治理策略是否配套。
相关概念
- Responses API（响应 API） — OpenAI API Tools 在 API 层的主要承载接口
- Function Calling（函数调用） — 自定义函数工具的结构化调用机制
- OpenAI Agents SDK — 把工具挂到 Agent 定义、handoff 和 workflow 上的编排层
- Model Context Protocol（模型上下文协议） — Remote MCP 工具接入的底层协议
- OpenAI API Connectors — 通过内置 connector 接入 Dropbox、Gmail、Google Drive 等第三方服务
- Agent-Computer Interface（智能体计算机接口） — 工具 schema、描述和结果格式的设计方法论
- Harness Engineering（驾驭工程） — 工具执行、权限、日志、审批和回滚所在的工程层