如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

工具搜索

在运行时按需加载工具,让模型只导入所需的工具定义。

工具搜索让模型能够按需查找工具,并将其动态加载到上下文中。这样,您无需在一开始就将所有工具定义加载到模型的上下文中,有可能减少 Token 总用量并降低总体成本。为优化成本和延迟,工具搜索在设计上会保留模型缓存。模型发现新工具时,这些工具会被添加到上下文窗口的末尾。

在 Responses API 中,只有 gpt-5.4 及后续模型支持 tool_search。

以下配置和示例使用 Responses API。有关如何在会话中加载函数和自动发现 MCP 工具,请参阅 Agents API。

要在 Responses API 中启用工具搜索,您需要完成以下两步:

  1. 将 tool_search 作为工具添加到 tools 数组中。
  2. 如果您使用函数,请为需要延迟加载的函数设置 defer_loading: true。如果您使用 MCP 服务器,请在 MCP 服务器的工具定义中设置 defer_loading: true。

尽量使用命名空间

工具搜索可用于延迟加载的函数、命名空间或 MCP 服务器。建议尽量使用命名空间或 MCP 服务器。我们的模型在训练时主要学习如何搜索这两类工具集合,在这些场景中节省的 Token 通常也更多。

对于命名空间,defer_loading 仅适用于命名空间内的函数,不适用于命名空间对象本身。

请求开始时,模型仍然能看到各个可搜索项的名称和描述。对于命名空间或 MCP 服务器,模型起初只能看到命名空间或服务器的名称和描述。只有在工具搜索加载其中的函数后,模型才能看到各个函数的详细信息。对于单独延迟加载的函数,模型仍能看到函数的名称和描述,因此工具搜索实际延迟加载的主要是参数模式。

为了尽可能节省 Token,建议将延迟加载的函数按用途归入命名空间或 MCP 服务器,并清楚概述每组包含哪些功能。这样,模型就能有针对性地搜索,只加载相关函数。建议每个命名空间包含的函数少于 10 个,以提高 Token 使用效率并改善模型表现。

{
    "tools": [
      {
        "type": "namespace",
        "name": "crm",
        "description": "CRM tools for customer lookup and order management.",
        "tools": [
          {
            "type": "function",
            "name": "list_open_orders",
            "description": "List open orders for a customer ID.",
            "defer_loading": true,
            "parameters": {
              "type": "object",
              "properties": {
                "customer_id": { "type": "string" }
              },
              "required": ["customer_id"],
              "additionalProperties": false
            }
          }
        ]
      },
      {
        "type": "tool_search"
      }
    ]
  }

同一命名空间中可以同时包含延迟加载和立即加载的工具。未设置 defer_loading: true 的工具可以立即调用,而同一命名空间中延迟加载的工具则通过工具搜索加载。

工具搜索类型

您可以选择以下两种工具搜索方式:

  • 托管工具搜索: OpenAI 在您通过请求声明的延迟加载工具中进行搜索,并在同一响应中返回已加载的工具子集。
  • 客户端执行的工具搜索: 模型发出 tool_search_call,您的应用程序执行查找,然后返回相应的 tool_search_output。

如果您在创建请求时已经知道有哪些候选工具,请先使用托管工具搜索。如果需要根据项目状态、租户状态或应用程序控制的其他系统来确定可用工具,请使用客户端执行的工具搜索。

托管工具搜索

如果您已经知道要让模型搜索的全部函数、命名空间或 MCP 服务器,托管工具搜索是最简单的方式。您只需预先声明这些工具,添加 {"type": "tool_search"},然后由 API 决定加载哪些工具。

配置托管工具搜索
from openai import OpenAI

client = OpenAI()

crm_namespace = {
    "type": "namespace",
    "name": "crm",
    "description": "CRM tools for customer lookup and order management.",
    "tools": [
        {
            "type": "function",
            "name": "get_customer_profile",
            "description": "Fetch a customer profile by customer ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "customer_id": {"type": "string"},
                },
                "required": ["customer_id"],
                "additionalProperties": False,
            },
        },
        {
            "type": "function",
            "name": "list_open_orders",
            "description": "List open orders for a customer ID.",
            "defer_loading": True,
            "parameters": {
                "type": "object",
                "properties": {
                    "customer_id": {"type": "string"},
                },
                "required": ["customer_id"],
                "additionalProperties": False,
            },
        },
    ],
}

response = client.responses.create(
    model="gpt-6.2-astra",
    input="List open orders for customer CUST-12345.",
    tools=[
        crm_namespace,
        {"type": "tool_search"},
    ],
    parallel_tool_calls=False,
)

