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

Funktionsaufrufe

Gib Modellen Zugriff auf zusätzliche Funktionen und Daten, mit denen sie Anweisungen befolgen und auf Prompts antworten können.

Funktionsaufrufe (auch Tool-Aufrufe genannt) bieten OpenAI-Modellen eine flexible Möglichkeit, mit externen Systemen zu interagieren und auf Daten zuzugreifen, die über ihre Trainingsdaten hinausgehen. In diesem Leitfaden erfährst du, wie du einem Modell Daten und Aktionen deiner Anwendung zur Verfügung stellst. Die Beispiele zeigen, wie du Funktionstools mit einem JSON-Schema definierst und wie du benutzerdefinierte Tools mit frei formulierten Texteingaben und -ausgaben verwendest.

Wie du für Sitzungen mit der Agents API Funktionen registrierst und Aktionsanfragen der Sitzung verarbeitest, erfährst du im Abschnitt Funktionen. Die Beispiele in diesem Leitfaden zeigen die Integration mit der Responses API und mit Chat Completions.

Wenn deine Anwendung viele Funktionen oder große Schemas hat, kannst du Funktionsaufrufe mit der Tool-Suche kombinieren. So kannst du selten genutzte Tools erst dann laden, wenn das Modell sie braucht. Nur gpt-5.4 und neuere Modelle unterstützen tool_search.

GPT-6 Astra und GPT-6.1 Sol benötigen für Tool-Aufrufe die Responses API. Die Beispiele für Chat Completions verwenden GPT-5.6 Terra mit deaktiviertem Reasoning. Wie du eine bestehende Integration aktualisierst, erfährst du im Migrationsleitfaden.

So funktionieren Tool-Aufrufe

Zunächst klären wir die wichtigsten Begriffe rund um Tool-Aufrufe. Anschließend zeigen praktische Beispiele, wie du Tool-Aufrufe umsetzt.

Ablauf eines Tool-Aufrufs

Bei Tool-Aufrufen tauschen deine Anwendung und das Modell über die OpenAI API in mehreren Schritten Nachrichten aus. Der Ablauf umfasst fünf Schritte:

  1. Sende eine Anfrage mit den verfügbaren Tools an das Modell.
  2. Empfange einen Tool-Aufruf vom Modell.
  3. Führe in deiner Anwendung Code mit den Eingaben aus dem Tool-Aufruf aus.
  4. Sende eine zweite Anfrage mit dem Ergebnis des Tools an das Modell.
  5. Empfange die abschließende Antwort des Modells (oder weitere Tool-Aufrufe).

Diagramm zum Ablauf eines Funktionsaufrufs

Mit der Responses API kann deine Anwendung diesen Ablauf wiederholen, bis alle für die Aufgabe nötigen Tool-Aufrufe abgeschlossen sind. Wenn du ein Framework suchst, das die wiederkehrende Koordination dieser Schritte übernimmt, lies den Vergleich der Responses API mit dem Agents SDK.

Beispiel für ein Funktionstool

Das folgende Beispiel zeigt den vollständigen Ablauf eines Tool-Aufrufs für die Funktion get_horoscope, die das Tageshoroskop für ein Sternzeichen abruft.

Vollständiges Beispiel für einen Tool-Aufruf
from openai import OpenAI
import json

client = OpenAI()

# 1. Define a list of callable tools for the model
tools = [
    {
        "type": "function",
        "name": "get_horoscope",
        "strict": True,
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius",
                },
            },
            "required": ["sign"],
            "additionalProperties": False,
        },
    },
]


def get_horoscope(sign):
    return f"{sign}: Next Tuesday you will befriend a baby otter."


# Create a running input list we will add to over time
input_list = [{"role": "user", "content": "What is my horoscope? I am an Aquarius."}]

# 2. Prompt the model with tools defined
response = client.responses.create(
    model="gpt-6-astra",
    tools=tools,
    input=input_list,
)

# Save function call outputs for subsequent requests
input_list += response.output

for item in response.output:
    if item.type == "function_call":
        if item.name == "get_horoscope":
            # 3. Execute the function logic for get_horoscope
            sign = json.loads(item.arguments)["sign"]
            horoscope = get_horoscope(sign)

            # 4. Provide function call results to the model
            input_list.append(
                {
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": horoscope,
                }
            )

