来源: OpenAI API 文档 — Tool search
说明: 本文是基于 OpenAI 官方文档整理的中文译介,保留原文技术要点并对示例做了精简。API 能力可能更新,请以原文为准。
当 Agent 可用的工具越来越多,把所有工具定义一次性塞进模型上下文会带来明显成本:大量参数 Schema 占用输入 Token,工具变更还可能破坏提示缓存。**Tool Search(工具搜索)**解决的正是这个问题——模型在运行时搜索并加载当前任务真正需要的工具,而不是在请求开始时导入完整工具目录。
新发现的工具会被追加到上下文末尾。这种设计尽量保留已有缓存前缀,因此既能降低 Token 消耗,也有助于改善延迟。
在 Responses API 中,tool_search 仅受 gpt-5.4 及之后的模型支持。
快速开始 在 Responses API 中启用工具搜索需要两步:
在 tools 数组中加入 { "type": "tool_search" }。 给希望按需加载的函数或 MCP Server 设置 defer_loading: true。 最小配置如下:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "tools": [ { "type": "namespace", "name": "crm", "description": "用于查询客户与管理订单的 CRM 工具。", "tools": [ { "type": "function", "name": "list_open_orders", "description": "按客户 ID 查询未完成订单。", "defer_loading": true, "parameters": { "type": "object", "properties": { "customer_id": { "type": "string" } }, "required": ["customer_id"], "additionalProperties": false } } ] }, { "type": "tool_search" } ] } 尽量使用命名空间 工具搜索可以作用于延迟加载的单个函数、命名空间(namespace)或 MCP Server。OpenAI 更推荐后两种形式,因为模型主要针对这些搜索界面进行过训练,而且通常能节省更多 Token。
...