For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale

Webhooks de session

Réagissez aux changements du cycle de vie des agents.

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énementDéclenchement
agent.session.createdUne session est créée.
agent.session.action_requiredLa session a besoin du résultat d’une fonction, d’une connexion initiale à l’environnement ou d’une reconnexion.
agent.session.in_progressLa session commence à traiter un tour.
agent.session.idleLa session est inactive et prête à recevoir de nouvelles entrées.
agent.session.failedLa 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.

Gestionnaire de webhooks
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.