For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Webhooks de sessão

Reaja a mudanças no ciclo de vida do agente.

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

EventoQuando é disparado
agent.session.createdUma sessão é criada.
agent.session.action_requiredA 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_progressA sessão começa a processar um turno.
agent.session.idleA sessão está ociosa e pronta para receber mais entradas.
agent.session.failedA 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.

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

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.