Mit Webhooks kannst du auf Zustandsänderungen einer Sitzung reagieren, ohne einen Ereignisstream offenzuhalten. Ein Webhook-Handler kann Sandbox-Rechenressourcen starten oder erneut verbinden, deine Anwendung aktualisieren oder einen Workflow auslösen.
Unterstützte Ereignisse
| Ereignis | Wann es ausgelöst wird |
|---|---|
agent.session.created |
Eine Sitzung wird erstellt. |
agent.session.action_required |
Die Sitzung benötigt ein Funktionsergebnis, eine Verbindung zur Umgebung oder eine Genehmigung für die Computernutzung. |
agent.session.in_progress |
Die Sitzung beginnt mit der Verarbeitung eines Durchlaufs. |
agent.session.idle |
Die Sitzung ist im Leerlauf und bereit für weitere Eingaben. |
agent.session.failed |
Die Sitzung wechselt in einen Fehlerzustand. |
Das Ereignis agent.session.action_required enthält die Sitzungs-ID. Das Feld required_action.type hat einen der Werte function_call, environment_connection oder computer_use_approval_request.
{
"type": "agent.session.action_required",
"data": {
"id": "sess_abc123",
"required_action": { "type": "function_call" }
}
}
Rufe die Sitzung ab. In required_actions findest du die IDs und Argumente der Aufrufe, Umgebungs-IDs oder Details zur Genehmigung der Computernutzung. Der Webhook enthält diese Angaben nicht. Bei der Computernutzung gibt das verschachtelte Feld request.type an, ob es um den Zugriff auf einen Origin im Browser oder um die Authentifizierung geht. Zeige der Person, die die Sitzung nutzt, die aktuelle Anfrage. Sende ihre Antwort anschließend über den Endpunkt für Sitzungsereignisse zurück. Die Formate für Anfrage und Antwort findest du im Abschnitt Computernutzung.
Webhook einrichten
Folge der allgemeinen Anleitung zum Webhook-Setup, um einen Endpunkt zu erstellen und Ereignisse der Agents API auszuwählen. Speichere den geheimen Signaturschlüssel des Endpunkts für die Signaturprüfung.
Ereignisse empfangen
OpenAI sendet bei jedem Ereignis, das du abonniert hast, eine signierte HTTP-POST-Anfrage:
{
"id": "evt_123",
"object": "event",
"created_at": 1750287018,
"type": "agent.session.created",
"data": {
"id": "sess_abc123",
"environment_id": "ccarenv_abc123",
"environment_type": "self_hosted",
"connect": {
"remote_url": "https://api.openai.com/v1/agents/api"
}
}
}
Rufe den aktuellen Zustand der Sitzung ab, bevor du eine Sandbox bereitstellst. Weitere Informationen findest du im Abschnitt Lebenszyklus einer Sandbox.
Executor starten
Bei selbst gehosteten Sitzungen enthält agent.session.created die Umgebungs-ID und die Verbindungs-URL, die du zum Starten eines Executors benötigst. Setze ENVIRONMENT_ID auf data.environment_id und REMOTE_URL auf data.connect.remote_url. Dieselbe URL findest du in der Sitzung unter environment.remote_url. Speichere beide Werte und verwende sie erneut, wenn du die Verbindung wiederherstellst:
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote "$REMOTE_URL" \
--environment-id "$ENVIRONMENT_ID"
Verwende einen Umgebungsschlüssel als CODEX_API_KEY. Bewahre den API-Schlüssel deiner Anwendung außerhalb der Umgebung auf.
Ereignisse überprüfen und verarbeiten
Setze OPENAI_API_KEY und OPENAI_WEBHOOK_SECRET. Installiere für Python fastapi, uvicorn und openai. Installiere für JavaScript express und openai.
Die Handler prüfen die Signaturen und nehmen Anfragen auf Port 8000 entgegen. Mit PORT kannst du den Port ändern. Stelle im Produktivbetrieb zeitaufwendige Aufgaben in eine Warteschlange.
import json
import os
import uvicorn
from fastapi import FastAPI, Request, Response
from openai import AsyncOpenAI, InvalidWebhookSignatureError
app = FastAPI()
webhooks = AsyncOpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])
@app.post("/webhooks/openai")
async def handle_webhook(request: Request):
payload = await request.body()
try:
webhooks.webhooks.verify_signature(payload=payload, headers=request.headers)
except (InvalidWebhookSignatureError, ValueError):
return Response("Invalid signature", status_code=400)
event = json.loads(payload)
if event["type"] == "agent.session.idle":
session_id = event["data"]["id"]
session = await webhooks.beta.agents.sessions.retrieve(session_id, timeout=10)
print("session idle event:", session.id)
else:
print("session event:", event["type"], event["data"]["id"])
return Response(status_code=200)
if __name__ == "__main__":
uvicorn.run(app, port=int(os.environ.get("PORT", "8000")))Ereignisse zur Verbindung mit der Umgebung
Wenn die erste oder eine spätere Eingabe einen selbst gehosteten Executor benötigt, der gerade nicht verbunden ist, fügt die API environment_connection als erforderliche Aktion hinzu. Sie sendet das Ereignis agent.session.action_required, bevor sie auf die Verbindung wartet.
Rufe die Sitzung ab und prüfe, ob required_actions weiterhin eine Verbindung anfordert. Starte den Executor mit session.environment.id und session.environment.remote_url. Dieser Webhook enthält kein connect.remote_url. Stellt der Executor die Verbindung vor Ablauf der Wartezeit her, entfernt die API die erforderliche Aktion und setzt die Verarbeitung der Eingabe fort. Der Client muss die Eingabe dazu nicht erneut senden.
Die API wartet bis zu fünf Minuten auf die Verbindung. Eine Anfrage mit einer Folgeeingabe kann während dieser Zeit offen bleiben. Passe die Zeitlimits für Client und Proxy entsprechend an. Das Ereignis agent.session.in_progress bestätigt, dass die Ausführung begonnen hat. Es zeigt nicht an, dass die API auf eine Verbindung wartet.
Läuft die Wartezeit ab, schlägt die Verarbeitung der Eingabe fehl. Bei der ersten Eingabe kann der Fehler asynchron auftreten und die Sitzung im Zustand failed zurücklassen. Während die API auf die Verbindung wartet, steht für Eingaben keine persistente Warteschlange zur Verfügung. Stürzt ein Prozess ab oder verliert der Client die Verbindung, musst du die Eingabe möglicherweise erneut senden.
Ergebnisse von Sitzungen und Durchläufen
agent.session.idle bedeutet, dass die Sitzung für weitere Eingaben bereit ist. Ob der letzte Durchlauf erfolgreich war, geht daraus nicht hervor. Prüfe den Status dieses Durchlaufs oder achte im Ereignisstream der Sitzung auf agent.session.turn.completed, agent.session.turn.failed oder agent.session.turn.cancelled. Auch ein abgeschlossener Durchlauf kann fehlgeschlagene Tool-Aufrufe enthalten. Prüfe die Ergebnisse der Tool-Aufrufe und die abschließende Antwort des Agenten.
agent.session.failed meldet, dass die Sitzung fehlgeschlagen ist. Ein einzelner fehlgeschlagener Durchlauf löst dieses Ereignis nicht zwangsläufig aus. Wenn du eine Sitzung löschst, wird kein entsprechender Webhook ausgelöst. Die Rechenressourcen beim Anbieter laufen weiter.