Edição de contexto

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 limpa resultados de ferramentas quando o contexto da conversa cresce além do seu limite configurado. Quando ativada, a API limpa automaticamente os resultados de ferramentas mais antigos em ordem cronológica, substituindo-os por texto de espaço reservado para informar ao Claude que o resultado da ferramenta foi removido. Por padrão, apenas os resultados de ferramentas são limpos. Você pode opcionalmente limpar tanto os resultados de ferramentas quanto as chamadas de ferramentas (os parâmetros de uso de ferramentas) definindo clear_tool_inputs como true.

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 limpa resultados de ferramentas quando o contexto da conversa cresce além do seu limite configurado. Quando ativada, a API limpa automaticamente os resultados de ferramentas mais antigos em ordem cronológica, substituindo-os por texto de espaço reservado para informar ao Claude que o resultado da ferramenta foi removido. Por padrão, apenas os resultados de ferramentas são limpos. Você pode opcionalmente limpar tanto os resultados de ferramentas quanto as chamadas de ferramentas (os parâmetros de uso de ferramentas) definindo clear_tool_inputs como true.

Limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 gerencia blocos thinking em conversas quando o pensamento estendido está ativado. Esta estratégia limpa automaticamente blocos de pensamento mais antigos de turnos anteriores.

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 limpa resultados de ferramentas quando o contexto da conversa cresce além do seu limite configurado. Quando ativada, a API limpa automaticamente os resultados de ferramentas mais antigos em ordem cronológica, substituindo-os por texto de espaço reservado para informar ao Claude que o resultado da ferramenta foi removido. Por padrão, apenas os resultados de ferramentas são limpos. Você pode opcionalmente limpar tanto os resultados de ferramentas quanto as chamadas de ferramentas (os parâmetros de uso de ferramentas) definindo clear_tool_inputs como true.

Limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 gerencia blocos thinking em conversas quando o pensamento estendido está ativado. Esta estratégia limpa automaticamente blocos de pensamento mais antigos de turnos anteriores.

Modelos suportados

A edição de contexto está disponível em:

• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 limpa resultados de ferramentas quando o contexto da conversa cresce além do seu limite configurado. Quando ativada, a API limpa automaticamente os resultados de ferramentas mais antigos em ordem cronológica, substituindo-os por texto de espaço reservado para informar ao Claude que o resultado da ferramenta foi removido. Por padrão, apenas os resultados de ferramentas são limpos. Você pode opcionalmente limpar tanto os resultados de ferramentas quanto as chamadas de ferramentas (os parâmetros de uso de ferramentas) definindo clear_tool_inputs como true.

Limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 gerencia blocos thinking em conversas quando o pensamento estendido está ativado. Esta estratégia limpa automaticamente blocos de pensamento mais antigos de turnos anteriores.

Modelos suportados

A edição de contexto está disponível em:

• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Uso de limpeza de resultados de ferramentas

A forma mais simples de ativar a limpeza de resultados de ferramentas é especificar apenas o tipo de estratégia, pois todas as outras opções de configuração usarão seus valores padrão:

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 limpa resultados de ferramentas quando o contexto da conversa cresce além do seu limite configurado. Quando ativada, a API limpa automaticamente os resultados de ferramentas mais antigos em ordem cronológica, substituindo-os por texto de espaço reservado para informar ao Claude que o resultado da ferramenta foi removido. Por padrão, apenas os resultados de ferramentas são limpos. Você pode opcionalmente limpar tanto os resultados de ferramentas quanto as chamadas de ferramentas (os parâmetros de uso de ferramentas) definindo clear_tool_inputs como true.

Limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 gerencia blocos thinking em conversas quando o pensamento estendido está ativado. Esta estratégia limpa automaticamente blocos de pensamento mais antigos de turnos anteriores.

Modelos suportados

A edição de contexto está disponível em:

• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Uso de limpeza de resultados de ferramentas

