如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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-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-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-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 提供的工具,請參閱使用工具。