Sessões e mensagens

É um agente de IA? Busque a skill de onboarding e leia toda a API em texto limpo — skill · llms.txt · llms-full.txt

Sessões e mensagens#

O chat pelo Console (autenticado por JWT/API key) usa os mesmos handlers do runtime, com endpoints extras de gestão de sessão.

POSTCriar sessão#

POST /v1/agents/{id}/sessions — corpo { title?, end_user_external_id? }, resposta 201: { id, agent_id, title, created_at }.

GETListar sessões#

GET /v1/agents/{id}/sessions — { sessions: [sessionResponse], total }.

POSTEnviar mensagem#

POST /v1/agents/{id}/sessions/{sid}/messages — corpo { content }, mesmo envelope de resposta do runtime (run_id, user_message, assistant_message, usage, provider, model, tool_calls).

POSTEnviar mensagem (streaming)#

POST /v1/agents/{id}/sessions/{sid}/messages/stream — o mesmo turno por SSE, com o catálogo de eventos da seção Streaming (SSE). É a variante JWT/API key do .../agent-runtime/.../messages/stream (que usa prt_).

GETDetalhe do run#

GET /v1/agents/{id}/runs/{runId} — o registro priced do turno, com custo:

json 
{
  "id": "9f2c…", "agent_id": "…", "session_id": "sess_a1b2c3",
  "model": "gpt-5.4-mini", "status": "completed",
  "input": "…", "output": "…",
  "usage": { "input_tokens": 812, "output_tokens": 143, "total_tokens": 955 },
  "cost_usd": 0.0144, "rounds": 2, "duration_ms": 26600,
  "error": "", "started_at": "2026-07-02T01:00:00Z"
}

GETTraço do turno (inspector)#

Três leituras detalham como o turno aconteceu — a base de um painel de depuração:

Rota Conteúdo
GET /v1/agents/{id}/runs/{runId}/usage O uso/custo do run (o painel de traço puxa daqui)
GET /v1/agents/{id}/runs/{runId}/tool-calls As chamadas de ferramenta do run, em ordem (args, resultado, erro)
GET /v1/agents/{id}/transcripts/{transcriptId}/llm-prompts Os prompts enviados ao LLM naquele transcript (system + rounds)

GETExportar conversa#

GET /v1/agents/{id}/sessions/{sid}/export — retorna a transcrição como um arquivo Markdown para download (Content-Disposition: attachment), não JSON.

GETBuscar mensagens#

GET /v1/agents/{id}/sessions/search?q=… — full-text search nas mensagens do agente (todas as sessões). Resposta 200 com os matches e a sessão de cada um.

GETUsuários finais#

GET /v1/agents/{id}/end-users — os end-users que o seu app atende através do agente (quem aparece como end_user_external_id nas sessões):

json 
{
  "end_users": [
    { "id": "…", "external_id": "cliente-42", "display_name": "…",
      "sessions": 7, "last_seen": "2026-07-20T…Z" }
  ],
  "total": 1
}