Consulta de Agent

Execute um agent contra uma consulta e receba sua resposta. O único endpoint suporta dois modos, selecionados pelo campo stream do corpo da requisição: uma resposta JSON bloqueante (o padrão) ou uma resposta de Server-Sent Events em streaming.

Executar um agent exige o scope agents:query. Cada consulta é medida contra a cota de consultas do seu plano no lado do servidor — excedê-la retorna 429 na via bloqueante, ou um único evento error na via de streaming.

`POST /agents/{agent_id}/query`

Execute o agent identificado por agent_id.

Scope: agents:query · Sucesso: 200

Parâmetro	Em	Tipo	Obrigatório	Descrição
`agent_id`	path	string	Sim	O agent a executar.
`query`	body	string	Sim	A consulta do usuário (1–10000 caracteres).
`stream`	body	boolean	Não	Quando `true`, retorna um stream SSE. Padrão `false`.
`conversation_id`	body	string	Não	Continua uma conversa de múltiplos turnos. Tem precedência sobre `session_id`.
`session_id`	body	string	Não	Uma key alternativa de múltiplos turnos (ignorada se `conversation_id` estiver definido).
`Idempotency-Key`	header	string	Não	Key de nova tentativa segura. Respeitada na via bloqueante; ignorada quando `stream: true`.

Modo bloqueante (padrão)

Com stream omitido ou false, o endpoint retorna um único corpo JSON assim que a execução é concluída.


curl -X POST https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e/query \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is the parental leave policy?" }'


{
  "agent_id": "agt_7c1d8e",
  "conversation_id": "conv_4d8a1f",
  "response": "Eligible employees receive 16 weeks of paid parental leave...",
  "tools_used": [
    { "name": "knowledge_search", "status": "complete" }
  ],
  "usage": {
    "prompt_tokens": 820,
    "completion_tokens": 145,
    "total_tokens": 965
  },
  "latency_ms": 1840,
  "created_at": "2026-06-07T12:00:00Z"
}

Campo	Tipo	Descrição
`agent_id`	string	O agent que foi executado.
`conversation_id`	string \| null	Passe-o de volta como `conversation_id` para continuar a conversa.
`response`	string	O texto da resposta do agent.
`tools_used`	array	As ferramentas que o agent invocou, cada uma como `{name, status}`. `status` é `complete` ou `error`.
`usage`	object	Contagens de tokens: `prompt_tokens`, `completion_tokens`, `total_tokens`. Nenhum custo é retornado.
`latency_ms`	integer \| null	Latência de resposta em tempo real, em milissegundos.
`created_at`	string \| null	Quando a consulta foi respondida (ISO-8601).

Para continuar uma conversa de múltiplos turnos, envie o conversation_id de uma resposta anterior na próxima chamada.

Modo de streaming (SSE)

Com stream: true, o endpoint retorna um text/event-stream de Server-Sent Events. Defina stream: true no corpo e leia a resposta de forma incremental.


curl -N -X POST https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e/query \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is the parental leave policy?", "stream": true }'

O esquema de eventos v1

O stream v1 emite exatamente seis nomes de eventos. Qualquer outro evento interno é descartado — seu cliente só vê estes:

Evento	Quando	Carga útil `data:`
`start`	A execução começou.	`{ "agent_id", "conversation_id" }`
`content`	Um fragmento incremental do texto da resposta.	`{ "delta": "..." }`
`tool_call`	Uma invocação de ferramenta começou.	`{ "tool": "...", "status": "running" }`
`tool_result`	Uma invocação de ferramenta terminou.	`{ "tool": "...", "status": "complete" }`
`done`	A execução foi concluída.	`{ "tokens_used", "latency_ms", "conversation_id" }`
`error`	A execução falhou ou foi recusada (p. ex. cota excedida).	`{ "error": "..." }`

Nenhum campo de custo aparece em qualquer evento — done carrega apenas contagens de tokens e latência.

Transcrição de exemplo

Uma execução em streaming bem-sucedida tem esta aparência no fio:


event: start
data: {"agent_id": "agt_7c1d8e", "conversation_id": "conv_4d8a1f"}

event: content
data: {"delta": "Eligible employees receive "}

event: tool_call
data: {"tool": "knowledge_search", "status": "running"}

event: tool_result
data: {"tool": "knowledge_search", "status": "complete"}

event: content
data: {"delta": "16 weeks of paid parental leave."}

event: done
data: {"tokens_used": 965, "latency_ms": 1840, "conversation_id": "conv_4d8a1f"}

Concatene os valores delta de cada evento content para construir a resposta completa. O evento done sinaliza o fim do stream.

Uma recusa — por exemplo, exceder sua cota de consultas — chega como um único evento error:


event: error
data: {"error": "Query allowance exceeded."}

Erros: 400, 401, 403 (scope), 404 agent_not_found, 429 (cota de consultas, via bloqueante), 500.