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

Programmatische Toolaufrufe

Lass Modelle JavaScript schreiben und ausführen, um Toolaufrufe zu koordinieren.

Mit programmatischen Toolaufrufen kann ein Modell JavaScript schreiben und ausführen, um seine Tools zu koordinieren. Ein Programm kann Tools parallel aufrufen, Schleifen und Bedingungen verwenden und Zwischenergebnisse in der gehosteten Laufzeitumgebung behalten. Das ist hilfreich, wenn eine Aufgabe eine Abfolge zusammenhängender Toolaufrufe erfordert oder wenn umfangreiche Toolausgaben verarbeitet werden müssen, bevor ein Ergebnis zurückgegeben wird.

Bei der Responses API legt deine Anwendung fest, ob programmatische Toolaufrufe verfügbar sind und welche der dafür geeigneten Tools das Modell direkt, aus einem Programm heraus oder auf beiden Wegen aufrufen kann. Für die Ausführung clientseitiger Toolaufrufe ist weiterhin deine Anwendung zuständig. Die Agents API aktiviert programmatische Toolaufrufe standardmäßig und steuert die Agentenschleife für dich.

Prüfe die Angaben auf der Modellseite, bevor du programmatische Toolaufrufe aktivierst.

So funktioniert die Laufzeitumgebung

OpenAI führt jedes generierte Programm in einer neuen, isolierten V8-Laufzeitumgebung aus. Sie unterstützt JavaScript mit await auf oberster Ebene. Node.js, Paketinstallation, direkter Netzwerkzugriff, ein allgemein nutzbares Dateisystem, die Ausführung von Unterprozessen und eine Konsole stehen nicht zur Verfügung. Der JavaScript-Zustand bleibt zwischen Programmausführungen nicht erhalten. Programme können nur über die in der Anfrage aktivierten Tools mit externen Systemen interagieren. Für Ausgaben können sie text(...) oder image(...) verwenden.

Bei Anfragen an die Responses API unterstützen programmatische Toolaufrufe Workflows, für die keine Datenaufbewahrung (ZDR) vorgesehen ist. Dafür ist kein persistenter Container zur Codeausführung erforderlich. ZDR muss für die Organisation oder das Projekt aktiviert sein. Mit store: false kannst du Anfragen zustandslos fortsetzen. Diese Einstellung allein aktiviert ZDR nicht. Ob eine Anfrage für ZDR infrage kommt und welche Aufbewahrungsregeln gelten, hängt von der gesamten Anfrage ab, einschließlich des Modells, der Tools und der Dienste von Drittanbietern. Details findest du in der Dokumentation zur Datenkontrolle.

Wann sich programmatische Toolaufrufe eignen

Verwende programmatische Toolaufrufe, wenn der Ablauf eines Arbeitsschritts vorhersehbar ist und der Code ein kleineres, strukturiertes Ergebnis zurückgeben kann. Verwende direkte Toolaufrufe, wenn ein Aufruf genügt, das Modell jedes Ergebnis neu beurteilen muss, eine Genehmigung erforderlich ist oder Quellenverweise bzw. native Artefakte erhalten bleiben müssen.

Art der Aufgabe Empfohlener Modus
Eine einzelne Abfrage oder Aktion Verwende einen direkten Toolaufruf.
Mehrere Ergebnisse, die sich per Code filtern, verknüpfen, nach Rang ordnen, von Duplikaten bereinigen, aggregieren oder validieren lassen Verwende programmatische Toolaufrufe, wenn das Programm ein kleineres, strukturiertes Ergebnis zurückgeben kann.
Voneinander abhängige Aufrufe mit vorhersehbarem Datenfluss Verwende programmatische Toolaufrufe, wenn der Code die Argumente für spätere Aufrufe ableiten kann und die Grenzen sowie das Verhalten im Fehlerfall ausdrücklich festgelegt sind.
Adaptive Suche oder semantische Bewertung Verwende direkte Toolaufrufe, wenn jedes Ergebnis die nächste Entscheidung des Modells beeinflussen soll.
Schreibvorgänge oder Aktionen, bei denen eine Genehmigung eine Rolle spielt Verwende standardmäßig direkte Toolaufrufe, damit klar bleibt, welche Aktionen autorisiert sind.
Abschließende Prüfung von Quellenverweisen oder nativen Artefakten Verwende direkte Toolaufrufe, es sei denn, das Programm behält die native Ausgabe bei und prüft jedes erforderliche Element.

