Configuração de Resumo

Visão geral

A configuração summarization oferece controle centralizado sobre o resumo de conversas e a poda de contexto. Isso substitui os campos summarize e summaryModel por endpoint que estavam disponíveis anteriormente em endpoints personalizados e do Azure OpenAI.

Quando uma conversa excede a janela de contexto do modelo, o sistema de sumarização comprime automaticamente mensagens mais antigas em um resumo de ponto de verificação conciso. Isso permite que as conversas continuem indefinidamente sem perder o contexto importante. O sistema também inclui context pruning (poda de contexto), que degrada progressivamente resultados de ferramentas grandes em mensagens mais antigas para recuperar espaço de tokens antes que a sumarização seja necessária.

Após um turno de sumarização, o medidor de uso de contexto utiliza a linha de base do resumo persistido mais os turnos pós-resumo, em vez de recontar o histórico pré-resumo descartado. Os totais cumulativos de uso e custo ainda incluem o gasto total da ramificação.

Exemplo

summarization:
  provider: 'openAI'
  model: 'gpt-4o-mini'
  maxSummaryTokens: 4096
  reserveRatio: 0.05
  trigger:
    type: 'token_ratio'
    value: 0.8
  contextPruning:
    enabled: true
    keepLastAssistants: 3
    softTrimRatio: 0.3
    hardClearRatio: 0.5
    minPrunableToolChars: 50000
    softTrim:
      maxChars: 4000
      headChars: 1500
      tailChars: 1500
    hardClear:
      enabled: true
      placeholder: '[Old tool result content cleared]'

provider

Padrão: Provedor do próprio agente

model

Padrão: Modelo próprio do agente

parameters

prompt

Padrão: Um prompt de ponto de verificação estruturado que produz seções para Objetivo (Goal), Restrições e Preferências (Constraints & Preferences), Progresso (Progress), Decisões Principais (Key Decisions), Próximos Passos (Next Steps) e Contexto Crítico (Critical Context).

updatePrompt

Padrão: Um prompt integrado que mescla novas mensagens ao checkpoint existente, comprime detalhes mais antigos e fornece mais detalhes sobre ações recentes.

maxSummaryTokens

reserveRatio

Padrão: 0.05 (5% de margem)

trigger

Sub-chaves trigger

Tipos de Gatilho

Exemplo:

summarization:
  trigger:
    type: 'remaining_tokens'
    value: 8000

contextPruning

O context pruning é um recurso opcional que opera independentemente da sumarização. Ele tem como alvo resultados grandes de chamadas de ferramentas em mensagens mais antigas, aplicando dois estágios progressivos:

1. Soft trim — Trunca os resultados da ferramenta para manter apenas as partes inicial e final, com reticências no meio
2. Hard clear — Substitui todo o resultado da ferramenta por um breve espaço reservado

Ambos os estágios são baseados em posição: mensagens mais próximas do início da conversa (mais antigas) são removidas primeiro.

Sub-chaves de contextPruning

Padrões:

Sub-chaves de softTrim

Padrões: maxChars: 4000, headChars: 1500, tailChars: 1500

Sub-chaves hardClear

Padrões: enabled: true, placeholder: "[Old tool result content cleared]"

Exemplo:

summarization:
  contextPruning:
    enabled: true
    keepLastAssistants: 5
    softTrimRatio: 0.25
    hardClearRatio: 0.6
    minPrunableToolChars: 30000
    softTrim:
      maxChars: 6000
      headChars: 2500
      tailChars: 2500
    hardClear:
      enabled: true
      placeholder: '[Content removed for context management]'

Exemplo Completo de Configuração

version: 1.3.10
cache: true

summarization:
  provider: 'openAI'
  model: 'gpt-4o-mini'
  maxSummaryTokens: 4096
  reserveRatio: 0.05
  trigger:
    type: 'token_ratio'
    value: 0.8
  contextPruning:
    enabled: true
    keepLastAssistants: 3
    softTrimRatio: 0.3
    hardClearRatio: 0.5
    minPrunableToolChars: 50000
    softTrim:
      maxChars: 4000
      headChars: 1500
      tailChars: 1500
    hardClear:
      enabled: true
      placeholder: '[Old tool result content cleared]'

Migração das Configurações por endpoint

Se você usou anteriormente summarize e summaryModel em endpoints personalizados ou do Azure OpenAI:

endpoints:
  custom:
    - name: 'My Endpoint'
      summarize: true
      summaryModel: 'gpt-3.5-turbo'

Estes campos foram removidos. Use a configuração summarization de nível superior em vez disso:

summarization:
  model: 'gpt-4o-mini'

Notas

• A sumarização é configurada globalmente em vez de por endpoint
• Os campos summarize e summaryModel em endpoints personalizados e endpoints do Azure OpenAI não são mais suportados.
• Quando provider e model são omitidos, o provider e o model do próprio agente são usados para a sumarização.
• O corte de contexto (context pruning) está desativado por padrão e deve ser explicitamente habilitado com contextPruning.enabled: true
• O context pruning afeta apenas os resultados de chamadas de ferramenta que excedem minPrunableToolChars — resultados menores nunca são descartados.
• A configuração keepLastAssistants protege as interações recentes contra a remoção, independentemente das taxas de corte/limpeza (trim/clear).
• Os valores de prompt e updatePrompt personalizados substituem totalmente os prompts integrados — use com cuidado
• Defina AGENT_DEBUG_LOGGING=true no seu arquivo .env para habilitar o registro detalhado (verbose) de contagens de tokens e diagnósticos de poda de contexto.