response = client.responses.create(
    model="gpt-6-astra",
    instructions="Respond only with a horoscope generated by a tool.",
    tools=tools,
    input=input_list,
)

# 5. The model should be able to give a response!
print(response.output_text)

Bei Reasoning-Modellen wie GPT-5 oder o4-mini musst du alle Reasoning-Elemente, die das Modell zusammen mit Tool-Aufrufen zurückgibt, gemeinsam mit den Ergebnissen der Aufrufe an das Modell zurücksenden. Wie du den Gesprächsverlauf beibehältst, aus dem diese Elemente hervorgegangen sind, erfährst du in den Empfehlungen für Änderungen am Präfix.

Funktionen definieren

Funktionen deklarierst du normalerweise im Parameter tools jeder API-Anfrage. Mit der Tool-Suche kann deine Anwendung Funktionen auch erst im weiteren Verlauf laden. In beiden Fällen hat das Schema jeder aufrufbaren Funktion dieselbe Struktur. Eine Funktionsdefinition enthält folgende Eigenschaften:

Feld Beschreibung
type Sollte immer den Wert function haben
name Name der Funktion (zum Beispiel get_weather)
description Angaben dazu, wann und wie die Funktion verwendet werden soll
parameters JSON-Schema, das die Eingabeargumente der Funktion definiert
strict Legt fest, ob der strikte Modus für den Funktionsaufruf erzwungen wird

So könnte die Definition der Funktion get_weather aussehen:

{
  "type": "function",
  "name": "get_weather",
  "description": "Retrieves current weather for the given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and country e.g. Bogotá, Colombia"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Units the temperature will be returned in."
      }
    },
    "required": ["location", "units"],
    "additionalProperties": false
  },
  "strict": true
}

Da du parameters mit einem JSON-Schema definierst, kannst du dessen Möglichkeiten nutzen, etwa Typen für Eigenschaften, Aufzählungen, Beschreibungen sowie verschachtelte und rekursive Objekte.

Namensräume definieren

Mit Namensräumen gruppierst du zusammengehörige Tools nach Bereichen wie crm, billing oder shipping. Das ist besonders hilfreich, wenn das Modell zwischen ähnlichen Tools für unterschiedliche Systeme oder Zwecke wählen muss, etwa zwischen einem Suchtool für dein CRM und einem für dein Support-Ticketsystem.

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

Tool-Suche

Wenn du dem Modell viele Tools bereitstellen möchtest, kannst du mit tool_search einige oder alle Tools erst bei Bedarf laden. Mit tool_search kann das Modell nach passenden Tools suchen, sie in seinen Kontext aufnehmen und anschließend verwenden. Nur gpt-5.4 und neuere Modelle unterstützen diese Funktion. Mehr dazu erfährst du im Leitfaden zur Tool-Suche.

Empfehlungen für Funktionsdefinitionen

  1. Wähle aussagekräftige Funktionsnamen, beschreibe die Parameter genau und formuliere klare, detaillierte Anweisungen.

    • Beschreibe ausdrücklich den Zweck der Funktion und jedes Parameters, das jeweilige Parameterformat und die Bedeutung der Ausgabe.
    • Gib im System-Prompt an, wann das Modell die einzelnen Funktionen verwenden soll und wann nicht. Sage dem Modell möglichst genau, was es tun soll.
    • Nenne Beispiele und Grenzfälle, besonders wenn dieselben Fehler wiederholt auftreten. (Hinweis: Beispiele können die Leistung von Reasoning-Modellen beeinträchtigen.)
    • Gib bei nachladbaren Tools detaillierte Anweisungen in der Funktionsbeschreibung und halte die Beschreibung des Namensraums kurz. Anhand des Namensraums entscheidet das Modell, welche Tools es lädt. Die Funktionsbeschreibung hilft ihm, das geladene Tool richtig zu verwenden.
  2. Orientiere dich an bewährten Methoden der Softwareentwicklung.

    • Gestalte Funktionen so, dass ihr Verhalten vorhersehbar und intuitiv ist. (Prinzip der geringsten Überraschung)
    • Verwende Aufzählungstypen und die Struktur deiner Objekte, um ungültige Zustände auszuschließen. Beispielsweise lässt toggle_light(on: bool, off: bool) ungültige Aufrufe zu.
    • Teste die Beschreibung mit jemandem im Praktikum. Kann die Person die Funktion allein mit den Angaben richtig verwenden, die auch das Modell erhält? (Falls nicht, welche Fragen stellt sie? Ergänze die Antworten im Prompt.)
  3. Entlaste das Modell und nutze nach Möglichkeit Code.

    • Lass das Modell keine Argumente ausfüllen, deren Werte du bereits kennst. Wenn dir beispielsweise aus einer vorherigen Menüauswahl die order_id vorliegt, lass den Parameter order_id weg. Definiere stattdessen submit_refund() ohne Parameter und übergib die order_id in deinem Code.
    • Fasse Funktionen zusammen, die du immer nacheinander aufrufst. Wenn du beispielsweise mark_location() immer nach query_location() aufrufst, integriere die Logik zum Markieren direkt in die Abfragefunktion.
  4. Stelle anfangs nur wenige Funktionen bereit, damit das Modell sie zuverlässiger aufruft.

    • Prüfe die Leistung mit unterschiedlich vielen Funktionen.
    • Stelle zu Beginn jedes Gesprächsschritts möglichst weniger als 20 Funktionen bereit. Diese Zahl dient als Richtwert.
    • Nutze die Tool-Suche, um umfangreiche oder selten genutzte Teile deines Tool-Angebots erst bei Bedarf zu laden.
  5. Nutze die Ressourcen von OpenAI.

    • Erstelle und überarbeite Funktionsschemas im Playground.
    • Ziehe Fine-Tuning in Betracht, um die Genauigkeit von Funktionsaufrufen zu verbessern, wenn du viele Funktionen anbietest oder die Aufgaben schwierig sind. (Beispiel im Cookbook)

