Docs
Console
Referência da API

Sessions

Crie execuções stateful, envie eventos do usuário e leia o histórico de uma session.

#Endpoints

MétodoCaminhoDescrição
POST/v1/projects/:projectId/sessionsCria uma session para um agent.
POST/v1/projects/:projectId/sessions/:id/eventsIngere eventos do usuário.
GET/v1/projects/:projectId/sessions/:id/artifactsEntregáveis da session agrupados por nome (versão mais recente + URL assinada).
PATCH/v1/projects/:projectId/sessions/:idRenomeia a session (`title`; `null` remove o título).
POST/v1/projects/:projectId/sessions/:id/archiveArquiva a session.
DELETE/v1/projects/:projectId/sessions/:idRemove a session.
GET/v1/projects/:projectId/sessions/:id/eventsLista eventos por `afterSeq`.
GET/v1/projects/:projectId/sessions/:idLê metadados e status da session.
GET/v1/projects/:projectId/sessionsLista sessions por cursor e filtros.

#Criar session

json
{
  "agent": { "id": "agent_...", "version": 3 },
  "title": "Atendimento #123",
  "metadata": { "customerId": "cus_123" },
  "resources": [{ "memoryStore": "ms_...", "mode": "read-only" }],
  "vaultIds": ["vault_..."]
}

agent também aceita apenas o ID para usar a versão atual. Para reprodutibilidade, prefira informar { id, version }.

#Ambiente, cofres e memória

environmentId, vaultIds e resources seguem a precedência explícito da chamada > padrão do agent > padrão da conta, resolvida na criação da session.

O sinal de "explícito" é a presença do campo, não o conteúdo:

No corpoEfeito
campo ausenteCai no padrão do agent e, na falta dele, no padrão da conta.
vaultIds: [] / resources: []Afirmação explícita "sem cofre / sem memória" — vence o padrão do agent.
environmentId: nullAfirmação explícita "ambiente base da conta".

A session é autocontida depois de nascer: mudar o padrão do agent não altera nenhuma session existente.

#Ingerir eventos

json
{
  "events": [
    {
      "type": "user.message",
      "content": [{ "type": "text", "text": "Explique a pendência do sinistro." }],
      "idempotencyKey": "claim-123-turn-1"
    }
  ]
}

Eventos ingeríveis:

TipoUso
user.messageMensagem ou instrução do usuário.
user.interruptSolicita interrupção da execução atual.
user.custom_tool_resultResponde uma custom tool executada pelo seu backend.
user.tool_confirmationAprova ou nega uma tool que exigiu confirmação.

#Histórico

http
GET /v1/projects/:projectId/sessions/:id/events?afterSeq=0&limit=100

Resposta:

json
{
  "data": [],
  "hasMore": true,
  "nextAfterSeq": 100
}

Use nextAfterSeq como próximo afterSeq até hasMore ser false.

#Listagem

GET /sessions aceita limit, cursor, agent, status e filtros de metadata no formato metadata[chave]=valor.

http
GET /v1/projects/:projectId/sessions?status=idle&metadata[customerId]=cus_123

#Renomear

http
PATCH /v1/projects/:projectId/sessions/:id
json
{ "title": "Edital ANS 2026" }

title é aparado nas pontas (1–200 caracteres) e null remove o título — a session volta ao rótulo padrão da interface. É só um rótulo: não escreve no log, não acorda o worker e funciona também em session arquivada, porque corrigir o nome de algo que já terminou é o caso mais comum.

No SDK: await client.sessions.rename('sess_...', 'Edital ANS 2026').

#Relacionado