OpenAI Function Calling nutzen: Eine Anleitung

Am Ende dieses Leitfadens werden Sie in der Lage sein, ein Tool zu definieren, es an OpenAI zu senden, den vom Modell zurückgegebenen Tool-Aufruf zu lesen und Ihre eigene Funktion mit den strukturierten Argumenten auszuführen, die es zurückgibt. Sie werden auch den Strict Mode und parallele Aufrufe aktivieren und dann die Tool-Seite mit Apidog überprüfen und simulieren, damit Sie der Ausgabe vertrauen können, bevor sie in Produktion geht. Halten Sie die Dokumentation zum Funktionsaufruf von OpenAI in einem anderen Tab geöffnet, um die Quelle der Wahrheit zu haben, und sehen Sie sich unser Grundlagenpapier zum Erstellen von Agenten mit dem OpenAI Agents SDK für das Gesamtbild an.

Was Sie vor dem Start benötigen

Funktionsaufrufe (oft auch Tool-Aufrufe genannt) sind die Art und Weise, wie ein Modell mit Ihrem Code und externen Systemen verbunden wird. Sie beschreiben die Funktionen, die Ihre App bereitstellt, das Modell liest die Anfrage des Benutzers, und wenn eine Funktion passt, gibt es den Funktionsnamen plus ein JSON-Objekt mit Argumenten zurück. Das Modell führt selbst nie etwas aus. Es übergibt Ihnen eine strukturierte Anfrage, und Ihr Code erledigt die Arbeit.

Diese Trennung sollten Sie beim Entwickeln im Hinterkopf behalten. Das Modell wählt die Absicht aus und füllt die Parameter aus. Sie behalten die Kontrolle über die Ausführung. Eine Nachricht wie „get the weather in Paris“ (Wetter in Paris abrufen) wird zu einem sauberen Aufruf von get_weather({"location": "Paris, France"}) anstatt eines Absatzes, den Sie von Hand hätten parsen müssen.

Um mitzumachen, benötigen Sie einen OpenAI API-Schlüssel und eine Funktion in Ihrem eigenen Code, die das Modell auslösen soll. Noch etwas, das Sie im Voraus entscheiden sollten: welchen Endpunkt Sie verwenden. Dieselbe Funktion funktioniert an zwei Stellen. Die ältere Chat Completions API unterstützt sie, ebenso wie die neuere Responses API, die das zusammenführt, was früher auf Chat Completions und die Assistants API aufgeteilt war. Die Strukturen unterscheiden sich geringfügig, und die folgenden Schritte behandeln beide.

Schritt 1: Definieren Sie Ihr Tool

Ein Tool ist eine Funktionsdefinition, die das Modell lesen kann. Sie geben ihm einen Namen, eine Beschreibung und ein JSON-Schema für die Argumente. Die Beschreibung leistet hier echte Arbeit. Sie teilt dem Modell mit, wann es die Funktion verwenden soll, also schreiben Sie sie als Anweisung, nicht als Bezeichnung.

Hier ist eine Tool-Definition in der Struktur der Chat Completions, wobei die Funktion unter einem function-Wrapper liegt:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and country, e.g. Bogotá, Colombia"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"],
      "additionalProperties": false
    }
  }
}

Die Responses API vereinfacht dies. Die Felder name, description, parameters und strict befinden sich auf der obersten Ebene des Tool-Objekts, ohne einen verschachtelten function-Schlüssel. Dieselbe Information, weniger Ebenen.

Wenn Sie bereits eine OpenAPI-Spezifikation für den zugrunde liegenden Dienst pflegen, werden die Parameterstrukturen fast direkt übernommen. Unser Leitfaden zum Generieren von Testsammlungen aus OpenAPI-Spezifikationen zeigt, wie sich diese Schemaarbeit doppelt auszahlt.

Schritt 2: Senden Sie Ihre erste Anfrage

Senden Sie Ihr Tool zusammen mit der Nachricht des Benutzers an das Modell. Eine vollständige Chat Completions-Anfrage, die dies tut, sieht so aus:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the weather in Paris right now?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string"}
            },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

Das tools-Array enthält jede Funktion, die Sie für diese Runde verfügbar machen möchten. Das Modell liest die Benutzernachricht, entscheidet, ob ein Tool passt, und antwortet. Wenn es eines auswählt, erhalten Sie einen Tool-Aufruf zurück anstelle von Text, den Sie im nächsten Schritt lesen.

Schritt 3: Lesen Sie den vom Modell zurückgegebenen Tool-Aufruf

Wenn das Modell entscheidet, eine Funktion aufzurufen, gibt es keinen Text zurück. Es gibt einen Tool-Aufruf zurück, den Sie aus der Antwort lesen.

