Resuma conversas longas do Cortex Agents com a Compact API

A nova Compact API do Cortex Agents permite resumir históricos de conversas longas para economizar tokens e evitar estourar a janela de contexto do modelo. O recurso funciona de duas formas: de maneira stateless enviando o histórico por parâmetro inline, ou stateful integrando com threads armazenadas no Snowflake.

Para que serve

Imagine que você tem um chatbot corporativo de inteligência artificial que mantém conversas longas com usuários e precisa otimizar o custo de processamento. Com esta novidade, você pode:

• Reduzir a quantidade de tokens consumidos em interações prolongadas com modelos de linguagem.
• Manter a sessão ativa sem ultrapassar limites da janela de contexto.
• Resumir históricos de forma automática via requisições REST.

Como usar

Envie uma requisição POST para o endpoint do agente para compactar um histórico stateless fornecido inline:

curl -X POST "https://<account>.snowflakecomputing.com/api/v2/cortex/agent:compact" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": [{ "type": "text", "text": "Qual foi o total de vendas no último trimestre?" }] },
      { "role": "assistant", "content": [{ "type": "text", "text": "As vendas totais foram de R$ 4,2 milhões..." }] }
    ]
  }'

O que acontece nesse código:

1. O payload envia o modelo e o array de mensagens contendo a transcrição da conversa.
2. O Snowflake processa o conteúdo e gera um resumo em linguagem natural.
3. O endpoint retorna um objeto JSON contendo o resumo gerado para ser injetado nas próximas chamadas.

Ou faça a compactação usando um identificador de thread para salvar o estado no servidor:

curl -X POST "https://<account>.snowflakecomputing.com/api/v2/cortex/agent:compact" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "model": "auto",
    "thread_id": 123
  }'

O que acontece nesse código:

1. A requisição aponta para o ID da thread existente sem precisar enviar a transcrição manualmente.
2. O sistema lê o histórico da thread, gera o resumo e grava uma mensagem do tipo COMPACTION.
3. O retorno fornece a string resumida e o ID da última mensagem para prosseguir nas próximas execuções.

O que retorna

Campo	Descrição
summary	Resumo em linguagem natural da conversa até o ponto compactado.
end_message_id	Identificador da última mensagem incluída na compactação (retornado apenas no modo stateful).

Limitações e requisitos

• Disponível em Public Preview para todas as contas.
• O endpoint não suporta streaming; retorna sempre uma resposta única em JSON.
• No modo stateless, o array de mensagens deve começar com uma mensagem de usuário (opcionalmente precedida por uma mensagem de sistema) e alternar entre papéis de usuário e assistente.
• Se ambos messages e thread_id forem enviados na mesma chamada, thread_id tem precedência e o payload de mensagens é ignorado.
• O uso é cobrado em créditos de IA por milhão de tokens processados conforme a tabela de preços do modelo utilizado, registrado na view de uso do account.
• É necessário possuir as roles SNOWFLAKE.CORTEX_USER ou SNOWFLAKE.CORTEX_AGENT_USER na conta Snowflake.