OpenAI Function Calling nutzen: Eine Anleitung

Am Ende dieses Leitfadens können Sie ein OpenAI-Tool definieren, es an das Modell senden, den zurückgegebenen Tool-Aufruf auslesen und Ihre eigene Funktion mit den strukturierten Argumenten ausführen. Danach aktivieren Sie Strict Mode und parallele Aufrufe und testen die API-Seite mit Apidog, bevor Sie den Ablauf in Produktion verwenden. Halten Sie die Dokumentation zum Funktionsaufruf von OpenAI offen und lesen Sie bei Bedarf den Grundlagenartikel zum Erstellen von Agenten mit dem OpenAI Agents SDK.

Probieren Sie Apidog noch heute aus

Was Sie vor dem Start benötigen

Funktionsaufrufe, oft auch Tool-Aufrufe genannt, verbinden ein Modell mit Ihrem Code oder externen Systemen. Sie beschreiben eine Funktion, das Modell entscheidet anhand der Benutzereingabe, ob diese Funktion passt, und gibt dann den Funktionsnamen plus JSON-Argumente zurück.

Wichtig: Das Modell führt Ihre Funktion nicht selbst aus. Es erzeugt nur eine strukturierte Anfrage. Ihre Anwendung parst die Argumente, validiert sie und ruft anschließend den eigenen Code oder eine API auf.

Beispiel:

User: Wetter in Paris abrufen
Model: get_weather({"location": "Paris, France"})
App: führt get_weather aus und gibt das Ergebnis zurück

Sie benötigen:

• einen OpenAI API-Schlüssel
• eine Funktion in Ihrer Anwendung, die das Modell auslösen darf
• ein JSON-Schema für die Funktionsargumente
• optional eine API-Spezifikation oder Mock-API zum Testen

Sie können Tool-Aufrufe sowohl mit der älteren Chat Completions API als auch mit der neueren Responses API verwenden. Der Ablauf ist identisch, aber die Payload-Struktur unterscheidet sich leicht.

Schritt 1: Definieren Sie Ihr Tool

Ein Tool besteht aus:

• name: technischer Funktionsname
• description: klare Anweisung, wann das Tool verwendet werden soll
• parameters: JSON-Schema für die Argumente
• optional strict: erzwingt schema-konforme Argumente

Für Chat Completions liegt die Funktion unter einem function-Wrapper:

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

Für die Responses API ist die Struktur flacher. name, description, parameters und strict liegen direkt im Tool-Objekt.

Wenn Sie bereits eine OpenAPI-Spezifikation für Ihren Dienst pflegen, können Sie viele Parameterstrukturen daraus ableiten. Der Leitfaden zum Generieren von Testsammlungen aus OpenAPI-Spezifikationen zeigt, wie Sie diese Schemaarbeit wiederverwenden.

Schritt 2: Senden Sie das Tool an OpenAI

Senden Sie das Tool zusammen mit der Benutzernachricht. Beispiel mit Chat Completions:

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 alle Funktionen, die das Modell in dieser Runde verwenden darf. Wenn ein Tool zur Anfrage passt, gibt das Modell keinen normalen Antworttext zurück, sondern einen Tool-Aufruf.

Schritt 3: Lesen Sie den Tool-Aufruf aus

Wenn das Modell eine Funktion auswählt, enthält die Antwort den Namen der Funktion und die Argumente.

In Chat Completions finden Sie die Aufrufe im Feld tool_calls:

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

In der Responses API steht der Aufruf im output-Array:

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

Achten Sie auf ein wichtiges Detail: arguments ist ein JSON-kodierter String, kein bereits geparstes Objekt. Sie müssen den String selbst parsen.

Beispiel in JavaScript:

const toolCall = response.choices[0].message.tool_calls[0];

const functionName = toolCall.function.name;
const args = JSON.parse(toolCall.function.arguments);

if (functionName === "get_weather") {
  const result = await getWeather(args.location, args.unit);
}

Validieren Sie die geparsten Argumente, bevor Sie Ihre Funktion ausführen.

Schritt 4: Führen Sie Ihre Funktion aus

Das Modell ruft nicht Ihre Funktion auf. Ihre Anwendung muss den Tool-Aufruf auf eine echte Implementierung abbilden.

Beispiel:

async function getWeather(location, unit = "celsius") {
  const response = await fetch(
    `https://weather.example.com/current?location=${encodeURIComponent(location)}&unit=${unit}`
  );

  if (!response.ok) {
    throw new Error(`Weather API failed with status ${response.status}`);
  }

  return response.json();
}