Token-Verbrauch

Die API fügt Funktionsdefinitionen in einer Syntax in die Systemnachricht ein, auf die das Modell trainiert wurde. Die Definitionen aufrufbarer Funktionen belegen daher Platz im Kontextfenster des Modells und werden als Eingabetoken abgerechnet. Wenn du an Tokengrenzen stößt, lade anfangs weniger Funktionen, kürze nach Möglichkeit die Beschreibungen oder nutze die Tool-Suche, um Tools erst bei Bedarf zu laden.

Wenn deine Tool-Spezifikation viele Funktionen definiert, kannst du den Token-Verbrauch auch mit Fine-Tuning senken.

Funktionsaufrufe verarbeiten

Wenn das Modell eine Funktion aufruft, musst du sie ausführen und das Ergebnis zurückgeben. Eine Modellantwort kann keinen, einen oder mehrere Aufrufe enthalten. Lege deinen Code daher für mehrere Aufrufe aus.

Das Array output der Antwort enthält einen Eintrag, dessen Feld type den Wert function_call hat. Jeder solche Eintrag enthält eine call_id, über die du später das Funktionsergebnis übermittelst, sowie name und JSON-kodierte arguments.

Beispielantwort mit mehreren Funktionsaufrufen
[
    {
        "id": "fc_12345xyz",
        "call_id": "call_12345xyz",
        "type": "function_call",
        "name": "get_weather",
        "arguments": "{\"location\":\"Paris, France\"}"
    },
    {
        "id": "fc_67890abc",
        "call_id": "call_67890abc",
        "type": "function_call",
        "name": "get_weather",
        "arguments": "{\"location\":\"Bogotá, Colombia\"}"
    },
    {
        "id": "fc_99999def",
        "call_id": "call_99999def",
        "type": "function_call",
        "name": "send_email",
        "arguments": "{\"to\":\"bob@email.com\",\"body\":\"Hi bob\"}"
    }
]

Wenn du die Tool-Suche verwendest, können auch Elemente der Typen tool_search_call und tool_search_output vor einem function_call erscheinen. Sobald die Funktion geladen ist, verarbeitest du den Funktionsaufruf wie hier gezeigt.

Funktionsaufrufe ausführen und Ergebnisse anhängen
input_messages += response.output

for tool_call in response.output:
    if tool_call.type != "function_call":
        continue

    name = tool_call.name
    args = json.loads(tool_call.arguments)

    result = call_function(name, args)
    input_messages.append(
        {
            "type": "function_call_output",
            "call_id": tool_call.call_id,
            "output": json.dumps(result),
        }
    )

Im obigen Beispiel leitet eine Beispielfunktion namens call_function jeden Aufruf an die passende Funktion weiter. So könntest du sie implementieren:

