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

Funktionen

Definiere Funktionen, verarbeite ausstehende Aufrufe und gib Ergebnisse zurück.

Mit Funktions-Tools kann ein Agent deinen Anwendungscode aufrufen. Du definierst die Funktion und ihre Argumente. Der Agent fordert den Aufruf an, dein Code gibt ein Ergebnis zurück und der Harness setzt den aktuellen Turn fort.

Dein Handler kann auf einem Anwendungsserver, in einem Worker oder in einer von dir verwalteten Umgebung laufen. Wenn du eine Umgebung mit einer Sitzung verknüpfst, werden Funktions-Tools dort nicht automatisch ausgeführt.

Wenn du Funktionsaufrufe in der Responses API nutzt, kannst du deine bestehende Funktionsimplementierung für den hier beschriebenen Sitzungsablauf wiederverwenden.

Eine Funktion definieren

Füge die Funktionsdefinition zu agent.tools hinzu, wenn du den Agenten konfigurierst. Gib einen Namen, eine Beschreibung und ein JSON-Schema für die Argumente der Funktion an.

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

Erforderliche Aktionen verarbeiten

Wenn der Agent ein Funktionsergebnis benötigt, sendet die Sitzung das Ereignis agent.session.requires_action. Lies die ausstehenden Aufrufe aus event.session.required_actions aus. Du kannst auch ohne Streaming die Sitzung abrufen und session.required_actions auslesen.

So sieht ein Eintrag für einen Funktionsaufruf in required_actions aus:

{
  "type": "function_call",
  "turn_id": "turn_123",
  "call_id": "call_123",
  "name": "get_customer",
  "arguments": { "customer_id": "123" }
}

Führe die angegebene Funktion mit den übergebenen Argumenten aus. Prüfe anhand von required_actions, für welche Aufrufe noch Ergebnisse fehlen. Ein function_call-Eintrag im Sitzungsverlauf allein gibt keinen Aufschluss darüber, ob das Ergebnis noch aussteht.

Das Ergebnis zurückgeben

Sende agent.session.input.tool_result an den Endpunkt für Sitzungsereignisse. Übernimm turn_id und call_id aus der ausstehenden Aktion.

  • Bei Erfolg setze success: true und übergib output als String oder als Array mit Inhalten in einem unterstützten Format. Serialisiere JSON-Objekte als Strings.
  • Bei einem Fehler setze success: false und übergib in error eine Fehlermeldung, mit der der Agent weiterarbeiten kann.

Führe für jeden ausstehenden Aufruf von get_customer die Abfrage aus und gib das Ergebnis zurück. Im Beispiel steht action für den Eintrag aus required_actions.

Ein Funktionsergebnis zurückgeben
const result = {
  turn_id: action.turn_id,
  call_id: action.call_id,
};
let outcome;

outcome = {
  success: true,
  output: JSON.stringify(getCustomer(action.arguments)),
};

await client.beta.agents.sessions.events.create(sessionId, {
  events: [
    { type: "agent.session.input.tool_result", ...result, ...outcome },
  ],
});

Sobald der Harness die erforderlichen Ergebnisse erhält, setzt er den Turn fort. Verfolge die Sitzungsereignisse und -einträge, um zu prüfen, wie der Turn ausgegangen ist, und seine Ausgabe abzurufen.

Größe des Ergebnisses

Wenn die API ein Tool-Ergebnis wegen seiner Größe ablehnt, verkleinere es auf weniger als 4 MiB (4.194.304 Byte). Lass dabei etwas Platz für die Metadaten der Agents API. Sende das Ergebnis erneut mit derselben turn_id und derselben call_id, solange der Aufruf noch aussteht.

Nach einem Verbindungsabbruch fortfahren

Rufe die Sitzung ab, um ausstehende Aktionen zu ermitteln. Wenn du eine Funktion bereits ausgeführt hast, übermittle das gespeicherte Ergebnis mit derselben turn_id und derselben call_id.

Speichere die Ergebnisse von Funktionen mit Seiteneffekten dauerhaft und ordne sie der jeweiligen Sitzungs-, Turn- und Aufruf-ID zu. Falls die Ausführung erfolgreich gewesen sein könnte, aber kein Ergebnis gespeichert wurde, prüfe zuerst, was der Aufruf bewirkt hat, bevor du die Funktion erneut ausführst.

Funktionen bei Bedarf laden

Standardmäßig werden Funktionen sofort geladen. Wenn eine Funktion erst bei Bedarf geladen werden soll, setze in ihrer Definition defer_loading: true und füge { "type": "tool_search" } zu agent.tools hinzu. Ein vollständiges Beispiel findest du im Leitfaden zur Tool-Suche.