Runtime — embutir um agente#
O grupo /v1/agent-runtime/{id} é a superfície de embed. Autenticação só por
X-Agent-Token: prt_…; o token é preso a um agente, e as rotas de sessão têm
guarda de posse (proteção BOLA) — uma sessão de outro agente retorna
404 SESSION_NOT_FOUND. O grupo roda num timeout estendido (5 min) porque um
turno agêntico pode fazer várias chamadas de LLM. São os mesmos handlers do
chat do Console, então os shapes são idênticos.
POSTCriar sessão#
POST /v1/agent-runtime/{id}/sessions — corpo { end_user_external_id?, title? }
(ambos opcionais). Registrar o end_user_external_id cria/atualiza o usuário
final do agente, o que mantém a memória separada por pessoa. Resposta 201:
{ id, agent_id, title, created_at }.
GETListar mensagens#
GET /v1/agent-runtime/{id}/sessions/{sid}/messages — resposta 200:
{ messages: [messageResponse], total }. Cada messageResponse:
{
"id": "…",
"session_id": "sess_a1b2c3",
"role": "user | assistant | tool | system",
"content": "…",
"thinking": "…",
"tool_calls": [ { "name": "brain_search", "is_error": false, "output": "…", "duration_ms": 142 } ],
"run_id": "9f2c…",
"created_at": "2026-07-02T01:00:00Z"
}
thinking, tool_calls e run_id só aparecem quando presentes. No
tool_calls, o output público é truncado em 4096 caracteres (output_truncated
e output_chars sinalizam).
POSTEnviar mensagem#
POST /v1/agent-runtime/{id}/sessions/{sid}/messages — corpo { content }
(obrigatório, não-vazio). Roda o turno completo e retorna o envelope
{ run_id, user_message, assistant_message, usage, provider, model, tool_calls }
mostrado no Início rápido.
Quando alguma ferramenta anexada ao agente não pôde ser montada no turno, o
envelope traz também tools_unavailable: ["nome", …] (o campo é omitido quando está
vazio) — e o evento SSE complete carrega o mesmo. Causas típicas: a ferramenta foi
deletada/renomeada, ela é escopada a outro tenant (um agente só enxerga as do próprio
tenant + as company-global), ou é uma ferramenta de catálogo cuja integração não está
configurada. Trate a presença desse campo como erro de configuração: sem a ferramenta
o modelo tende a improvisar a chamada como texto em vez de executá-la.
O cost_usd do turno não vem nesse corpo — ele
fica persistido no run e é lido em GET /v1/agents/{id}/runs/{runId} (o evento
done do streaming também carrega o custo agregado).
POSTEnviar mensagem (streaming)#
POST /v1/agent-runtime/{id}/sessions/{sid}/messages/stream — o mesmo turno, em
SSE (Streaming SSE).