Você pode testar esta rota diretamente em nossa documentação interativa.

Retorna o histórico da conversa com resumo inteligente aplicado e estatísticas de economia. Usa o Smart Context para fatiar, resumir e formatar o diálogo conforme os parâmetros informados. O resumo é gerado e persistido automaticamente quando o diálogo ultrapassa o limiar de tokens configurado.

​
Endpoint

POST /api/v4/smart-context/get-context

​
Parâmetros

conversation_id
string
required

UUID da conversa a ser processada.

boxes
integer
default: "null"

Número de pares user/assistant a retornar. Omitir retorna tudo.

format
string
default: "array"

Formato de saída: array, json-string ou toon.

include_summary
boolean
default: "true"

Se false, retorna o diálogo sem aplicar resumo.

force_full_dialogue
boolean
default: "false"

Se true, ignora resumo e recorte — retorna o histórico completo (debug/análise).

smart_context_config
object

Configuração explícita do Smart Context para esta chamada. Sobrescreve a config do avatar quando informada.

boxes representa pares de mensagens (user + assistant). Uma “caixa” equivale a um turno completo. O parâmetro sempre recorta, independentemente de include_summary.

Caso de usoboxes sugerido
Captura simples de dados5
Formulário com contexto10
Extração de data3
Decisão de fluxo8
Resposta principal ou análise completaomitir
formatRetorno
arrayArray<{ role, content }> — para injetar em dialogue de chamada LLM
json-stringString com JSON.stringify() — para injetar em system message
toonString comprimida (experimental; verificar benchmark de tokens antes de usar)

​
Exemplo

curl -X POST {{BASE_URL}}/api/v4/smart-context/get-context \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "uuid-da-conversa",
    "boxes": 5,
    "format": "array",
    "include_summary": true
  }'

Com parâmetros adicionais:

curl -X POST {{BASE_URL}}/api/v4/smart-context/get-context \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "uuid-da-conversa",
    "boxes": 10,
    "format": "json-string",
    "include_summary": false
  }'

Histórico completo sem resumo (análise/debug):

curl -X POST {{BASE_URL}}/api/v4/smart-context/get-context \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "uuid-da-conversa",
    "force_full_dialogue": true
  }'

Com smart_context_config customizado:

curl -X POST {{BASE_URL}}/api/v4/smart-context/get-context \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "uuid-da-conversa",
    "smart_context_config": {
      "summary_model": "qwen-3-32b",
      "summary_provider": "cerebras",
      "threshold_tokens": 3000,
      "max_input_chars": 50000,
      "max_single_message_tokens": 1200,
      "truncated_message_target_tokens": 700
    }
  }'

​
Resposta

{
  "success": true,
  "data": {
    "dialogue": [
      { "role": "user", "content": "..." },
      { "role": "assistant", "content": "..." }
    ],
    "stats": {
      "boxCount": 5,
      "totalBoxes": 12,
      "summaryInjected": true,
      "pinnedMessageCount": 1,
      "source": "database",
      "cacheHit": false,
      "savings": {
        "originalCharCount": 12400,
        "returnedCharCount": 3100,
        "savedCharCount": 9300,
        "savedPercent": 75,
        "estimatedOriginalTokens": 3100,
        "estimatedReturnedTokens": 775,
        "estimatedSavedTokens": 2325
      }
    }
  }
}

​
Campos da Resposta

success
boolean

Indica sucesso da operação.

data
object

Dados retornados pela API.

​
Erros

CódigoDescrição
400Parâmetro conversation_id ausente
404Conversa não encontrada
500Erro interno do servidor

Esta rota expõe a função getContext() do módulo Smart Context. Para detalhes de arquitetura, fontes de diálogo, histerese de resumo, mensagens ancoradas e configuração, consulte a visão geral do Smart Context.

Smart Context — Visão GeralInvestigar Mensagem por ID