Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Tool-Suche

Lade Tools bei Bedarf zur Laufzeit, damit Modelle nur die Definitionen importieren, die sie brauchen.

Mit der Tool-Suche kann das Modell bei Bedarf nach Tools suchen und sie in seinen Kontext laden. So musst du nicht schon zu Beginn alle Tool-Definitionen in den Modellkontext laden. Das kann den Token-Verbrauch und die Kosten insgesamt senken. Um Kosten und Latenz möglichst gering zu halten, ist die Tool-Suche darauf ausgelegt, den Cache des Modells zu erhalten. Neu gefundene Tools werden am Ende des Kontextfensters eingefügt.

In der Responses API unterstützen nur gpt-5.4 und neuere Modelle tool_search.

Die folgende Konfiguration und die Beispiele verwenden die Responses API. Wie Funktionen innerhalb einer Sitzung geladen und MCP-Tools automatisch gefunden werden, erfährst du im Abschnitt Agents API.

Um die Tool-Suche in der Responses API zu aktivieren, sind zwei Schritte nötig:

  1. Füge tool_search als Tool zu deinem tools-Array hinzu.
  2. Wenn du Funktionen verwendest, kennzeichne diejenigen, die erst bei Bedarf geladen werden sollen, mit defer_loading: true. Wenn du MCP-Server verwendest, setze defer_loading: true in der Tool-Definition des jeweiligen MCP-Servers.

Möglichst Namensräume verwenden

Du kannst die Tool-Suche für Funktionen, Namensräume oder MCP-Server verwenden, wenn du Tools erst bei Bedarf laden möchtest. Wir empfehlen, nach Möglichkeit Namensräume oder MCP-Server zu verwenden. Unsere Modelle wurden vor allem darauf trainiert, diese zu durchsuchen. Außerdem sparst du damit meist deutlich mehr Token.

Bei Namensräumen gilt defer_loading für die darin enthaltenen Funktionen. Das Namensraumobjekt selbst ist davon ausgenommen.

Zu Beginn einer Anfrage sieht das Modell weiterhin den Namen und die Beschreibung jedes durchsuchbaren Eintrags. Bei einem Namensraum oder MCP-Server sieht es zunächst nur den Namen und die Beschreibung des Namensraums oder Servers. Details zu den einzelnen Funktionen sieht es erst, wenn die Tool-Suche sie lädt. Bei einer einzelnen Funktion, die erst bei Bedarf geladen wird, sieht das Modell weiterhin den Funktionsnamen und die Beschreibung. In der Praxis schiebt die Tool-Suche hier also vor allem das Laden des Parameterschemas auf.

Um möglichst viele Token zu sparen, gruppiere Funktionen, die erst bei Bedarf geladen werden, in Namensräumen oder auf MCP-Servern. Beschreibe jeweils kurz und klar, welche Funktionen die Gruppe umfasst. So kann das Modell gezielt suchen und nur die relevanten Funktionen laden. Beschränke jeden Namensraum möglichst auf weniger als 10 Funktionen, damit das Modell effizienter mit Token umgeht und bessere Ergebnisse erzielt.

{
    "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"
      }
    ]
  }

Ein Namensraum kann sowohl sofort verfügbare Tools als auch Tools enthalten, die erst bei Bedarf geladen werden. Tools ohne defer_loading: true sind sofort aufrufbar. Die übrigen Tools im selben Namensraum lädt die Tool-Suche bei Bedarf.

Varianten der Tool-Suche

Du hast die Wahl zwischen zwei Varianten:

  • Gehostete Tool-Suche: OpenAI durchsucht die Tools, die du in der Anfrage zum Laden bei Bedarf deklariert hast, und gibt die geladenen Tools in derselben Antwort zurück.
  • Clientseitige Tool-Suche: Das Modell gibt einen tool_search_call aus, deine Anwendung führt die Suche durch und du gibst das passende tool_search_output zurück.

Beginne mit der gehosteten Tool-Suche, wenn beim Erstellen der Anfrage bereits feststeht, welche Tools infrage kommen. Verwende die clientseitige Tool-Suche, wenn die Auswahl der Tools vom aktuellen Zustand des Projekts, des Mandanten oder eines anderen Systems abhängt, das deine Anwendung steuert.

Gehostete Tool-Suche