In Chat Completions enthält die Assistentennachricht ein tool_calls-Array. Jeder Eintrag hat eine id, einen type von function und ein function-Objekt mit dem name und einem arguments-String:

{
  "id": "call_12345xyz",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
  }
}

In der Responses API erscheint der Aufruf im output-Array mit einer flacheren Struktur: einem type von function_call, einer call_id, einem name und arguments:

{
  "type": "function_call",
  "call_id": "call_12345xyz",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}

Ein Detail, das oft Verwirrung stiftet: arguments ist ein JSON-kodierter String, kein geparstes Objekt. Sie parsen es selbst, führen Ihre Funktion aus und senden das Ergebnis dann zurück, damit das Modell seine Antwort vervollständigen kann.

Schritt 4: Geben Sie das Ergebnis an das Modell zurück

Nachdem Sie Ihre Funktion ausgeführt haben, geben Sie das Ergebnis zurück, damit das Modell eine endgültige Antwort erstellen kann. In Chat Completions fügen Sie eine tool-Rollen-Nachricht hinzu, die mit der Aufruf-id verknüpft ist. In der Responses API senden Sie ein function_call_output-Element, das mit der call_id verknüpft ist. In jedem Fall ist der Ablauf derselbe: Modell fragt, Sie führen aus, Sie geben das Ergebnis zurück, Modell antwortet.

Schritt 5: Fügen Sie parallele Aufrufe und den Strict Mode hinzu

Zwei Einstellungen ändern die Zuverlässigkeit und Geschwindigkeit, und Sie fügen sie hinzu, sobald der grundlegende Ablauf funktioniert.

Parallele Tool-Aufrufe. Standardmäßig kann das Modell in einem einzigen Durchlauf mehr als einen Tool-Aufruf zurückgeben. Wenn ein Benutzer nach dem Wetter in drei Städten fragt, erhalten Sie möglicherweise drei Aufrufe gleichzeitig und können diese zusammen ausführen. Wenn Sie lieber maximal einen Aufruf pro Durchlauf erzwingen möchten, setzen Sie parallel_tool_calls auf false.

Strict Mode. Setzen Sie strict: true in der Funktionsdefinition, und die Argumente des Modells stimmen garantiert mit Ihrem JSON-Schema überein, anstatt nur eine Best-Effort-Implementierung zu sein. OpenAI empfiehlt, ihn immer zu aktivieren. Der Strict Mode hat Regeln: Jedes Objekt benötigt additionalProperties: false, und jedes Feld in properties muss in required erscheinen. Um ein Feld optional zu machen, entfernen Sie es nicht aus required; Sie fügen null zu seiner Liste der erlaubten Typen hinzu.

Die Regel für optionale Felder überrascht viele. Angenommen, unit ist in get_weather optional. Im Strict Mode listen Sie es immer noch unter required auf und markieren es dann im Schema als nullbar, z.B. "unit": {"type": ["string", "null"], "enum": ["celsius", "fahrenheit"]}. Das Modell kann nun eine tatsächliche Einheit oder ein explizites null übergeben, aber es kann den Schlüssel niemals weglassen. Diese Vorhersehbarkeit ist der entscheidende Punkt: Ihr Parsing-Code weiß genau, welche Schlüssel er jedes Mal erwarten muss.

Der Strict Mode reduziert fehlerhaftes JSON, aber er prüft nicht, ob die Werte geschäftlich sinnvoll sind. Ein Standort kann schema-gültig sein und trotzdem eine Stadt sein, die Sie nicht bedienen. Hier kommt das Testen ins Spiel.

So testen Sie es in Apidog

Das Modell gibt Ihnen einen Tool-Aufruf. Bevor Sie ihn mit einer Live-Funktion verbinden, möchten Sie zwei Garantien: Die Argumente stimmen mit der von Ihnen erwarteten Form überein, und die nachgeschaltete API, die Ihre Funktion aufrufen würde, verhält sich so, wie Sie es annehmen. Apidog deckt beide Seiten ab, und es lohnt sich, präzise zu sein, welche.

Apidog validiert und simuliert die API-Seite. Es führt die Funktionen Ihrer Anwendung nicht aus. Was es gut macht, ist der Vertrag um sie herum.