Programmatische Toolaufrufe konfigurieren

Füge bei der Responses API das gehostete Tool programmatic_tool_calling zur Anfrage hinzu. Lege dann allowed_callers für jedes geeignete Tool fest, das das Programm aufrufen darf.

Programmatische Toolaufrufe aktivieren
[
  {
    "type": "function",
    "name": "get_inventory",
    "description": "Return an object with sku (string) and available_units (number).",
    "parameters": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" }
      },
      "required": ["sku"],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" },
        "available_units": { "type": "number" }
      },
      "required": ["sku", "available_units"],
      "additionalProperties": false
    },
    "allowed_callers": ["programmatic"]
  },
  {
    "type": "programmatic_tool_calling"
  }
]

allowed_callers legt fest, wie das Modell ein Tool aufrufen kann:

Wert Verhalten
Nicht angegeben oder ["direct"] Das Modell kann das Tool direkt aufrufen.
["programmatic"] Nur Code in einem program-Element kann das Tool aufrufen.
["direct", "programmatic"] Das Modell kann das Tool direkt oder aus einem Programm heraus aufrufen.

parameters beschreibt die Funktionsargumente. Gibt eine Funktion strukturierte Daten mit vorhersehbarem Aufbau zurück, beschreibt output_schema das JSON-Objekt, das als Zeichenfolge in function_call_output.output codiert ist. Definiere beides, damit der generierte JavaScript-Code die zurückgegebenen Felder zuverlässig verwenden kann.

Unterstützte Tools

Die folgenden Tooltypen unterstützen allowed_callers: ["programmatic"]:

  • function und custom
  • mcp
  • apply_patch
  • shell in der lokalen und der gehosteten Variante
  • code_interpreter

Bei MCP-Tools kann die Richtlinie require_approval des jeweiligen Tools bewirken, dass das Programm pausiert, bis du den Aufruf genehmigst.

Lies bei von OpenAI gehosteten Tools die Hinweise zur Datenaufbewahrung und Sicherheit, bevor du das jeweilige Tool für ein Programm aktivierst.

Programmatische Aufrufe mit der Toolsuche kombinieren

Die Toolsuche läuft als Tool auf der obersten Ebene der Responses API, außerhalb des generierten JavaScript-Codes. Funktionstools, benutzerdefinierte Tools und MCP-Tools mit defer_loading: true stehen einem Programm zunächst nicht zur Verfügung. Nachdem das Modell ein passendes Tool geladen hat, kann ein später gestartetes Programm es über tools.* aufrufen, sofern allowed_callers den Wert "programmatic" enthält. Ein laufendes Programm kann die Toolsuche nicht aufrufen. Das Modell muss solche Tools daher laden, bevor es ein Programm startet, das sie benötigt.

Den Aufrufmodus festlegen, wenn beide Modi verfügbar sind

Wenn deine Anwendung dem Modell erlaubt, eine Funktion direkt oder aus einem Programm heraus aufzurufen, lege für jeden Arbeitsschritt fest, welcher Modus zum Einsatz kommen soll. Allgemeine Anweisungen wie „Nutze programmatische Toolaufrufe effizient“ lassen offen, für welche Schritte sie gedacht sind. Ein Beispiel:

<tool_orchestration>
Verwende für [bounded stage] programmatische Toolaufrufe. Nutze dabei ausschließlich [eligible tools].
Führe unabhängige Aufrufe parallel aus, wenn das sicher ist. Verwende nur dokumentierte
Ein- und Ausgabefelder der Tools.