Funktionsaufrufe ausführen und Ergebnisse anhängen
def call_function(name, args):
    if name == "get_weather":
        return get_weather(**args)
    if name == "send_email":
        return send_email(**args)
    raise ValueError(f"Unknown function: {name}")

Ergebnisse formatieren

Das Ergebnis, das du in der Nachricht function_call_output übergibst, sollte in der Regel eine Zeichenkette sein. Das Format bestimmst du selbst, etwa JSON, Fehlercodes oder einfacher Text. Das Modell interpretiert die Zeichenkette entsprechend.

Bei Funktionen, die Bilder oder Dateien zurückgeben, kannst du anstelle einer Zeichenkette ein Array von Bild- oder Dateiobjekten übergeben.

Hat deine Funktion keinen Rückgabewert (zum Beispiel send_email), gib eine Zeichenkette zurück, die Erfolg oder Fehlschlag anzeigt, etwa "success".

Ergebnisse in die Antwort einbeziehen

Hänge die Ergebnisse an input an und sende die ergänzte Eingabe an das Modell zurück, um die abschließende Antwort zu erhalten.

Ergebnisse an das Modell zurücksenden
response = client.responses.create(
    model="gpt-6-astra",
    input=input_messages,
    tools=responses_tools,
)
Abschließende Antwort
"It's about 15°C in Paris, 18°C in Bogotá, and I've sent that email to Bob."

Weitere Konfigurationsmöglichkeiten

Tool-Auswahl

Standardmäßig entscheidet das Modell, wann und wie viele Tools es verwendet. Mit dem Parameter tool_choice kannst du ein bestimmtes Verhalten vorgeben.

  1. Automatisch: (Standard) Das Modell ruft keine, eine oder mehrere Funktionen auf. tool_choice: "auto"
  2. Erforderlich: Das Modell ruft mindestens eine Funktion auf. tool_choice: "required"
  3. Vorgegebene Funktion: Das Modell ruft genau eine bestimmte Funktion auf. tool_choice: {"type": "function", "name": "get_weather"}
  4. Zulässige Tools: Das Modell darf nur eine Teilmenge der verfügbaren Tools aufrufen.

Wann sich allowed_tools eignet

Mit einer allowed_tools-Liste kannst du pro Modellanfrage nur bestimmte Tools zulassen und trotzdem jedes Mal dieselbe vollständige Tool-Liste übergeben. So kannst du die Einsparungen durch Prompt-Caching maximieren.

"tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
        { "type": "function", "name": "get_weather" },
        { "type": "function", "name": "search_docs" }
    ]
  }
}

Du kannst tool_choice auch auf "none" setzen. Das Modell verhält sich dann so, als hättest du keine Funktionen übergeben.

Auch bei der Tool-Suche gilt tool_choice für die Tools, die im aktuellen Gesprächsschritt aufrufbar sind. Das ist besonders hilfreich, wenn du nur bestimmte Tools geladen hast und das Modell auf diese Auswahl beschränken möchtest.

Parallele Funktionsaufrufe

Modelle ab GPT-5, die parallele Funktionsaufrufe unterstützen, können Funktionen auch dann parallel aufrufen, wenn integrierte Tools verfügbar sind. Eine Gruppe parallel aufgerufener Funktionen darf keine integrierten Tools enthalten.

Das Modell kann mehrere Funktionen in einem Gesprächsschritt aufrufen. Wenn du parallel_tool_calls auf false setzt, ruft das Modell höchstens ein Tool auf.

Hinweis: Wenn ein per Fine-Tuning angepasstes Modell mehrere Funktionen in einem Gesprächsschritt aufruft, wird der strikte Modus für diese Aufrufe derzeit deaktiviert.

Hinweis zu gpt-4.1-nano-2025-04-14: Dieser Snapshot von gpt-4.1-nano kann bei aktivierten parallelen Tool-Aufrufen gelegentlich dasselbe Tool mehrfach aufrufen. Wir empfehlen, parallele Tool-Aufrufe für diesen Snapshot zu deaktivieren.

Strikter Modus

Wenn du strict auf true setzt, halten Funktionsaufrufe das Funktionsschema zuverlässig ein. Ohne strikte Prüfung versucht das Modell, das Schema so gut wie möglich einzuhalten. Wir empfehlen, den strikten Modus immer zu aktivieren.

Der strikte Modus nutzt strukturierte Ausgaben. Daraus ergeben sich zwei Anforderungen:

  1. Setze additionalProperties auf false, und zwar für jedes Objekt in parameters.
  2. Alle Felder in properties müssen als required gekennzeichnet sein.

