Utilisez les webhooks pour réagir aux changements d’état des sessions sans maintenir un flux d’événements ouvert. Un gestionnaire de webhooks peut démarrer ou reconnecter les ressources de calcul du bac à sable, mettre à jour votre application ou déclencher un workflow.
Événements pris en charge
| Événement | Déclenchement |
|---|---|
agent.session.created | Une session est créée. |
agent.session.action_required | La session a besoin du résultat d’une fonction, d’une connexion initiale à l’environnement ou d’une reconnexion. |
agent.session.in_progress | La session commence à traiter un tour. |
agent.session.idle | La session est inactive et prête à recevoir de nouvelles entrées. |
agent.session.failed | La session passe à un état d’échec. |
Un événement agent.session.action_required inclut l’ID de la session et un champ
required_action.type dont la valeur est function_call ou environment_connection.
{
"type": "agent.session.action_required",
"data": {
"id": "sess_abc123",
"required_action": { "type": "function_call" }
}
}
Récupérez la session et examinez required_actions pour obtenir les ID d’appel, les arguments ou les
ID d’environnement. Le webhook n’inclut pas ces détails.
Configurez un webhook
Suivez le guide commun de configuration des webhooks pour créer un point de terminaison et sélectionner les événements de l’API Agents. Conservez le secret de signature du point de terminaison pour la vérification des signatures.
Recevez des événements
OpenAI envoie une requête HTTP POST signée chaque fois qu’un événement auquel vous êtes abonné se produit :
{
"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"
}
}
}
Récupérez l’état actuel de la session avant de provisionner un bac à sable. Consultez Cycle de vie du bac à sable.
Démarrez l’exécuteur
Pour les sessions auto-hébergées, agent.session.created inclut l’ID de l’environnement et l’URL de connexion nécessaires au démarrage d’un exécuteur. Définissez ENVIRONMENT_ID sur data.environment_id et REMOTE_URL sur data.connect.remote_url. Il s’agit de la même URL que celle renvoyée dans le champ environment.remote_url de la session. Enregistrez ces deux valeurs et réutilisez-les lors de la reconnexion :
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote "$REMOTE_URL" \
--environment-id "$ENVIRONMENT_ID"
Utilisez une clé d’environnement comme valeur de CODEX_API_KEY. Conservez la clé API de votre application en dehors de l’environnement.
Vérifiez et traitez les événements
Définissez OPENAI_API_KEY et OPENAI_WEBHOOK_SECRET. Pour Python, installez fastapi, uvicorn et openai. Pour JavaScript, installez express et openai.
Les gestionnaires vérifient les signatures et écoutent sur le port 8000. Définissez PORT pour changer de port. En production, placez les traitements plus longs dans une file d’attente.
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")))Événements de connexion à l’environnement
Lorsque les entrées initiales ou suivantes nécessitent un exécuteur auto-hébergé déconnecté, l’API ajoute une action requise de type environment_connection. Elle émet agent.session.action_required avant d’attendre la connexion.
Récupérez la session et confirmez que required_actions demande toujours une connexion. Démarrez l’exécuteur avec session.environment.id et session.environment.remote_url. Ce webhook n’inclut pas connect.remote_url. Si l’exécuteur se connecte avant l’expiration du délai d’attente, l’API supprime l’action requise et reprend le traitement de la soumission sans que le client ait à la renvoyer.
L’API attend la connexion pendant cinq minutes au maximum. Une requête d’envoi d’entrées supplémentaires peut rester ouverte pendant cette attente. Configurez les délais d’expiration du client et du proxy en conséquence. agent.session.in_progress confirme que l’exécution a commencé, et non que l’API attend une connexion.
Si le délai d’attente expire, la soumission échoue. Le traitement des entrées initiales peut échouer de manière asynchrone et laisser la session dans l’état failed. L’attente de connexion ne constitue pas une file d’attente persistante pour les entrées. Un plantage du processus ou une déconnexion du client peut nécessiter de nouvelles tentatives.
Résultats des sessions et des tours
agent.session.idle indique que la session est prête à recevoir de nouvelles entrées, et non que son dernier tour a réussi. Examinez l’état de ce tour ou surveillez les événements agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled dans le flux de la session. Un tour terminé peut néanmoins contenir des appels d’outils ayant échoué. Vérifiez les résultats des outils et la réponse finale de l’agent.
agent.session.failed signale l’échec d’une session, et non chaque échec d’un tour. La suppression d’une session ne déclenche aucun webhook correspondant et n’arrête pas les ressources de calcul du fournisseur.