Überprüfen Sie die Struktur der Argumente. Nehmen Sie den arguments-String aus einem echten Tool-Aufruf, behandeln Sie ihn als Anfragekörper und führen Sie in Apidog Überprüfungen darauf durch. Überprüfen Sie, ob location existiert und ein String ist, dass ein Enum-Feld immer nur einen erlaubten Wert enthält, und dass erforderliche Felder vorhanden sind. Das Extrahieren spezifischer Felder aus der Payload ist einfach mit JSONPath-Ausdrücken, und für tiefere strukturelle Prüfungen gibt es die Validierung gegen ein JSON-Schema, das dasselbe Schema widerspiegelt, das Sie OpenAI im Strict Mode übergeben haben. Wenn die Ausgabe des Modells dasselbe Schema erfüllt, das Ihre Funktion erwartet, haben Sie den Kreis geschlossen.

Simulieren Sie die nachgeschaltete API, die die Funktion aufrufen würde. Ihre get_weather-Funktion ruft wahrscheinlich einen Wetterdienstleister auf. Während der Entwicklung kann dieser Anbieter ratenbegrenzt, kostenpflichtig oder noch nicht fertiggestellt sein. Erstellen Sie eine Mock-API in Apidog, die eine realistische Wetter-Payload zurückgibt, richten Sie Ihre Funktion auf den Mock und testen Sie den gesamten Aufrufpfad, ohne eine Anfrage an den echten Dienst zu senden. Sie kontrollieren die Antwort, einschließlich Fehlerfällen, die die Live-API selten auf Anfrage produziert, sodass Sie bestätigen können, dass Ihr Code einen Timeout oder einen 429-Fehler verarbeitet, bevor ein Benutzer ihn findet.

Zusammenfassend lässt sich der Workflow beschreiben als: Erfassen Sie einen Tool-Aufruf von OpenAI, überprüfen Sie dessen Argumente in Apidog gegen Ihr Schema und führen Sie dann Ihre Funktion gegen einen Apidog-Mock der echten API aus. Sie überprüfen den Vertrag an beiden Enden, ohne Live-Aufrufe zu verbrauchen oder Randfälle zu erraten.

Häufig gestellte Fragen

Funktionieren Funktionsaufrufe sowohl in Chat Completions als auch in der Responses API? Ja. Beide Endpunkte unterstützen dies. Die Responses API vereinheitlicht Funktionen, die zuvor auf Chat Completions und die Assistants API aufgeteilt waren. Der Hauptunterschied liegt in der Struktur: Chat Completions verschachtelt die Funktion unter einem function-Schlüssel und gibt tool_calls zurück, während die Responses API eine flache Tool-Definition verwendet und function_call-Elemente im output-Array zurückgibt.

Warum gibt das Modell Argumente als String anstelle eines Objekts zurück? Das Feld arguments ist JSON-kodierter Text. Sie parsen es in Ihrem Code, bevor Sie es verwenden. Dies ist bei beiden APIs konsistent, also lassen Sie es immer durch Ihren JSON-Parser laufen und validieren Sie das Ergebnis, anstatt ihm blind zu vertrauen. Das Ausführen dieser Argumente durch eine JSON-Schema-Validierung fängt eine fehlerhafte Payload ab, bevor sie Ihre Funktion erreicht.

Garantiert der Strict Mode, dass die Funktion erfolgreich ist? Nein. Der Strict Mode garantiert, dass die Argumente Ihrem JSON-Schema entsprechen, sodass die Struktur zuverlässig ist. Er prüft nicht, ob die Werte für Ihre Geschäftslogik korrekt sind, und er führt Ihre Funktion nicht aus. Sie müssen die Werte immer noch selbst validieren und die Fehler des nachgeschalteten Aufrufs selbst behandeln.

Kann Apidog meine eigentliche Funktion ausführen? Nein, und das versucht es auch nicht. Apidog validiert die vom Modell erzeugten Argumente und simuliert die API, von der Ihre Funktion abhängt. Ihre Anwendung führt weiterhin ihre eigenen Funktionen aus. Apidog deckt den Vertrag auf beiden Seiten ab, sodass Sie den Eingaben und Abhängigkeiten vertrauen können, bevor Sie live gehen.

Zusammenfassung

Sie haben nun den vollständigen Ablauf: Definieren Sie Ihre Tools klar, senden Sie sie mit der Anfrage, lesen Sie die Ausgabe von tool_calls oder function_call, geben Sie das Ergebnis zurück, aktivieren Sie dann den Strict Mode und entscheiden Sie, ob parallele Aufrufe helfen oder schaden. Schließen Sie dies mit Tests ab, indem Sie überprüfen, ob die Argumente Ihrem Schema entsprechen, und die nachgeschaltete API simulieren, damit Sie vor der Produktion zuversichtlich sind.

Möchten Sie die Testseite ausprobieren? Laden Sie Apidog herunter, um Tool-Aufruf-Argumente gegen Ihr Schema zu überprüfen und die APIs, von denen Ihre Funktionen abhängen, an einem Ort zu simulieren.