Executar um agente de texto
Manda uma mensagem a um agente de texto e devolve a execução. stream=true responde text/event-stream com os eventos da execução (run.started, message.delta, tool_call, run.completed, run.failed) e o cabeçalho Content-Location com o endereço da execução. persist=false não grava conversa nem mensagens — e então não continua conversa nenhuma. studio=true é execução de homologação (a tela Chat) e segue a regra do estúdio: um rascunho roda com o cliente bloqueado. A execução gasta tokens, então a Idempotency-Key é obrigatória: uma retentativa depois de um timeout não pode virar duas execuções e duas cobranças.
Autorização
bearer runs:executeCredencial da v3: o JWT da sessão (o mesmo da v2) ou um token pessoal dom_pat_…. A lista de escopos de cada operação diz o que ela exige: uma capacidade (agents:read), authenticated ou session-only. Segredo de máquina (X-Agent-Secret, X-API-Token, sdk_…) não é aceito.
Em: header
Escopo: runs:execute
Parâmetros de cabeçalho
Chave de 1 a 255 caracteres ASCII visíveis, estável por intenção do usuário: a mesma chave numa retentativa devolve a primeira resposta em vez de repetir o efeito.
Corpo da requisição
application/json
Definições TypeScript
Use o tipo request body no TypeScript.
Uma execução a começar. Idempotency-Key é obrigatório: uma retentativa
depois de um timeout não pode virar duas execuções, duas cobranças e duas
entradas na memória do agente.
Corpo da resposta
text/event-stream
application/json
application/json
curl -X POST "https://example.com/runs" \ -H "Idempotency-Key: b3f0c1e2-4a5b-4c6d-8e9f-0a1b2c3d4e5f" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "input": { "message": "string" } }'{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "conversation_id": "cc71b11a-25cd-4c2d-9950-df2cc38e3407", "input_message_id": "4761b30e-fe7a-4d53-b53b-ed5be1e65a17", "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec", "type": "run.started"}