print(response.output)

如果模型判断需要某个延迟加载的工具,响应会在最终的函数调用之前额外包含两个输出项:

  • tool_search_call 记录托管搜索步骤。
  • tool_search_output 包含已加载且可供调用的工具子集。
托管工具搜索响应
[
  {
    "type": "tool_search_call",
    "execution": "server",
    "call_id": null,
    "status": "completed",
    "arguments": {
      "paths": ["crm"]
    }
  },
  {
    "type": "tool_search_output",
    "execution": "server",
    "call_id": null,
    "status": "completed",
    "tools": [
      {
        "type": "namespace",
        "name": "crm",
        "description": "CRM tools for customer lookup and order management.",
        "tools": [
          {
            "type": "function",
            "name": "list_open_orders",
            "description": "List open orders for a customer ID.",
            "defer_loading": true,
            "parameters": {
              "type": "object",
              "properties": {
                "customer_id": { "type": "string" }
              },
              "required": ["customer_id"],
              "additionalProperties": false
            }
          }
        ]
      }
    ]
  },
  {
    "type": "function_call",
    "name": "list_open_orders",
    "namespace": "crm",
    "call_id": "call_abc123",
    "arguments": "{\"customer_id\":\"CUST-12345\"}"
  }
]

在托管模式下,execution 设为 server,call_id 设为 null。

对于较复杂的任务,模型还可以在同一次 tool_search_call 中加载多个命名空间或 MCP 服务器。例如,如果完成一项任务需要使用不同命名空间中的函数,模型可能会选择先一并搜索并加载这些命名空间,再执行后续的函数调用。

客户端执行的工具搜索

使用客户端执行的工具搜索,您的应用程序可以完全控制工具的发现方式。如果需要根据某些信息来确定可用工具,而这些信息不便在初始 tools 列表中声明,就可以采用这种方式。

配置 tool_search 工具时,请设置 execution: "client",并提供模式来定义应用程序预期接收的搜索参数:

配置客户端执行的工具搜索
from openai import OpenAI

client = OpenAI()

first_response = client.responses.create(
    model="gpt-6.2-astra",
    input="Find the shipping ETA tool first, then use it for order_42.",
    tools=[
        {
            "type": "tool_search",
            "execution": "client",
            "description": "Find the project-specific tools needed to continue the task.",
            "parameters": {
                "type": "object",
                "properties": {
                    "goal": {"type": "string"},
                },
                "required": ["goal"],
                "additionalProperties": False,
            },
        }
    ],
    parallel_tool_calls=False,
)

search_call = next(
    item for item in first_response.output if item.type == "tool_search_call"
)

loaded_tools = [
    {
        "type": "function",
        "name": "get_shipping_eta",
        "description": "Look up shipping ETA details for an order.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
            },
            "required": ["order_id"],
            "additionalProperties": False,
        },
    }
]

second_response = client.responses.create(
    model="gpt-6.2-astra",
    previous_response_id=first_response.id,
    input=[
        {
            "type": "tool_search_output",
            "execution": "client",
            "call_id": search_call.call_id,
            "status": "completed",
            "tools": loaded_tools,
        },
    ],
)

print(second_response.output)

在第一轮中,模型发出 tool_search_call 后便结束本轮:

客户端工具搜索调用
[
  {
    "type": "tool_search_call",
    "execution": "client",
    "call_id": "call_abc123",
    "status": "completed",
    "arguments": {
      "goal": "Find the shipping ETA tool for order_42."
    }
  }
]

随后,您的应用程序执行搜索,并返回 tool_search_output,其中包含要加载的工具:

