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
| 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 inicial al entorno o una reconexión. |
agent.session.in_progress | La sesión comienza 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. |
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.
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.