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: trueund übergiboutputals String oder als Array mit Inhalten in einem unterstützten Format. Serialisiere JSON-Objekte als Strings. - Bei einem Fehler setze
success: falseund übergib inerroreine 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.
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.