Die gehostete Tool-Suche ist die einfachste Variante, wenn du bereits alle Funktionen, Namensräume oder MCP-Server kennst, die das Modell durchsuchen soll. Du deklarierst sie vorab, fügst {"type": "tool_search"} hinzu und überlässt der API die Entscheidung, welche Tools sie lädt.

Gehostete Tool-Suche konfigurieren
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)

Wenn das Modell feststellt, dass es ein noch nicht geladenes Tool benötigt, enthält die Antwort vor dem eigentlichen Funktionsaufruf zwei zusätzliche Ausgabeelemente:

  • tool_search_call dokumentiert die gehostete Suche.
  • tool_search_output enthält die geladenen Tools, die jetzt aufrufbar sind.
Antwort der gehosteten Tool-Suche
[
  {
    "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\"}"
  }
]

Im gehosteten Modus hat execution den Wert server und call_id den Wert null.

Bei komplexeren Aufgaben kann das Modell mit demselben tool_search_call auch mehrere Namensräume oder MCP-Server laden. Benötigt es für eine Aufgabe etwa Funktionen aus verschiedenen Namensräumen, kann es diese gemeinsam durchsuchen und laden, bevor es die Funktionen aufruft.

Clientseitige Tool-Suche

Bei der clientseitigen Tool-Suche bestimmt deine Anwendung selbst, wie sie nach Tools sucht. Das ist sinnvoll, wenn die verfügbaren Tools von Informationen abhängen, die sich in der ursprünglichen tools-Liste nur schwer angeben lassen.

Konfiguriere das Tool tool_search mit execution: "client" und einem Schema für die Suchargumente, die deine Anwendung erwartet:

Clientseitige Tool-Suche konfigurieren
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)

Im ersten Schritt gibt das Modell einen tool_search_call aus und beendet damit seine Antwort:

Aufruf der clientseitigen Tool-Suche
[
  {
    "type": "tool_search_call",
    "execution": "client",
    "call_id": "call_abc123",
    "status": "completed",
    "arguments": {
      "goal": "Find the shipping ETA tool for order_42."
    }
  }
]

Deine Anwendung führt dann die Suche aus und gibt ein tool_search_output mit den Tools zurück, die sie laden möchte:

tool_search_output zurückgeben
[
  {
    "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
        }
      }
    ]
  }
]

Im nächsten Schritt kann das Modell das geladene Tool wie eine normale Funktion aufrufen:

Aufruf der geladenen Funktion
[
  {
    "type": "function_call",
    "name": "get_shipping_eta",
    "namespace": "get_shipping_eta",
    "call_id": "call_xyz456",
    "arguments": "{\"order_id\":\"order_42\"}"
  }
]

Im Clientmodus hat execution den Wert client und call_id ist definiert. Gib dieselbe call_id aus dem tool_search_call in deinem tool_search_output zurück.

Erweiterte Verwendung

Namensräume klar beschreiben

Beschreibe den Einsatzzweck jedes Namensraums klar. Anhand dieser Beschreibung entscheidet das Modell, wann es einzelne Funktionen aus dem Namensraum lädt. Halte die Beschreibung kurz. Ausführlichere Details gehören in die Beschreibungen der einzelnen Funktionen, die erst bei Bedarf geladen werden.

Welche Tools geladen werden

tool_search_output.tools enthält die Liste der Tools, die das Modell dynamisch geladen hat. Das Modell kann jedes dieser Tools in späteren Gesprächsschritten aufrufen. Im Clientmodus musst du dasselbe Tool also nicht für jeden Schritt neu laden. Tools, die in diesem Array fehlen, stehen dem Modell nicht zur Verfügung. Um ein geladenes Tool zu deaktivieren, kannst du es aus dem tool_search_output-Element entfernen, in dem du die geladenen Tools festlegst. Beachte dabei, dass jede Änderung an dieser Auswahl den Modellcache ab dieser Stelle ungültig macht.

Weitere Möglichkeiten zum Einfügen von Tools

Die meisten Integrationen deklarieren Tools im Parameter tools der Anfrage. Bei der clientseitigen Tool-Suche kann deine Anwendung auch Tools zurückgeben, die in der ursprünglichen Anfrage nicht enthalten waren. Diese Variante ist für fortgeschrittene Workflows gedacht. Prüfe die zurückgegebenen Schemas sorgfältig und stelle nur vertrauenswürdige Tool-Definitionen bereit.

Tool-Suche und Caching