Verarbeite und verdichte die Zwischenergebnisse. Gib das Ergebnis genau im Format
[program result shape] aus. Nimm die Belege auf, die für die abschließende Antwort erforderlich sind.

Beende den Ablauf, sobald [condition] erfüllt ist. Bei einem vorübergehenden Fehler darfst du
den betroffenen Aufruf höchstens [R] Mal wiederholen. Wiederhole keine abgeschlossenen Aufrufe
und führe keine Aktionen mit Nebeneffekten aus. Fehlt weiterhin ein erforderliches Ergebnis,
gib eine eindeutige, strukturierte Fehlermeldung zurück.

Verwende direkte Toolaufrufe für [semantic judgment, approval, or final validation].
</tool_orchestration>

So kannst du diese Vorlage verwenden:

<tool_orchestration>
Vergleiche für sku_123 den Lagerbestand mit dem Bedarf. Rufe dazu ausschließlich
get_inventory und get_demand auf. Führe beide Aufrufe programmatisch und parallel aus.
Verwende nur dokumentierte Ein- und Ausgabefelder der Tools.

Verarbeite und verdichte die Zwischenergebnisse. Gib dann genau ein JSON-Objekt mit den
Feldern sku, available_units, requested_units und shortage_units aus. Berechne
shortage_units mit max(requested_units - available_units, 0). Gib available_units und
requested_units als Belege für die Berechnung an.

Beende den Ablauf, sobald beide Toolergebnisse die erforderlichen Felder enthalten.
Bei einem vorübergehenden Fehler darfst du den betroffenen Aufruf höchstens einmal
wiederholen. Wiederhole keine abgeschlossenen Aufrufe und führe keine Aktionen mit
Nebeneffekten aus. Fehlt weiterhin ein erforderliches Ergebnis, gib eine eindeutige,
strukturierte Fehlermeldung zurück.

Hole vor jeder Aktion, die den Lagerbestand verändert, per direktem Toolaufruf eine
Genehmigung ein. Verwende direkte Toolaufrufe ausschließlich für diese Genehmigung.
</tool_orchestration>

Wenn ein Workflow beide Modi benötigt, lege genau einen Übergabepunkt fest. Vermeide weitere Wechsel zwischen den Modi und führe Arbeitsschritte nicht doppelt aus. Gibt es eine sichere Ausweichlösung, definiere sie einmal und begrenze die Anzahl ihrer Wiederholungsversuche.

Programmelemente in der API-Antwort

Jeder API-Aufruf gibt weiterhin das standardmäßige Antwortobjekt der Responses API zurück. Programmatische Toolaufrufe verwenden kein separates Antwortformat. Nutzt das Modell programmatische Toolaufrufe, kann das output-Array der Antwort folgende Elemente enthalten:

  • Ein program-Element mit dem generierten JavaScript-Code, einer call_id und einem opaken fingerprint, mit dem sich das Programm fortsetzen oder erneut ausführen lässt.
  • Ein function_call-Element für einen Funktionsaufruf des Programms. Es hat eine eigene call_id, mit der deine Anwendung das Funktionsergebnis zurückgibt. Sein Feld caller.caller_id entspricht der call_id des Programms.
  • Ein program_output-Element mit dem Endergebnis und dem Status des Programms. Seine call_id entspricht der call_id des Programms. Sein status hat den Wert completed oder incomplete.

Diese Elemente stehen einzeln auf der obersten Ebene von response.output. Das Feld caller hält fest, von welchem Programm ein Aufruf stammt.

Ein Programm kann beispielsweise pausieren, während deine Anwendung get_inventory und get_demand ausführt:

Programm und verschachtelte Funktionsaufrufe
[
  {
    "type": "program",
    "id": "prog_123",
    "call_id": "call_prog_123",
    "code": "const [stock, demand] = await Promise.all([tools.get_inventory({ sku: 'sku_123' }), tools.get_demand({ sku: 'sku_123' })]); text(JSON.stringify({ sku: stock.sku, available_units: stock.available_units, requested_units: demand.requested_units, shortage_units: Math.max(demand.requested_units - stock.available_units, 0) }));",
    "fingerprint": "opaque_replay_state"
  },
  {
    "type": "function_call",
    "id": "fc_123",
    "call_id": "call_inventory_123",
    "name": "get_inventory",
    "arguments": "{\"sku\":\"sku_123\"}",
    "caller": {
      "type": "program",
      "caller_id": "call_prog_123"
    }
  },
  {
    "type": "function_call",
    "id": "fc_456",
    "call_id": "call_demand_123",
    "name": "get_demand",
    "arguments": "{\"sku\":\"sku_123\"}",
    "caller": {
      "type": "program",
      "caller_id": "call_prog_123"
    }
  }
]

Die Beispiele zeigen nur die relevanten Elemente aus response.output. Das umgebende Standardobjekt der Responses API ist der Übersicht halber ausgelassen. Nachdem deine Anwendung die Ergebnisse der verschachtelten Funktionsaufrufe zurückgegeben hat, kann eine spätere Antwort das vollständige program_output-Element enthalten:

Programmausgabe
{
  "type": "program_output",
  "id": "prog_out_123",
  "call_id": "call_prog_123",
  "result": "{\"sku\":\"sku_123\",\"available_units\":42,\"requested_units\":31,\"shortage_units\":0}",
  "status": "completed"
}

Die JSON-Zeichenfolge in program_output.result entspricht dem Format, das du in deinen Anweisungen für das Programmergebnis festgelegt hast. Für das umgebende program_output-Element gilt die oben gezeigte API-Spezifikation. Die beiden Formate sind getrennt definiert. Eine abschließende message kann zusammen mit der Programmausgabe oder in einer späteren Antwort eintreffen. Setze den Ablauf fort, bis du diese Nachricht erhältst.

OpenAI führt den vom Modell generierten JavaScript-Code in der gehosteten Laufzeitumgebung aus. Deine Anwendung führt die zurückgegebenen clientseitigen Funktionsaufrufe aus. Den generierten JavaScript-Code führt sie nicht aus.

Gib das Funktionsergebnis als function_call_output zurück. Übernimm caller unverändert aus dem Funktionsaufruf. Anhand dieses Werts setzt der Dienst das richtige Programm fort.

Programme nach clientseitigen Funktionsaufrufen fortsetzen

Ein Programm kann mehrmals pausieren, wenn es clientseitige Tools aufruft. Setze den Ablauf fort, bis die Antwort eine abschließende Nachricht des Assistenten enthält:

  1. Sende die Anfrage mit dem gehosteten Tool und den Funktionen, die programmatische Aufrufe zulassen.
  2. Führe alle zurückgegebenen clientseitigen Funktionsaufrufe aus.
  3. Gib jedes Funktionsergebnis mit der ursprünglichen call_id und dem ursprünglichen caller zurück.
  4. Behandle eine unvollständige Antwort, bevor du fortfährst.
  5. Enthält die Antwort weder ausstehende function_call-Elemente noch ein abschließendes message-Element, setze den Ablauf auf Grundlage dieser Antwort fort. Bei store: false sendest du ihre Ausgabeelemente erneut. Bei einer gespeicherten Antwort verwendest du previous_response_id.
  6. Beende die Schleife, sobald die Antwort ein abschließendes message-Element enthält. Lies response.output_text oder, falls das Modell die Antwort verweigert hat, den entsprechenden Inhalt der Nachricht.

Das folgende Beispiel verwendet store: false, behält jedes Antwortelement bei und gibt jedes Funktionsergebnis an das Programm zurück:

Programmatische Toolaufrufe in einer Schleife ausführen
import json

from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"


def get_inventory(sku):
    return {"sku": sku, "available_units": 42}


def get_demand(sku):
    return {"sku": sku, "requested_units": 31}


implementations = {
    "get_inventory": get_inventory,
    "get_demand": get_demand,
}