A forma mais simples de ativar a limpeza de resultados de ferramentas é especificar apenas o tipo de estratégia, pois todas as outras opções de configuração usarão seus valores padrão:

Configuração avançada

Você pode personalizar o comportamento de limpeza de resultados de ferramentas com parâmetros adicionais:

Visão geral

A edição de contexto permite que você gerencie automaticamente o contexto da conversa conforme ele cresce, ajudando você a otimizar custos e permanecer dentro dos limites da janela de contexto. Você pode usar estratégias de API do lado do servidor, recursos de SDK do lado do cliente ou ambos juntos.

Estratégias do lado do servidor

Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 limpa resultados de ferramentas quando o contexto da conversa cresce além do seu limite configurado. Quando ativada, a API limpa automaticamente os resultados de ferramentas mais antigos em ordem cronológica, substituindo-os por texto de espaço reservado para informar ao Claude que o resultado da ferramenta foi removido. Por padrão, apenas os resultados de ferramentas são limpos. Você pode opcionalmente limpar tanto os resultados de ferramentas quanto as chamadas de ferramentas (os parâmetros de uso de ferramentas) definindo clear_tool_inputs como true.

Limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 gerencia blocos thinking em conversas quando o pensamento estendido está habilitado. Esta estratégia limpa automaticamente blocos de pensamento mais antigos de turnos anteriores.

Modelos suportados

A edição de contexto está disponível em:

• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Uso de limpeza de resultados de ferramentas

A forma mais simples de habilitar a limpeza de resultados de ferramentas é especificar apenas o tipo de estratégia, pois todas as outras opções de configuração usarão seus valores padrão:

Configuração avançada

Você pode personalizar o comportamento de limpeza de resultados de ferramentas com parâmetros adicionais:

Uso de limpeza de blocos de pensamento

Habilite a limpeza de blocos de pensamento para gerenciar contexto e cache de prompt efetivamente quando o pensamento estendido está habilitado:

Opções de configuração para limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 suporta a seguinte configuração:

Exemplos de configuração:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Opções de configuração para limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 suporta a seguinte configuração:

Exemplos de configuração:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinando estratégias

Você pode usar limpeza de blocos de pensamento e limpeza de resultados de ferramentas juntas:

Opções de configuração para limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 suporta a seguinte configuração:

Exemplos de configuração:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinando estratégias

Você pode usar limpeza de blocos de pensamento e limpeza de resultados de ferramentas juntas:

Opções de configuração para limpeza de resultados de ferramentas

Opções de configuração para limpeza de blocos de pensamento

A estratégia clear_thinking_20251015 suporta a seguinte configuração:

Exemplos de configuração:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinando estratégias

Você pode usar limpeza de blocos de pensamento e limpeza de resultados de ferramentas juntas:

Resposta de edição de contexto

Você pode ver quais edições de contexto foram aplicadas à sua solicitação usando o campo de resposta context_management, junto com estatísticas úteis sobre o conteúdo e tokens de entrada limpos.

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            // When using `clear_thinking_20251015`
            {
                "type": "clear_thinking_20251015",
                "cleared_thinking_turns": 3,
                "cleared_input_tokens": 15000
            },
            // When using `clear_tool_uses_20250919`
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,
                "cleared_input_tokens": 50000
            }
        ]
    }
}

Para respostas de streaming, as edições de contexto serão incluídas no evento final message_delta:

{
    "type": "message_delta",
    "delta": {
        "stop_reason": "end_turn",
        "stop_sequence": null
    },
    "usage": {
        "output_tokens": 1024
    },
    "context_management": {
        "applied_edits": [...]
    }
}

Opções de configuração para limpeza de bloco de pensamento

A estratégia clear_thinking_20251015 suporta a seguinte configuração:

Exemplos de configuração:

// Manter blocos de pensamento das últimas 3 voltas do assistente
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Manter todos os blocos de pensamento (maximiza acertos de cache)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinando estratégias