Für optionale Felder kannst du null als zusätzlichen Typ unter type zulassen (siehe Beispiel unten).

Wenn du strict: true sendest und dein Schema diese Anforderungen nicht erfüllt, lehnt die API die Anfrage ab und gibt an, welche Vorgaben fehlen. Lässt du strict weg, hängt das Standardverhalten von der API ab. Bei Responses-Anfragen versucht die API, dein Schema für den strikten Modus zu normalisieren. Ist das nicht möglich, erfolgen Funktionsaufrufe ohne strikte Prüfung, und das Modell versucht, das Schema bestmöglich einzuhalten. In diesem Fall steht in der Tool-Definition der Antwort strict: false. Bei Chat Completions ist der strikte Modus standardmäßig deaktiviert. Wenn du auch bei Responses ausdrücklich Funktionsaufrufe ohne strikte Prüfung verwenden möchtest, setze strict: false.

{
    "type": "function",
    "name": "get_weather",
    "description": "Retrieves current weather for the given location.",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country e.g. Bogotá, Colombia"
            },
            "units": {
                "type": ["string", "null"],
                "enum": ["celsius", "fahrenheit"],
                "description": "Units the temperature will be returned in."
            }
        },
        "required": ["location", "units"],
        "additionalProperties": false
    }
}

Bei allen Schemas, die du im Playground generierst, ist der strikte Modus aktiviert.

Wir empfehlen den strikten Modus. Beachte dabei folgende Einschränkungen:

  1. Einige Funktionen von JSON-Schema werden nicht unterstützt. (Siehe unterstützte Schemas.)

Für per Fine-Tuning angepasste Modelle gilt außerdem:

  1. Bei der ersten Anfrage durchlaufen Schemas einen zusätzlichen Verarbeitungsschritt. Danach werden sie zwischengespeichert. Wenn sich deine Schemas von Anfrage zu Anfrage ändern, kann die Latenz steigen.
  2. Da die Schemas aus Leistungsgründen zwischengespeichert werden, kommt die Option keine Datenaufbewahrung für sie nicht infrage.

Streaming

Mit Streaming kannst du den Fortschritt anzeigen. Während das Modell die Argumente erzeugt, siehst du bereits, welche Funktion es aufruft, und kannst sogar die Argumente in Echtzeit anzeigen.

Das Streaming von Funktionsaufrufen funktioniert ähnlich wie bei gewöhnlichen Antworten. Du setzt stream auf true und erhältst unterschiedliche event-Objekte.

Funktionsaufrufe streamen
from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "strict": True,
        "description": "Get current temperature for a given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia",
                }
            },
            "required": ["location"],
            "additionalProperties": False,
        },
    }
]

stream = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
    stream=True,
)

for event in stream:
    print(event)
Ausgegebene Ereignisse
{"type":"response.output_item.added","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":""}}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"{\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"location"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\":\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"Paris"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":","}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":" France"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\"}"}
{"type":"response.function_call_arguments.done","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"arguments":"{\"location\":\"Paris, France\"}"}
{"type":"response.output_item.done","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":"{\"location\":\"Paris, France\"}"}}

Bei einer Textantwort setzt du die Teilstücke zu einer einzigen content-Zeichenkette zusammen. Bei einem Funktionsaufruf ergeben sie das als JSON kodierte Objekt für arguments.

Ruft das Modell eine oder mehrere Funktionen auf, erhältst du für jeden Funktionsaufruf ein Ereignis vom Typ response.output_item.added mit folgenden Feldern:

Feld Beschreibung
response_id ID der Antwort, zu der der Funktionsaufruf gehört
output_index Index des Ausgabeelements in der Antwort. Er unterscheidet die einzelnen Funktionsaufrufe innerhalb der Antwort.
item Element für den laufenden Funktionsaufruf mit den Feldern name, arguments und id

Danach erhältst du eine Reihe von Ereignissen des Typs response.function_call_arguments.delta. Sie enthalten jeweils das delta des Felds arguments. Diese Ereignisse haben folgende Felder:

Feld Beschreibung
response_id ID der Antwort, zu der der Funktionsaufruf gehört
item_id ID des Elements für den Funktionsaufruf, zu dem das Delta gehört
output_index Index des Ausgabeelements in der Antwort. Er unterscheidet die einzelnen Funktionsaufrufe innerhalb der Antwort.
delta Delta des Felds arguments

