Ensaiar um agente de tarefa
Roda um agente de tarefa (type=text, purpose=tarefa) sobre uma interação real (conversa ou ligação), AGORA, pelo mesmo executor dos hooks. Nada é simulado: as ferramentas rodam de verdade e o run é registrado e faturado. Por isso a Idempotency-Key é obrigatória. A interação deve ser do mesmo cliente. Devolve o run e o bloco que um pre-hook injetaria. O cliente bloqueado (§14) não ensaia: 402 TENANT_BLOCKED, sem run aberto. O 201 não traz Location: o run não tem endereço próprio na v3 — vem inteiro no corpo e aparece depois na lista da interação (GET /conversations/{conversation_id}/hook-runs ou GET /calls/{call_id}/hook-runs).
Autorização
bearer agents: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: agents:execute
Parâmetros de caminho
Id do agente de tarefa
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.
O corpo de POST /agents/{agent_id}/hook-runs.
Corpo da resposta
application/json
application/json
curl -X POST "https://example.com/agents/string/hook-runs" \ -H "Idempotency-Key: b3f0c1e2-4a5b-4c6d-8e9f-0a1b2c3d4e5f" \ -H "Content-Type: application/json" \ -d '{ "interaction": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "conversation" }, "phase": "pre" }'{ "block": "string", "run": null}