Você pode usar limpeza de bloco de pensamento e limpeza de resultado de ferramenta juntas:

Opções de configuração para limpeza de resultado de ferramenta

Resposta de edição de contexto

Você pode ver quais edições de contexto foram aplicadas à sua solicitação usando o campo de resposta context_management, juntamente com estatísticas úteis sobre o conteúdo e tokens de entrada limpos.

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            // Ao usar `clear_thinking_20251015`
            {
                "type": "clear_thinking_20251015",
                "cleared_thinking_turns": 3,
                "cleared_input_tokens": 15000
            },
            // Ao usar `clear_tool_uses_20250919`
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,
                "cleared_input_tokens": 50000
            }
        ]
    }
}

Para respostas de streaming, as edições de contexto serão incluídas no evento final message_delta:

{
    "type": "message_delta",
    "delta": {
        "stop_reason": "end_turn",
        "stop_sequence": null
    },
    "usage": {
        "output_tokens": 1024
    },
    "context_management": {
        "applied_edits": [...]
    }
}

Contagem de tokens

O endpoint de contagem de tokens suporta gerenciamento de contexto, permitindo que você visualize quantos tokens seu prompt usará após a edição de contexto ser aplicada.

{
    "input_tokens": 25000,
    "context_management": {
        "original_input_tokens": 70000
    }
}

A resposta mostra tanto a contagem final de tokens após o gerenciamento de contexto ser aplicado (input_tokens) quanto a contagem original de tokens antes de qualquer limpeza ocorrer (original_input_tokens).

Usando com a Ferramenta de Memória

A edição de contexto pode ser combinada com a ferramenta de memória. Quando o contexto da sua conversa se aproxima do limite de limpeza configurado, Claude recebe um aviso automático para preservar informações importantes. Isso permite que Claude salve resultados de ferramentas ou contexto em seus arquivos de memória antes de serem limpos do histórico de conversa.

Esta combinação permite que você:

• Preserve contexto importante: Claude pode escrever informações essenciais dos resultados de ferramentas em arquivos de memória antes que esses resultados sejam limpos
• Mantenha fluxos de trabalho de longa duração: Habilite fluxos de trabalho agênticos que de outra forma excederiam limites de contexto ao descarregar informações para armazenamento persistente
• Acesse informações sob demanda: Claude pode procurar informações previamente limpas em arquivos de memória quando necessário, em vez de manter tudo na janela de contexto ativa

Por exemplo, em um fluxo de trabalho de edição de arquivo onde Claude realiza muitas operações, Claude pode resumir alterações concluídas em arquivos de memória conforme o contexto cresce. Quando os resultados de ferramentas são limpos, Claude retém acesso a essas informações através de seu sistema de memória e pode continuar trabalhando efetivamente.

Para usar ambos os recursos juntos, habilite-os em sua solicitação de API:

Compactação do lado do cliente (SDK)

Compactação é um recurso do SDK que gerencia automaticamente o contexto da conversa gerando resumos quando o uso de tokens fica muito grande. Diferentemente das estratégias de edição de contexto do lado do servidor que limpam conteúdo, a compactação instrui Claude a resumir o histórico de conversa, depois substitui o histórico completo por esse resumo. Isso permite que Claude continue trabalhando em tarefas de longa duração que de outra forma excederiam a janela de contexto.

Como a compactação funciona

Quando a compactação está habilitada, o SDK monitora o uso de tokens após cada resposta do modelo:

1. Verificação de limite: O SDK calcula tokens totais como input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens
2. Geração de resumo: Quando o limite é excedido, um prompt de resumo é injetado como uma volta do usuário, e Claude gera um resumo estruturado envolvido em tags <summary></summary>
3. Substituição de contexto: O SDK extrai o resumo e substitui todo o histórico de mensagens por ele
4. Continuação: A conversa retoma a partir do resumo, com Claude continuando de onde parou

Usando compactação