返回 tool_search_output
[
  {
    "type": "tool_search_output",
    "execution": "client",
    "call_id": "call_abc123",
    "status": "completed",
    "tools": [
      {
        "type": "function",
        "name": "get_shipping_eta",
        "description": "Look up shipping ETA details for an order.",
        "defer_loading": true,
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    ]
  }
]

在下一轮中,模型便可以像调用普通函数一样调用已加载的工具:

调用已加载的函数
[
  {
    "type": "function_call",
    "name": "get_shipping_eta",
    "namespace": "get_shipping_eta",
    "call_id": "call_xyz456",
    "arguments": "{\"order_id\":\"order_42\"}"
  }
]

在客户端模式下,execution 设为 client,且 call_id 有明确的值。请将同一个 call_id 从 tool_search_call 原样传回到 tool_search_output 中。

高级用法

清楚描述命名空间

请在命名空间描述中清楚说明其用途。模型会根据这段描述决定何时加载该命名空间中的部分函数。避免让命名空间描述过长。更详细的信息可以写在延迟加载的函数描述中,这些描述只在需要时加载。

了解哪些工具会被加载

tool_search_output.tools 列出了模型动态加载的工具。模型可以在后续轮次调用其中的任一工具,因此在客户端模式下,您无需在不同轮次重复加载同一个工具。模型无法使用未列入该数组的工具。如果您想禁用某个已加载的工具,可以从定义已加载工具集的 tool_search_output 项中移除该工具。请注意,更改已加载的工具集会使模型缓存从该位置起失效。

高级工具注入方式

大多数集成会在请求的 tools 参数中声明工具。客户端执行的工具搜索还支持更高级的用法,允许应用程序返回原始请求中未声明的工具。采用这种高级工作流时,请仔细验证返回的模式,并且只向模型提供可信的工具定义。

工具搜索与缓存

所有工具都加载到模型上下文窗口的末尾。托管工具搜索和客户端执行的工具搜索均采用这种方式。因此,模型可以在不同请求之间复用缓存,从而降低总体成本并加快处理速度。

在输入的指定位置添加工具

对于高级工作流,您可以使用 additional_tools 输入项,让工具从对话中的指定位置开始可用。如果您的应用程序在常规工具搜索流程之外加载工具,或需要保留先前响应中添加工具的顺序,这种方式就很有用。

请将 role 设为 developer,并在该项的 tools 数组中列出要添加的工具:

{
    "type": "additional_tools",
    "role": "developer",
    "tools": [
      {
        "type": "function",
        "name": "get_customer",
        "description": "Look up a customer by ID.",
        "parameters": {
          "type": "object",
          "properties": {
            "customer_id": { "type": "string" }
          },
          "required": ["customer_id"],
          "additionalProperties": false
        }
      }
    ]
  }

只有当 additional_tools 项出现在输入中之后,其中的工具才可用。如果您手动将对话项传回模型,请保留该项的位置,以便模型在对话的同一位置看到相同的工具。

Agents API

Agents API 默认会预先加载函数定义。要延迟加载指定函数,请将 { "type": "tool_search" } 添加到 agent.tools 中,并为每个需要智能体按需发现的函数设置 defer_loading: true。添加 tool_search 不会自动延迟加载所有函数。

您的会话请求仍需提供完整的函数定义,包括名称、描述和参数模式。工具搜索改变的是模型获取该定义的时间。模型发现函数后,您的应用程序仍按常规方式处理函数调用并返回结果。有关如何处理结果,请参阅函数。

运行此示例前,请设置 OPENAI_API_KEY:

按需加载函数工具
import OpenAI from "openai";
const client = new OpenAI();

const result = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "tool_search",
      },
      {
        type: "function",
        name: "lookup_account",
        description: "Find an account by its account number.",
        parameters: {
          type: "object",
          properties: {
            account_id: {
              type: "string",
            },
          },
          required: ["account_id"],
          additionalProperties: false,
        },
        defer_loading: true,
      },
    ],
  },
  environment: {
    type: "none",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Look up account 42.",
        },
      ],
    },
  ],
});
console.log(result.id);

选择函数加载策略

策略 配置 适用场景 权衡
预先加载 省略 defer_loading 或将其设为 false。 函数数量较少,或大多数任务都需要这些函数。 未使用的函数定义也会占用上下文空间。修改定义可能会使已缓存的前缀失效。
延迟加载 设置 defer_loading: true 并添加 tool_search。 函数目录很大,但每项任务只需要少量函数。 工具发现会增加一个步骤,而且只有找到相关工具才能调用它。

Agents API 支持在同一会话中同时使用预先加载和延迟加载的函数,但通常不建议混用。请为延迟加载的函数提供清晰的名称和描述。在选择默认策略之前,请使用有代表性的请求,比较不同策略下的任务完成情况、输入 Token 用量和延迟。

MCP 工具和插件工具

当模型和提供商支持工具搜索时,Agents API 会自动发现 MCP 工具。运行时会延迟加载 MCP 工具,并在有可搜索的延迟加载工具时添加工具搜索。这适用于远程 MCP 服务器、执行器 MCP 服务器以及插件提供的 MCP 工具。

您无需专门为 MCP 工具添加 { "type": "tool_search" },也无需在 MCP 服务器上设置函数级别的 defer_loading 标志。请按照 MCP 连接指南配置服务器。本指南前面介绍的 Responses API 配置不适用于 Agents API 中的 MCP 服务器。

相关指南

  • 使用函数调用定义可调用的函数和自定义工具。
  • 阅读使用工具,全面了解 Responses API 中可用的工具。