Das folgende Codebeispiel zeigt, wie du die delta-Objekte zu einem vollständigen tool_call-Objekt zusammensetzt.

Deltas für tool_call zusammenführen
final_tool_calls = {}

for event in stream:
    if (
        event.type == "response.output_item.added"
        and event.item.type == "function_call"
    ):
        final_tool_calls[event.output_index] = event.item
    elif event.type == "response.function_call_arguments.delta":
        index = event.output_index

        if final_tool_calls[index]:
            final_tool_calls[index].arguments += event.delta
Vollständig zusammengesetzter Eintrag final_tool_calls[0]
{
    "type": "function_call",
    "id": "fc_1234xyz",
    "call_id": "call_2345abc",
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
}

Sobald das Modell die Funktionsaufrufe abgeschlossen hat, erhältst du ein Ereignis des Typs response.function_call_arguments.done. Es enthält den vollständigen Funktionsaufruf mit folgenden Feldern:

Feld Beschreibung
response_id ID der Antwort, zu der der Funktionsaufruf gehört
output_index Index des Ausgabeelements in der Antwort. Er unterscheidet die einzelnen Funktionsaufrufe innerhalb der Antwort.
item Element für den Funktionsaufruf mit den Feldern name, arguments und id

Benutzerdefinierte Tools

Benutzerdefinierte Tools funktionieren ähnlich wie Funktionstools mit JSON-Schema. Du musst dem Modell jedoch nicht ausdrücklich vorgeben, welche Eingabe das Tool erwartet. Das Modell kann eine beliebige Zeichenkette als Eingabe an das Tool übergeben. So kannst du vermeiden, eine Antwort unnötig in JSON zu verpacken. Außerdem kannst du für die Antwort eine eigene Grammatik vorgeben (mehr dazu weiter unten).

Das folgende Codebeispiel erstellt ein benutzerdefiniertes Tool, das vom Modell eine Zeichenkette mit Python-Code erwartet.

Beispiel für den Aufruf eines benutzerdefinierten Tools
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Use the code_exec tool to print hello world to the console.",
    tools=[
        {
            "type": "custom",
            "name": "code_exec",
            "description": "Executes arbitrary Python code.",
        }
    ],
)
print(response.output)

Wie zuvor enthält das Array output einen vom Modell erzeugten Tool-Aufruf. Diesmal liegt die Eingabe für den Tool-Aufruf als einfacher Text vor.

[
  {
    "id": "rs_6890e972fa7c819ca8bc561526b989170694874912ae0ea6",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6890e975e86c819c9338825b3e1994810694874912ae0ea6",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_aGiFQkRWSWAIsMQ19fKqxUgb",
    "input": "print(\"hello world\")",
    "name": "code_exec"
  }
]

Kontextfreie Grammatiken

Eine kontextfreie Grammatik (CFG) legt durch Regeln fest, wie gültiger Text in einem bestimmten Format entsteht. Mit einer CFG kannst du einschränken, welche Texteingaben das Modell an ein benutzerdefiniertes Tool übergeben kann.

Beim Konfigurieren eines benutzerdefinierten Tools gibst du deine CFG über den Parameter grammar an. Derzeit unterstützen wir zwei Syntaxvarianten für solche Grammatiken: lark und regex.

Lark-Grammatik

Beispiel für eine kontextfreie Grammatik mit Lark
from openai import OpenAI

client = OpenAI()

grammar = """
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT
"""

response = client.responses.create(
    model="gpt-6-astra",
    input="Use the math_exp tool to add four plus four.",
    tools=[
        {
            "type": "custom",
            "name": "math_exp",
            "description": "Creates valid mathematical expressions",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": grammar,
            },
        }
    ],
)
print(response.output)

Die vom Modell erzeugte Eingabe für das Tool sollte dann der von dir definierten Lark-Grammatik entsprechen:

[
  {
    "id": "rs_6890ed2b6374819dbbff5353e6664ef103f4db9848be4829",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6890ed2f32e8819daa62bef772b8c15503f4db9848be4829",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_pmlLjmvG33KJdyVdC4MVdk5N",
    "input": "4 + 4",
    "name": "math_exp"
  }
]