Adicione compaction_control à sua chamada tool_runner:

O que acontece durante a compactação

Conforme a conversa cresce, o histórico de mensagens se acumula:

Antes da compactação (aproximando-se de 100k tokens):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
  { "role": "assistant", "content": "After analyzing file2.txt..." },
  // ... 50 more exchanges like this ...
]

Quando os tokens excedem o limite, o SDK injeta uma solicitação de resumo e Claude gera um resumo. Todo o histórico é então substituído:

Após compactação (voltando a ~2-3k tokens):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude continua trabalhando a partir deste resumo como se fosse o histórico de conversa original.

Opções de configuração

Escolhendo um limite de tokens

O limite determina quando a compactação ocorre. Um limite mais baixo significa compactações mais frequentes com janelas de contexto menores. Um limite mais alto permite mais contexto, mas corre o risco de atingir limites.

# More frequent compaction for memory-constrained scenarios
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# Less frequent compaction when you need more context
compaction_control={
    "enabled": True,
    "context_token_threshold": 150000
}

Usando um modelo diferente para resumos

Você pode usar um modelo mais rápido ou mais barato para gerar resumos:

compaction_control={
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5"
}

Prompts de resumo customizados

Você pode fornecer um prompt customizado para necessidades específicas de domínio. Seu prompt deve instruir Claude a envolver seu resumo em tags <summary></summary>.

compaction_control={
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags."""
}

Usando com a Ferramenta de Memória

A edição de contexto pode ser combinada com a ferramenta de memória. Quando o contexto da sua conversa se aproxima do limite de limpeza configurado, Claude recebe um aviso automático para preservar informações importantes. Isso permite que Claude salve resultados de ferramentas ou contexto em seus arquivos de memória antes de serem limpos do histórico de conversa.

Essa combinação permite que você:

• Preserve contexto importante: Claude pode escrever informações essenciais dos resultados de ferramentas em arquivos de memória antes que esses resultados sejam limpos
• Mantenha fluxos de trabalho de longa duração: Ative fluxos de trabalho de agentes que de outra forma excederiam os limites de contexto ao descarregar informações para armazenamento persistente
• Acesse informações sob demanda: Claude pode procurar informações previamente limpas em arquivos de memória quando necessário, em vez de manter tudo na janela de contexto ativa

Por exemplo, em um fluxo de trabalho de edição de arquivo onde Claude realiza muitas operações, Claude pode resumir alterações concluídas em arquivos de memória conforme o contexto cresce. Quando os resultados das ferramentas são limpos, Claude mantém acesso a essas informações através de seu sistema de memória e pode continuar trabalhando efetivamente.

Para usar ambos os recursos juntos, ative-os em sua solicitação de API:

Compactação do lado do cliente (SDK)

A compactação é um recurso do SDK que gerencia automaticamente o contexto da conversa gerando resumos quando o uso de tokens fica muito grande. Ao contrário das estratégias de edição de contexto do lado do servidor que limpam conteúdo, a compactação instrui Claude a resumir o histórico de conversa, depois substitui o histórico completo por esse resumo. Isso permite que Claude continue trabalhando em tarefas de longa duração que de outra forma excederiam a janela de contexto.

Como a compactação funciona

Quando a compactação está ativada, o SDK monitora o uso de tokens após cada resposta do modelo:

1. Verificação de limite: O SDK calcula o total de tokens como input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens
2. Geração de resumo: Quando o limite é excedido, um prompt de resumo é injetado como um turno do usuário, e Claude gera um resumo estruturado envolvido em tags <summary></summary>
3. Substituição de contexto: O SDK extrai o resumo e substitui todo o histórico de mensagens por ele
4. Continuação: A conversa retoma a partir do resumo, com Claude continuando de onde parou

Usando compactação

Adicione compaction_control à sua chamada tool_runner:

O que acontece durante a compactação

Conforme a conversa cresce, o histórico de mensagens se acumula:

Antes da compactação (aproximando-se de 100k tokens):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
  { "role": "assistant", "content": "After analyzing file2.txt..." },
  // ... 50 more exchanges like this ...
]

Quando os tokens excedem o limite, o SDK injeta uma solicitação de resumo e Claude gera um resumo. Todo o histórico é então substituído:

Após compactação (voltando para ~2-3k tokens):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude continua trabalhando a partir deste resumo como se fosse o histórico de conversa original.

Opções de configuração

Escolhendo um limite de tokens

O limite determina quando a compactação ocorre. Um limite mais baixo significa compactações mais frequentes com janelas de contexto menores. Um limite mais alto permite mais contexto, mas corre o risco de atingir limites.

# More frequent compaction for memory-constrained scenarios
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# Less frequent compaction when you need more context
compaction_control={
    "enabled": True,
    "context_token_threshold": 150000
}

Usando um modelo diferente para resumos

Você pode usar um modelo mais rápido ou mais barato para gerar resumos:

compaction_control={
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5"
}

Prompts de resumo personalizados

Você pode fornecer um prompt personalizado para necessidades específicas de domínio. Seu prompt deve instruir Claude a envolver seu resumo em tags <summary></summary>.

compaction_control={
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags."""
}

