Use webhooks para responder a mudanças no estado da sessão sem manter um fluxo de eventos aberto. Um manipulador de webhook pode iniciar ou reconectar recursos computacionais do sandbox, atualizar seu aplicativo ou acionar um fluxo de trabalho.
Eventos disponíveis
| Evento | Quando é disparado |
|---|---|
agent.session.created | Uma sessão é criada. |
agent.session.action_required | A sessão precisa do resultado de uma função, de uma conexão inicial com o ambiente ou de uma reconexão. |
agent.session.in_progress | A sessão começa a processar um turno. |
agent.session.idle | A sessão está ociosa e pronta para receber mais entradas. |
agent.session.failed | A sessão entra em estado de falha. |
Um evento agent.session.action_required inclui o ID da sessão e um
required_action.type com o valor function_call ou environment_connection.
{
"type": "agent.session.action_required",
"data": {
"id": "sess_abc123",
"required_action": { "type": "function_call" }
}
}
Recupere a sessão e examine required_actions para obter IDs de chamadas, argumentos ou
IDs de ambientes. O webhook não inclui esses detalhes.
Configure um webhook
Siga o guia compartilhado de configuração de webhooks para criar um endpoint e selecionar eventos da API de Agentes. Armazene o segredo de assinatura do endpoint para a verificação de assinaturas.
Receba eventos
A OpenAI envia uma requisição HTTP POST assinada sempre que ocorre um evento para o qual você se inscreveu:
{
"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"
}
}
}
Recupere o estado atual da sessão antes de provisionar um sandbox. Consulte Ciclo de vida do sandbox.
Inicie o executor
Para sessões hospedadas em infraestrutura própria, agent.session.created inclui o ID do ambiente e a URL de conexão necessários para iniciar um executor. Defina ENVIRONMENT_ID como data.environment_id e REMOTE_URL como data.connect.remote_url. Essa é a mesma URL retornada em environment.remote_url na sessão. Salve os dois valores e reutilize-os na reconexão:
CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
--remote "$REMOTE_URL" \
--environment-id "$ENVIRONMENT_ID"
Use uma chave de ambiente como CODEX_API_KEY. Mantenha a chave de API do seu aplicativo fora do ambiente.
Verifique e processe eventos
Defina OPENAI_API_KEY e OPENAI_WEBHOOK_SECRET. Para Python, instale fastapi, uvicorn e openai. Para JavaScript, instale express e openai.
Os manipuladores verificam assinaturas e escutam na porta 8000. Defina PORT para alterar a porta. Em produção, coloque tarefas mais demoradas em uma fila.
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 conexão com o ambiente
Quando uma entrada inicial ou subsequente precisa de um executor hospedado em infraestrutura própria que está desconectado, a API adiciona uma ação necessária do tipo environment_connection. Ela emite agent.session.action_required antes de aguardar a conexão.
Recupere a sessão e confirme que required_actions ainda solicita uma conexão. Inicie o executor com session.environment.id e session.environment.remote_url. Esse webhook não inclui connect.remote_url. Se o executor se conectar antes que o tempo de espera expire, a API remove a ação necessária e retoma o envio sem que o cliente precise reenviá-lo.
A API aguarda até cinco minutos pela conexão. Uma requisição de entrada subsequente pode permanecer aberta durante essa espera. Configure os tempos limite do cliente e do proxy de acordo com esse prazo. agent.session.in_progress confirma que a execução começou, não que a API está aguardando uma conexão.
Se o tempo de espera expirar, o envio falha. A entrada inicial pode falhar de forma assíncrona e deixar a sessão em failed. A espera pela conexão não fornece uma fila persistente de entradas. Uma falha no processo ou uma desconexão do cliente pode exigir novas tentativas.
Resultados de sessões e turnos
agent.session.idle significa que a sessão está pronta para receber mais entradas, não que o último turno foi bem-sucedido. Examine o status desse turno ou observe agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled no fluxo de eventos da sessão. Um turno concluído ainda pode conter chamadas de ferramentas que falharam. Verifique os resultados das ferramentas e a resposta final do agente.
agent.session.failed informa uma falha na sessão, não cada falha de turno. A exclusão de uma sessão não tem um webhook correspondente e não interrompe os recursos computacionais do provedor.