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

Webhooks de session

Réagissez aux changements d’état de l’agent au cours de son cycle de vie.

Utilisez les webhooks pour réagir aux changements d’état d’une session sans garder un flux d’événements ouvert. Un gestionnaire de webhook peut démarrer ou reconnecter les ressources de calcul d’un bac à sable, mettre à jour votre application ou déclencher un workflow.

Événements pris en charge

Événement Condition de 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 à un environnement ou d’une approbation pour utiliser l’ordinateur.
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 à l’état d’échec.

Un événement agent.session.action_required contient l’identifiant de la session et le champ required_action.type, qui vaut function_call, environment_connection ou computer_use_approval_request.

{
  "type": "agent.session.action_required",
  "data": {
    "id": "sess_abc123",
    "required_action": { "type": "function_call" }
  }
}

Récupérez la session et consultez required_actions pour obtenir les identifiants des appels, leurs arguments, les identifiants des environnements ou les détails de la demande d’approbation pour l’utilisation de l’ordinateur. Le webhook ne transmet pas ces informations. Pour l’utilisation de l’ordinateur, le champ imbriqué request.type indique si la demande concerne l’accès à une origine dans le navigateur ou l’authentification. Présentez la demande en cours à l’utilisateur, puis transmettez sa réponse au point de terminaison des événements de session. Consultez la section Utilisation de l’ordinateur pour connaître le format des demandes et des réponses.

Configuration d’un webhook

Suivez le guide général de configuration des webhooks pour créer un point de terminaison et sélectionner les événements de l’API Agents. Enregistrez le secret de signature du point de terminaison pour vérifier les signatures.

Réception 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 la section Cycle de vie du bac à sable.

Démarrage de l’exécuteur

Pour les sessions auto-hébergées, l’événement agent.session.created contient l’identifiant de l’environnement et l’URL de connexion nécessaires au démarrage d’un exécuteur. Affectez à ENVIRONMENT_ID la valeur de data.environment_id et à REMOTE_URL celle de data.connect.remote_url. La session renvoie cette même URL dans environment.remote_url. Enregistrez les 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érification et traitement des é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 tâches plus longues dans une file d’attente.

Gestionnaire de webhook
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 le traitement d’une entrée initiale ou ultérieure nécessite un exécuteur auto-hébergé qui est 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 vérifiez que required_actions demande toujours une connexion. Démarrez l’exécuteur avec session.environment.id et session.environment.remote_url. Ce webhook ne contient pas connect.remote_url. Si l’exécuteur se connecte avant l’expiration du délai, l’API supprime l’action requise et reprend le traitement de l’entrée sans que le client ait à la renvoyer.

L’API attend la connexion pendant cinq minutes au maximum. Une requête qui transmet une entrée ultérieure peut rester ouverte pendant cette attente. Configurez les délais d’expiration du client et du proxy en conséquence. L’événement agent.session.in_progress confirme que l’exécution a commencé. Il ne signale pas que l’API attend une connexion.

Si le délai expire, la soumission échoue. Le traitement de l’entrée initiale peut échouer de manière asynchrone et laisser la session dans l’état failed. Pendant l’attente de la connexion, les entrées ne sont pas conservées dans une file d’attente persistante. Si un processus s’arrête brutalement ou si le client se déconnecte, il peut être nécessaire de réessayer.

Résultats des sessions et des tours

L’événement agent.session.idle indique que la session est prête à recevoir de nouvelles entrées. Il ne garantit pas que le dernier tour a réussi. Vérifiez 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. Même si le tour s’est terminé avec succès, certains appels d’outils peuvent avoir échoué. Vérifiez les résultats des outils et la réponse finale de l’agent.

L’événement agent.session.failed signale l’échec d’une session. Il n’est pas émis à chaque échec d’un tour. La suppression d’une session ne déclenche aucun webhook et n’arrête pas les ressources de calcul du fournisseur.