For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal

Webhooks de sesión

Responde a los cambios en el ciclo de vida del agente.

Usa webhooks para responder a los cambios de estado de la sesión sin mantener abierto un flujo de eventos. Un controlador de webhooks puede iniciar o reconectar los recursos de cómputo del sandbox, actualizar tu aplicación o activar un flujo de trabajo.

Eventos admitidos

EventoCuándo se emite
agent.session.createdSe crea una sesión.
agent.session.action_requiredLa sesión necesita el resultado de una función, una conexión inicial al entorno o una reconexión.
agent.session.in_progressLa sesión comienza a procesar un turno.
agent.session.idleLa sesión está inactiva y lista para recibir más entradas.
agent.session.failedLa sesión pasa a un estado de error.

Un evento agent.session.action_required incluye el ID de la sesión y un required_action.type con el valor function_call o environment_connection.

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

Obtén la sesión y revisa required_actions para consultar los ID de las llamadas, los argumentos o los ID de los entornos. El webhook no incluye esos detalles.

Configurar un webhook

Sigue la guía compartida de configuración de webhooks para crear un punto de acceso y seleccionar eventos de la API de agentes. Guarda el secreto de firma del punto de acceso para la verificación de firmas.

Recibir eventos

OpenAI envía una solicitud HTTP POST firmada cada vez que ocurre un evento al que te suscribiste:

{
  "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"
    }
  }
}

Obtén el estado actual de la sesión antes de aprovisionar un sandbox. Consulta Ciclo de vida del sandbox.

Iniciar el ejecutor

En las sesiones con alojamiento propio, agent.session.created incluye el ID del entorno y la URL de conexión necesarios para iniciar un ejecutor. Establece ENVIRONMENT_ID en data.environment_id y REMOTE_URL en data.connect.remote_url. Es la misma URL que se devuelve como environment.remote_url en la sesión. Guarda ambos valores y reutilízalos al reconectarte:

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
  --remote "$REMOTE_URL" \
  --environment-id "$ENVIRONMENT_ID"

Usa una clave de entorno como CODEX_API_KEY. Mantén la clave de API de tu aplicación fuera del entorno.

Verificar y procesar eventos

Configura OPENAI_API_KEY y OPENAI_WEBHOOK_SECRET. Para Python, instala fastapi, uvicorn y openai. Para JavaScript, instala express y openai.

Los controladores verifican las firmas y escuchan en el puerto 8000. Configura PORT para cambiar el puerto. En producción, pon en cola las tareas más lentas.

Controlador 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")))

Eventos de conexión al entorno

Cuando una entrada inicial o posterior necesita un ejecutor con alojamiento propio que está desconectado, la API agrega una acción requerida de tipo environment_connection. Emite agent.session.action_required antes de esperar la conexión.

Obtén la sesión y confirma que required_actions aún solicita una conexión. Inicia el ejecutor con session.environment.id y session.environment.remote_url. Este webhook no incluye connect.remote_url. Si el ejecutor se conecta antes de que se agote el tiempo de espera, la API elimina la acción requerida y reanuda el envío sin que el cliente tenga que repetirlo.

La API espera hasta cinco minutos a que se establezca la conexión. Una solicitud de entrada posterior puede permanecer abierta durante esta espera. Configura los tiempos de espera del cliente y del proxy teniendo esto en cuenta. agent.session.in_progress confirma que la ejecución comenzó, no que la API esté esperando una conexión.

Si se agota el tiempo de espera, el envío falla. La entrada inicial puede fallar de forma asíncrona y dejar la sesión en failed. La espera de conexión no proporciona una cola de entradas persistente. Si el proceso se bloquea o el cliente se desconecta, puede ser necesario reintentar.

Resultados de las sesiones y los turnos

agent.session.idle significa que la sesión está lista para recibir más entradas, no que su último turno haya finalizado correctamente. Revisa el estado de ese turno u observa agent.session.turn.completed, agent.session.turn.failed o agent.session.turn.cancelled en el flujo de eventos de la sesión. Un turno completado puede contener llamadas a herramientas fallidas. Revisa los resultados de las herramientas y la respuesta final del agente.

agent.session.failed informa que una sesión falló, no cada vez que falla un turno. La eliminación de una sesión no tiene un webhook correspondiente ni detiene los recursos de cómputo del proveedor.