Du definierst Grammatiken mit einer Variante von Lark. LLGuidance beschränkt die Token-Auswahl des Modells. Einige Funktionen von Lark werden nicht unterstützt:

  • Lookaround-Ausdrücke in regulären Ausdrücken des Lexers
  • Nicht gierige Quantifizierer (*?, +?, ??) in regulären Ausdrücken des Lexers
  • Prioritäten für Terminalsymbole
  • Vorlagen
  • Importe (mit Ausnahme der integrierten common-Definitionen über %import)
  • %declare-Direktiven

Zum Ausprobieren eigener Grammatiken empfehlen wir die Lark IDE.

Komplexität der Grammatik begrenzen

Beschränke deine Grammatik auf die Regeln und Muster, die dein Tool benötigt. Bei zu komplexen Grammatiken kann die OpenAI API einen Fehler zurückgeben. Prüfe deshalb vor dem Einsatz, ob deine Grammatik mit der API kompatibel ist.

Es kann mehrere Anläufe brauchen, bis eine Lark-Grammatik wie gewünscht funktioniert. Einfache Grammatiken funktionieren am zuverlässigsten. Bei komplexen Grammatiken musst du häufig die Grammatik selbst, den Prompt und die Tool-Beschreibung überarbeiten, damit das Modell innerhalb der Verteilung bleibt, die es aus dem Training kennt.

Richtige und falsche Muster

So ist es richtig (ein einziges, klar abgegrenztes Terminalsymbol):

start: SENTENCE
SENTENCE: /[A-Za-z, ]*(the hero|a dragon|an old man|the princess)[A-Za-z, ]*(fought|saved|found|lost)[A-Za-z, ]*(a treasure|the kingdom|a secret|his way)[A-Za-z, ]*\./

Vermeide die folgende Aufteilung auf mehrere Regeln und Terminalsymbole. Hier sollen Regeln den Freitext auf mehrere Terminalsymbole verteilen. Der Lexer erfasst jedoch für jedes Freitextstück möglichst viele Zeichen. Dadurch verlierst du die Kontrolle über die Aufteilung:

start: sentence
sentence: /[A-Za-z, ]+/ subject /[A-Za-z, ]+/ verb /[A-Za-z, ]+/ object /[A-Za-z, ]+/

Nur die Definitionen der Terminalsymbole bestimmen, wie der Lexer die Eingabe zerlegt. Kleingeschriebene Regeln haben darauf keinen Einfluss. Wenn du „Freitext zwischen Ankern“ brauchst, definiere das gesamte Muster als ein einziges Terminalsymbol mit einem regulären Ausdruck. So erfasst der Lexer die gewünschte Struktur in einem einzigen Treffer.

Terminalsymbole und Regeln

Lark verwendet Terminalsymbole für Lexer-Token (üblicherweise UPPERCASE) und Regeln für Parserproduktionen (üblicherweise lowercase). Damit deine Grammatik nur unterstützte Funktionen nutzt und sich vorhersehbar verhält, definiere sie möglichst einfach und eindeutig. Trenne dabei die Aufgaben von Terminalsymbolen und Regeln klar voneinander.

Für die regulären Ausdrücke der Terminalsymbole gilt die Syntax des Rust-Crates regex. Sie unterscheidet sich von der Syntax des re-Moduls für Python.

Grundlagen und Empfehlungen

Der Lexer arbeitet vor dem Parser

Bevor eine CFG-Regel greift, erkennt der Lexer die Terminalsymbole. Dabei wählt er jeweils den längsten Treffer. Wenn du ein Terminalsymbol über mehrere Regeln verteilst, um seine Form vorzugeben, können diese Regeln den Lexer nicht steuern. Dafür sind allein die regulären Ausdrücke der Terminalsymbole maßgeblich.

Erfasse Muster in Freitext möglichst mit einem einzigen Terminalsymbol

Wenn du ein Muster in beliebigem Text erkennen möchtest, etwa in natürlicher Sprache mit beliebigen Zeichen zwischen Ankern, beschreibe es als ein einziges Terminalsymbol. Vermeide es, Freitext-Terminalsymbole und Parserregeln abwechselnd anzuordnen. Da der Lexer den längsten Treffer wählt, hält er die vorgesehenen Grenzen nicht ein. Das Modell verlässt dann mit hoher Wahrscheinlichkeit die ihm vertraute Verteilung.

Setze einzelne Token mit Regeln zusammen