Ein einfacher Dispatcher kann so aussehen:

async function runToolCall(toolCall) {
  const name = toolCall.function.name;
  const args = JSON.parse(toolCall.function.arguments);

  switch (name) {
    case "get_weather":
      return await getWeather(args.location, args.unit);
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
}

Behandeln Sie hier auch Fehlerfälle:

• ungültige Argumente
• unbekannte Funktionsnamen
• Timeouts
• 4xx/5xx-Antworten von APIs
• leere oder unvollständige Ergebnisse

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

Nachdem Ihre Funktion ausgeführt wurde, senden Sie das Ergebnis wieder an OpenAI. Das Modell verwendet dieses Ergebnis, um die endgültige Antwort an den Benutzer zu formulieren.

Bei Chat Completions fügen Sie eine Nachricht mit der Rolle tool hinzu und verknüpfen sie über tool_call_id:

{
  "role": "tool",
  "tool_call_id": "call_12345xyz",
  "content": "{\"temperature\":18,\"unit\":\"celsius\",\"condition\":\"cloudy\"}"
}

Der Ablauf ist:

1. Benutzer stellt Anfrage.
2. Modell gibt Tool-Aufruf zurück.
3. Ihre App parst und validiert die Argumente.
4. Ihre App führt die Funktion aus.
5. Ihre App sendet das Ergebnis zurück.
6. Modell erstellt die finale Antwort.

Schritt 6: Aktivieren Sie parallele Aufrufe und Strict Mode

Sobald der Grundablauf funktioniert, konfigurieren Sie Zuverlässigkeit und Ausführungsverhalten.

Parallele Tool-Aufrufe

Standardmäßig kann das Modell mehrere Tool-Aufrufe in einer Antwort zurückgeben. Beispiel: Fragt ein Benutzer nach dem Wetter in drei Städten, können drei Aufrufe gleichzeitig entstehen.

Wenn Ihre Funktionen unabhängig sind, können Sie diese parallel ausführen. Wenn Aufrufe voneinander abhängen oder in einer bestimmten Reihenfolge laufen müssen, setzen Sie:

{
  "parallel_tool_calls": false
}

Strict Mode

Mit strict: true erzwingen Sie, dass die Modellargumente Ihrem JSON-Schema entsprechen. OpenAI empfiehlt, den Strict Mode zu aktivieren.

Beispiel:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        },
        "unit": {
          "type": ["string", "null"],
          "enum": ["celsius", "fahrenheit", null]
        }
      },
      "required": ["location", "unit"],
      "additionalProperties": false
    }
  }
}

Im Strict Mode gelten wichtige Regeln:

• Jedes Objekt braucht additionalProperties: false.
• Alle Felder aus properties müssen in required stehen.
• Optionale Felder werden nicht aus required entfernt.
• Stattdessen erlauben Sie null als Wert.

Das bedeutet: Wenn unit optional sein soll, bleibt unit in required, akzeptiert aber null.

Einstellung	Was sie steuert	Standard	Wann ändern?
parallel_tool_calls	Ob mehrere Tool-Aufrufe in einem Durchlauf zurückkommen können	true	Auf false setzen, wenn Aufrufe voneinander abhängen oder geordnet ausgeführt werden müssen
strict	Ob Argumente dem Schema entsprechen müssen	Best-Effort, sofern nicht gesetzt	Für zuverlässiges Parsing aktivieren
tool_choice	Ob und welche Funktion das Modell aufrufen darf	auto	required zum Erzwingen, none zum Deaktivieren oder Funktionsname zum Festlegen

Der Strict Mode garantiert die Struktur, aber nicht die fachliche Korrektheit. Ein Standort kann schema-gültig sein und trotzdem außerhalb Ihres unterstützten Gebiets liegen. Validieren Sie daher zusätzlich Ihre Geschäftsregeln.

So testen Sie es in Apidog

Das Modell liefert einen Tool-Aufruf. Bevor Sie diesen mit Live-Code und echten APIs verbinden, sollten Sie zwei Dinge prüfen:

1. Entsprechen die Argumente der erwarteten Struktur?
2. Verhält sich die API, die Ihre Funktion aufruft, wie erwartet?

Apidog hilft beim Validieren und Simulieren der API-Seite. Es führt nicht Ihre Anwendungsfunktion aus, sondern testet den Vertrag um diese Funktion herum.