tools = [
    {
        "type": "function",
        "name": "get_inventory",
        "description": "Return an object with sku (string) and available_units (number).",
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "available_units": {"type": "number"},
            },
            "required": ["sku", "available_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {
        "type": "function",
        "name": "get_demand",
        "description": "Return an object with sku (string) and requested_units (number).",
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "requested_units": {"type": "number"},
            },
            "required": ["sku", "requested_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {"type": "programmatic_tool_calling"},
]

input_items = [
    {
        "role": "user",
        "content": "Compare inventory with demand for sku_123.",
    }
]

while True:
    response = client.responses.create(
        model=model,
        store=False,
        input=input_items,
        tools=tools,
    )

    if response.status != "completed":
        raise RuntimeError(f"Response ended with status {response.status}")

    # Preserve every output item, including program and reasoning items.
    input_items.extend(item.model_dump(exclude_none=True) for item in response.output)

    calls = [item for item in response.output if item.type == "function_call"]
    if not calls:
        message = next(
            (item for item in response.output if item.type == "message"), None
        )
        if message:
            refusal = next(
                (part.refusal for part in message.content if part.type == "refusal"),
                "",
            )
            print(response.output_text or refusal)
            break
        continue

    for call in calls:
        run = implementations.get(call.name)
        if run is None:
            raise ValueError(f"Unknown tool: {call.name}")

        result = run(**json.loads(call.arguments))
        input_items.append(
            {
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
                # Preserve caller so the runtime can resume the correct program.
                "caller": call.caller.model_dump() if call.caller else None,
            }
        )

Wenn du Antworten speicherst, kannst du den Ablauf mit previous_response_id fortsetzen, ohne alle bisherigen Antwortelemente erneut zu senden. Sende die neuen function_call_output-Elemente als nächste Eingabe. Bei store: false sendest du die vollständige Abfolge erneut in der ursprünglichen Reihenfolge, einschließlich aller program-Elemente, Reasoning-Elemente, Funktionsaufrufe, Ausgaben von Funktionsaufrufen und program_output-Elemente.

Sende bei zustandslosen Anfragen an Reasoning-Modelle jedes zurückgegebene Reasoning-Element erneut. Jedes dieser Elemente enthält standardmäßig encrypted_content. Den allgemeinen Ablauf für zustandslose Anfragen beschreibt der Leitfaden zum Gesprächszustand.

Tools für Programme entwickeln

  • Gib kompakte, strukturierte Daten zurück, die JavaScript auswerten kann, ohne Fließtext parsen zu müssen.
  • Definiere mit output_schema für jedes Tool die erwarteten Rückgabefelder und ihre Typen. Dokumentiere auch das Verhalten im Fehlerfall. Ist die Struktur der Rückgabe nicht im Voraus bekannt, lass nur direkte Aufrufe zu, damit das Modell das Ergebnis prüfen kann.
  • Lege das genaue Format des Programmergebnisses und die erforderlichen Belege fest. Kann das Programm kein gültiges Ergebnis liefern, gib eine eindeutige, strukturierte Fehlermeldung zurück.
  • Gestalte Funktionsaufrufe nach Möglichkeit idempotent. Ein erneuter Versuch oder eine erneute Ausführung sollte keinen unsicheren Nebeneffekt wiederholen.
  • Prüfe in deiner Anwendung bei jedem Aufruf die Argumente und Berechtigungen, auch wenn der Aufruf von einem gehosteten Programm stammt.
  • Gib den Tools aussagekräftige Namen und präzise Beschreibungen, damit das Modell sie richtig kombinieren kann.
  • Verlange vor folgenreichen Aktionen eine Genehmigung auf Anwendungsebene, unabhängig davon, woher der Aufruf stammt.

Programmatische Toolaufrufe bewerten

Mit programmatischen Toolaufrufen lässt sich die Menge an Daten aus Zwischenergebnissen verringern, die in den Modellkontext gelangen. Wie groß der Effekt ist, hängt von der Aufgabe und den Antworten der Tools ab. Verwende zunächst direkte Toolaufrufe als Vergleichsmaßstab und vergleiche dann beide Ansätze anhand repräsentativer Aufgaben.

Lege vor der Effizienzmessung fest, welche Qualität die abschließende Antwort erreichen muss und welche Belege sie enthalten soll. Bewerte den Tokenverbrauch und die Zahl der Toolaufrufe zusammen mit der Korrektheit, der Vollständigkeit und dem Umfang, in dem die Belege die Antwort stützen. Halte ausdrücklich fest, welche Qualitätseinbußen du in Kauf nimmst.

Erfasse folgende Kriterien:

  • Korrektheit und Vollständigkeit der abschließenden Antwort sowie den Umfang, in dem die Belege ihre Aussagen stützen.
  • Anzahl der Eingabetoken und Gesamtzahl der Token, Ende-zu-Ende-Latenz und Kosten.
  • Anzahl der Modellschritte, Toolaufrufe und Wiederholungsversuche sowie das Verhalten bei der Wiederherstellung nach Fehlern.
  • Sicherheit im tatsächlichen Ablauf, insbesondere beim Umgang mit Nebeneffekten und beim Einholen erforderlicher Genehmigungen.
  • Übereinstimmung zwischen dem tatsächlich verwendeten Aufrufmodus und dem für den jeweiligen Arbeitsschritt vorgesehenen Modus.

Agents API

In der Agents API laufen programmatische Toolaufrufe im von OpenAI verwalteten Agenten-Harness und sind standardmäßig aktiviert. Der Harness stellt dem Agenten ein exec-Tool zur Verfügung und macht seine vorhandenen Tools im generierten JavaScript-Code zugänglich. Du musst diese Tools weder als Kommandozeilenprogramme verpacken noch in der Sandbox installieren.

Um programmatische Toolaufrufe zu deaktivieren, füge diesen Eintrag in agent.tools ein:

{
  "type": "programmatic_tool_calling",
  "enabled": false
}

Lässt du den Eintrag oder sein Feld enabled weg, bleiben programmatische Toolaufrufe aktiviert. Auch bei einem Eintrag, der nur den Typ angibt, also { "type": "programmatic_tool_calling" }, bleiben sie aktiviert. Die oben beschriebene Konfiguration von allowed_callers und die Schleife zum Fortsetzen von Anfragen gelten für die Integration mit der Responses API.

Programmatische Toolaufrufe funktionieren auch in reinen Gesprächssitzungen, bei denen environment.type auf none gesetzt ist. Bash, Executor-MCPs und andere Tools, die in einer Sandbox laufen, benötigen weiterhin eine Ausführungsumgebung.

Wenn JavaScript einen Toolaufruf steuert, ändert sich der Ausführungsort des Tools nicht. Bei einem Shell-Aufruf laufen die Befehle in der Sandbox. Die JavaScript-Laufzeitumgebung startet selbst keine Systemprozesse. Executor-MCPs verwenden weiterhin die Sandbox, und Funktionstools rufen weiterhin deinen Anwendungsserver auf. Der Agent verarbeitet die Ergebnisse dieser Tools, bevor er entscheidet, welche davon in den Modellkontext gelangen.

Lege anhand der obigen Hinweise zur Wahl des Aufrufmodus fest, in welchen Arbeitsschritten Code zum Einsatz kommen soll. Wie du die Agents API konfigurierst und Aufrufe verarbeitest, erfährst du in den Leitfäden zu Funktionen und MCP-Verbindungen.

Weiterführende Leitfäden

  • Nutze Funktionsaufrufe, um clientseitige Funktionen zu definieren.
  • Nutze die Toolsuche, um umfangreiche Tooldefinitionen erst zu laden, wenn ein Modell sie benötigt.
  • Nutze den Gesprächszustand, um Anfragen an die Responses API mit gespeicherten Antworten oder zustandslos fortzusetzen.
  • Lies die Hinweise zur Datenkontrolle, bevor du einen Speichermodus auswählst.