Regeln eignen sich dafür, klar abgegrenzte Terminalsymbole wie Zahlen, Schlüsselwörter und Satzzeichen zu größeren Strukturen zusammenzusetzen. Um den Text zwischen zwei Terminalsymbolen einzuschränken, sind sie ungeeignet.

Definiere Terminalsymbole gezielt, begrenzt und in sich geschlossen

Verwende möglichst explizite Zeichenklassen und begrenzte Quantifizierer (etwa {0,10}, statt überall das unbegrenzte * zu verwenden). Wenn du „beliebigen Text bis zu einem Punkt“ erfassen möchtest, verwende eher einen Ausdruck wie /[^.\n]{0,10}*\./ als /.+\./, damit der erfasste Text nicht unkontrolliert wächst.

Nutze Regeln zum Kombinieren von Token und überlasse die Auswertung regulärer Ausdrücke dem Lexer

So kannst du Regeln sinnvoll einsetzen:

start: expr
NUMBER: /[0-9]+/
PLUS: "+"
MINUS: "-"
expr: term (("+"|"-") term)*
term: NUMBER

Berücksichtige Leerraum ausdrücklich

Verlass dich nicht auf unbegrenzte %ignore-Direktiven. Solche Direktiven können die Grammatik zu komplex machen oder dazu führen, dass das Modell seine vertraute Verteilung verlässt. Füge stattdessen überall dort, wo Leerraum zulässig ist, ausdrücklich passende Terminalsymbole ein.

Fehlerbehebung

  • Lehnt die API die Grammatik als zu komplex ab, vereinfache die Regeln und Terminalsymbole und entferne unbegrenzte %ignore-Direktiven.
  • Wenn benutzerdefinierte Tools mit unerwarteten Token aufgerufen werden, prüfe, ob sich Terminalsymbole überschneiden und wie der Lexer den längsten Treffer bestimmt.
  • Wenn das Modell die ihm vertraute Verteilung verlässt (erkennbar an übermäßig langen oder repetitiven Ausgaben, die syntaktisch gültig, aber inhaltlich falsch sind):
    • Schränke die Grammatik stärker ein.
    • Überarbeite den Prompt und die Tool-Beschreibung. Ergänze Few-Shot-Beispiele im Prompt. Erkläre in der Tool-Beschreibung die Grammatik und weise das Modell an, sie beim Reasoning zu berücksichtigen und einzuhalten.
    • Probiere einen höheren Reasoning-Aufwand aus, etwa indem du von „Mittel“ auf „Hoch“ wechselst.

Regex-Grammatik

Beispiel für eine kontextfreie Grammatik mit regulären Ausdrücken
from openai import OpenAI

client = OpenAI()

grammar = r"^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?\s+(?P<year>\d{4})\s+at\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$"

response = client.responses.create(
    model="gpt-6-astra",
    input="Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.",
    tools=[
        {
            "type": "custom",
            "name": "timestamp",
            "description": "Saves a timestamp in date + time in 24-hr format.",
            "format": {
                "type": "grammar",
                "syntax": "regex",
                "definition": grammar,
            },
        }
    ],
)
print(response.output)

Die vom Modell erzeugte Eingabe für das Tool sollte dann der von dir definierten Regex-Grammatik entsprechen:

[
  {
    "id": "rs_6894f7a3dd4c81a1823a723a00bfa8710d7962f622d1c260",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6894f7ad7fb881a1bffa1f377393b1a40d7962f622d1c260",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_8m4XCnYvEmFlzHgDHbaOCFlK",
    "input": "August 7th 2025 at 10AM",
    "name": "timestamp"
  }
]

Wie bei der Lark-Syntax gilt für reguläre Ausdrücke die Syntax des Rust-Crates regex. Sie unterscheidet sich von der Syntax des re-Moduls für Python.

Einige Funktionen regulärer Ausdrücke werden nicht unterstützt:

  • Lookaround-Ausdrücke
  • Nicht gierige Quantifizierer (*?, +?, ??)

Grundlagen und Empfehlungen

Das Muster muss in einer einzigen Zeile stehen

Wenn du einen Zeilenumbruch in der Eingabe erkennen möchtest, verwende die Escape-Sequenz \n. Verwende nicht den erweiterten Modus (Verbose/Extended), in dem sich Muster über mehrere Zeilen erstrecken können.

Gib das Muster als einfache Zeichenkette an

Schließe das Muster nicht in // ein.