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
Theme

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 una 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

Evento Cuándo se emite
agent.session.created Se crea una sesión.
agent.session.action_required La sesión necesita el resultado de una función, una conexión al entorno o una aprobación para el uso de la computadora.
agent.session.in_progress La sesión empieza a procesar un turno.
agent.session.idle La sesión está inactiva y lista para recibir más entradas.
agent.session.failed La sesión pasa a un estado de error.

El evento agent.session.action_required incluye el ID de la sesión y el campo required_action.type, cuyo valor puede ser function_call, environment_connection o computer_use_approval_request.

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

Recupera la sesión y revisa required_actions para obtener los ID de las llamadas, los argumentos, los ID de los entornos o los detalles de la aprobación para el uso de la computadora. El webhook omite esos datos. Para el uso de la computadora, el campo anidado request.type indica si se solicita acceso a un origen del navegador o autenticación. Muestra la solicitud actual al usuario y luego devuelve su respuesta a través del punto de acceso de eventos de la sesión. Consulta Uso de la computadora para ver la estructura de la solicitud y de la respuesta.

Configurar un webhook

Sigue la guía general de configuración de webhooks para crear un punto de acceso y seleccionar los eventos de la API de agentes. Guarda el secreto de firma del punto de acceso para verificar las 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"
    }
  }
}

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

Iniciar el ejecutor

En las sesiones autoalojadas, agent.session.created incluye el ID del entorno y la URL de conexión que necesitas para iniciar un ejecutor. Asigna a ENVIRONMENT_ID el valor de data.environment_id y a REMOTE_URL el de data.connect.remote_url. Es la misma URL que devuelve la sesión en environment.remote_url. Guarda ambos valores y vuelve a usarlos al reconectar el ejecutor:

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

Usa una clave de entorno como valor de 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 que tarden más.

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 la entrada inicial o una entrada posterior requiere un ejecutor autoalojado que está desconectado, la API agrega una acción requerida de tipo environment_connection. Emite agent.session.action_required antes de empezar a esperar la conexión.

Recupera 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 venza el tiempo de espera, la API elimina la acción requerida y reanuda el procesamiento de la entrada sin que el cliente tenga que volver a enviarla.

La API espera hasta cinco minutos para que se establezca la conexión. La solicitud que envía una entrada posterior puede permanecer abierta durante ese tiempo. Ten en cuenta ese plazo al configurar los tiempos de espera del cliente y del proxy. agent.session.in_progress confirma que la ejecución ya comenzó. No indica que la API esté esperando una conexión.

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

Resultados de sesiones y turnos

agent.session.idle indica que la sesión está lista para recibir más entradas. El último turno pudo haber fallado. Revisa el estado de ese turno o busca los eventos 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 incluir llamadas a herramientas que fallaron. Revisa los resultados de las herramientas y la respuesta final del agente.

agent.session.failed indica que la sesión falló. No se emite por cada turno fallido. Al eliminar una sesión, no se emite ningún webhook de eliminación ni se detienen los recursos de cómputo del proveedor.