Alle Tools werden am Ende des Kontextfensters des Modells geladen. Das gilt sowohl für die gehostete als auch für die clientseitige Tool-Suche. So kann der Modellcache über mehrere Anfragen hinweg erhalten bleiben. Das senkt die Gesamtkosten und beschleunigt die Verarbeitung.

Tools an einer bestimmten Stelle der Eingabe hinzufügen

In fortgeschrittenen Workflows kannst du mit einem additional_tools-Eingabeelement Tools ab einer bestimmten Stelle im Gespräch verfügbar machen. Das ist sinnvoll, wenn deine Anwendung Tools außerhalb der üblichen Tool-Suche lädt oder die Reihenfolge beibehalten muss, in der Tools während einer früheren Antwort hinzugefügt wurden.

Setze role auf developer und trage die hinzuzufügenden Tools in das tools-Array des Elements ein:

{
    "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
        }
      }
    ]
  }

Tools aus einem additional_tools-Element stehen erst nach diesem Element in der Eingabe zur Verfügung. Wenn du Gesprächselemente manuell in der nächsten Anfrage mitsendest, behalte die Position des Elements bei. So sieht das Modell dieselben Tools an derselben Stelle im Gespräch.

Agents API

Die Agents API lädt Funktionsdefinitionen standardmäßig sofort. Wenn du ausgewählte Funktionen erst bei Bedarf laden möchtest, füge { "type": "tool_search" } zu agent.tools hinzu und setze defer_loading: true für jede Funktion, die der Agent bei Bedarf finden soll. Das Hinzufügen von tool_search allein schiebt das Laden der übrigen Funktionen nicht auf.

Deine Sitzungsanfrage enthält weiterhin die vollständige Funktionsdefinition mit Name, Beschreibung und Argumentschema. Die Tool-Suche ändert den Zeitpunkt, zu dem das Modell diese Definition erhält. Sobald das Modell die Funktion gefunden hat, verarbeitet deine Anwendung den Funktionsaufruf wie gewohnt und gibt das Ergebnis zurück. Wie du Ergebnisse verarbeitest, erfährst du im Leitfaden zu Funktionen.

Setze OPENAI_API_KEY, bevor du dieses Beispiel ausführst:

Funktionen nur bei Bedarf als Tools laden
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);

Ladestrategie für Funktionen auswählen

Strategie Konfiguration Geeignet für Was du beachten solltest
Sofort laden Lass defer_loading weg oder setze es auf false. Wenige Funktionen oder Funktionen, die für die meisten Aufgaben benötigt werden. Ungenutzte Definitionen belegen Platz im Kontextfenster. Eine Änderung an einer Definition kann ein Präfix im Cache ungültig machen.
Bei Bedarf laden Setze defer_loading: true und füge tool_search hinzu. Einen großen Katalog, aus dem für jede Aufgabe nur wenige Funktionen benötigt werden. Die Suche erfordert einen zusätzlichen Schritt. Dabei muss das Modell das passende Tool finden.

Die Agents API unterstützt es, in derselben Sitzung einige Funktionen sofort und andere erst bei Bedarf zu laden. Wir empfehlen das in der Regel jedoch nicht. Gib Funktionen, die erst bei Bedarf geladen werden, eindeutige Namen und Beschreibungen. Vergleiche anhand repräsentativer Anfragen, wie gut das Modell die Aufgaben erledigt, wie viele Eingabetoken es benötigt und wie hoch die Latenz ist, bevor du eine Standardstrategie wählst.

MCP-Tools und Tools aus Plugins

Die Agents API findet MCP-Tools automatisch, wenn das Modell und der Anbieter die Tool-Suche unterstützen. Die Laufzeitumgebung lädt MCP-Tools erst bei Bedarf und fügt die Tool-Suche hinzu, sobald solche Tools für die Suche verfügbar sind. Das gilt für Remote-MCP-Server, Executor-MCP-Server und MCP-Tools aus Plugins.

Du musst nicht eigens für MCP-Tools { "type": "tool_search" } hinzufügen oder auf einem MCP-Server das Flag defer_loading für einzelne Funktionen setzen. Konfiguriere den Server mithilfe von MCP-Verbindungen. Die weiter oben beschriebene Konfiguration der Responses API gilt nicht für MCP-Server in der Agents API.

Weiterführende Leitfäden

  • Mit dem Funktionsaufruf kannst du aufrufbare Funktionen und eigene Tools definieren.
  • Der Leitfaden Tools verwenden gibt dir einen Überblick über die Tools der Responses API.