Prompt de resumo padrão

O prompt de resumo integrado instrui Claude a criar um resumo de continuação estruturado incluindo:

1. Visão Geral da Tarefa: A solicitação principal do usuário, critérios de sucesso e restrições
2. Estado Atual: O que foi concluído, arquivos modificados e artefatos produzidos
3. Descobertas Importantes: Restrições técnicas, decisões tomadas, erros resolvidos e abordagens que falharam
4. Próximas Etapas: Ações específicas necessárias, bloqueadores e ordem de prioridade
5. Contexto a Preservar: Preferências do usuário, detalhes específicos do domínio e compromissos feitos

Essa estrutura permite que Claude retome o trabalho de forma eficiente sem perder contexto importante ou repetir erros.

Limitações

Ferramentas do lado do servidor

Ao usar ferramentas do lado do servidor, o SDK pode calcular incorretamente o uso de tokens, causando a compactação ser acionada no momento errado.

Por exemplo, após uma operação de busca na web, a resposta da API pode mostrar:

{
  "usage": {
    "input_tokens": 63000,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

O SDK calcula o uso total como 63.000 + 270.000 = 333.000 tokens. No entanto, o valor cache_read_input_tokens inclui leituras acumuladas de múltiplas chamadas internas de API feitas pela ferramenta do lado do servidor, não seu contexto de conversa real. Seu comprimento de contexto real pode ser apenas os 63.000 input_tokens, mas o SDK vê 333k e aciona a compactação prematuramente.

Soluções alternativas:

• Use o endpoint de contagem de tokens para obter o comprimento de contexto preciso
• Evite compactação ao usar ferramentas do lado do servidor extensivamente

Casos extremos de uso de ferramentas

Quando a compactação é acionada enquanto uma resposta de uso de ferramenta está pendente, o SDK remove o bloco de uso de ferramenta do histórico de mensagens antes de gerar o resumo. Claude reabrirá a chamada de ferramenta após retomar do resumo se ainda for necessário.

Monitorando compactação

Ative o registro para rastrear quando a compactação ocorre:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

Quando usar compactação

Bons casos de uso:

• Tarefas de agente de longa duração que processam muitos arquivos ou fontes de dados
• Fluxos de trabalho de pesquisa que acumulam grandes quantidades de informações
• Tarefas de múltiplas etapas com progresso claro e mensurável
• Tarefas que produzem artefatos (arquivos, relatórios) que persistem fora da conversa

Casos de uso menos ideais:

• Tarefas que requerem recall preciso de detalhes de conversa anterior
• Fluxos de trabalho usando ferramentas do lado do servidor extensivamente
• Tarefas que precisam manter estado exato em muitas variáveis