Argumente aus Tool-Aufrufen validieren

Nehmen Sie den arguments-String aus einem echten Tool-Aufruf und behandeln Sie ihn als Request Body.

Prüfen Sie zum Beispiel:

• Existiert location?
• Ist location ein String?
• Enthält unit nur erlaubte Enum-Werte?
• Sind alle erforderlichen Felder vorhanden?
• Gibt es unerwartete zusätzliche Felder?

Mit JSONPath-Ausdrücken können Sie einzelne Felder aus der Payload extrahieren. Für strukturelle Prüfungen nutzen Sie die Validierung gegen ein JSON-Schema.

Das Ziel: Dasselbe Schema, das Sie OpenAI übergeben, sollte auch die Payload validieren, die Ihre Funktion erwartet.

Nachgeschaltete API mocken

Ihre Funktion get_weather ruft wahrscheinlich einen Wetterdienst auf. In der Entwicklung ist dieser Dienst eventuell:

• rate-limitiert
• kostenpflichtig
• instabil
• noch nicht fertig
• schwer gezielt in Fehlerzustände zu bringen

Erstellen Sie dafür eine Mock-API in Apidog. Lassen Sie sie realistische Wetterdaten zurückgeben und richten Sie Ihre Funktion auf den Mock.

Damit können Sie testen:

• erfolgreiche Antworten
• Timeouts
• 429 Too Many Requests
• leere Ergebnisse
• ungültige Payloads
• serverseitige Fehler

Der praktische Workflow:

1. Tool-Aufruf von OpenAI erfassen.
2. arguments parsen.
3. Argumente in Apidog gegen Ihr Schema validieren.
4. Funktion gegen eine Apidog-Mock-API ausführen.
5. Fehlerfälle testen, bevor echte Benutzer betroffen sind.

Häufig gestellte Fragen

Funktionieren Funktionsaufrufe in Chat Completions und in der Responses API?

Ja. Beide Endpunkte unterstützen Tool-Aufrufe. Der Hauptunterschied liegt in der Struktur:

• Chat Completions verschachtelt die Funktion unter function und gibt tool_calls zurück.
• Die Responses API verwendet eine flachere Tool-Definition und gibt function_call-Elemente im output-Array zurück.

Warum gibt das Modell Argumente als String zurück?

arguments ist JSON-kodierter Text. Sie müssen ihn mit einem JSON-Parser in ein Objekt umwandeln.

Verlassen Sie sich nicht blind auf den Inhalt. Parsen und validieren Sie die Daten, bevor Sie Ihre Funktion ausführen. Eine JSON-Schema-Validierung fängt fehlerhafte Payloads ab, bevor sie Ihre Anwendung erreichen.

Garantiert der Strict Mode, dass die Funktion erfolgreich ist?

Nein. Der Strict Mode garantiert nur, dass die Argumente dem JSON-Schema entsprechen. Er prüft nicht, ob Werte fachlich korrekt sind, ob eine Stadt unterstützt wird oder ob eine externe API verfügbar ist.

Sie brauchen weiterhin:

• fachliche Validierung
• Fehlerbehandlung
• Logging
• Tests für nachgeschaltete Dienste

Kann Apidog meine eigentliche Funktion ausführen?

Nein. Apidog führt nicht Ihre Anwendungslogik aus. Es validiert die vom Modell erzeugten Argumente und simuliert APIs, von denen Ihre Funktion abhängt.

Ihre Anwendung bleibt für die Ausführung der Funktion verantwortlich. Apidog hilft dabei, Eingaben und API-Abhängigkeiten vor dem Live-Betrieb zu prüfen.

Zusammenfassung

Der Implementierungsablauf ist klar:

1. Tool mit Name, Beschreibung und JSON-Schema definieren.
2. Tool zusammen mit der Benutzeranfrage an OpenAI senden.
3. tool_calls oder function_call auslesen.
4. arguments parsen und validieren.
5. Eigene Funktion ausführen.
6. Ergebnis an das Modell zurückgeben.
7. Strict Mode aktivieren.
8. Parallele Aufrufe bewusst erlauben oder deaktivieren.
9. Argumente und nachgeschaltete APIs mit Apidog testen.

Wenn Sie die Testseite ausprobieren möchten, laden Sie Apidog herunter, um Tool-Aufruf-Argumente gegen Ihr Schema zu prüfen und die APIs zu simulieren, von denen Ihre Funktionen abhängen.