Edição de contexto



Visão geral

A edição de contexto permite que você remova seletivamente conteúdo específico do histórico da conversa à medida que ele cresce. Além de otimizar custos e permanecer dentro dos limites, trata-se de curar ativamente o que Claude vê: o contexto é um recurso finito com retornos decrescentes, e conteúdo irrelevante degrada o foco do modelo. A edição de contexto oferece controle refinado em tempo de execução sobre essa curadoria. Para os princípios mais amplos por trás do gerenciamento de contexto, consulte Effective context engineering. Esta página aborda:

• Limpeza de resultados de ferramentas - Ideal para fluxos de trabalho agênticos com uso intensivo de ferramentas, onde resultados antigos de ferramentas não são mais necessários
• Limpeza de blocos de pensamento - Para gerenciar blocos de pensamento ao usar pensamento estendido, com opções para preservar o pensamento recente para continuidade de contexto
• Compactação no lado do cliente via SDK - Uma alternativa baseada em SDK para gerenciamento de contexto por meio de resumos (a compactação no lado do servidor é geralmente preferida)



Estratégias no lado do servidor



Limpeza de resultados de ferramentas

A estratégia clear_tool_uses_20250919 remove resultados de ferramentas quando o contexto da conversa cresce além do limite configurado. Isso é particularmente útil para fluxos de trabalho agênticos com uso intensivo de ferramentas. Resultados de ferramentas mais antigos (como conteúdos de arquivos ou resultados de busca) não são mais necessários depois que Claude os processou.

Quando ativada, a API remove automaticamente os resultados de ferramentas mais antigos em ordem cronológica. A API substitui cada resultado removido por um texto de placeholder para que Claude saiba que ele foi removido. Por padrão, apenas os resultados de ferramentas são removidos. Opcionalmente, você pode remover tanto os resultados 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. Essa estratégia oferece controle sobre a preservação do pensamento: você pode optar por manter mais blocos de pensamento para preservar a continuidade do raciocínio, ou removê-los de forma mais agressiva para economizar espaço de contexto.

Um turno de conversa do assistente pode incluir vários blocos de conteúdo (por exemplo, ao usar ferramentas) e vários blocos de pensamento (por exemplo, com pensamento intercalado).



A edição de contexto acontece no lado do servidor

A edição de contexto é aplicada no lado do servidor antes de o prompt chegar ao Claude. Sua aplicação cliente mantém o histórico completo e não modificado da conversa. Você não precisa sincronizar o estado do seu cliente com a versão editada. Continue gerenciando seu histórico completo de conversa localmente como faria normalmente.



Edição de contexto e cache de prompt

A interação da edição de contexto com o cache de prompt varia de acordo com a estratégia:

• Limpeza de resultados de ferramentas: Invalida prefixos de prompt em cache quando o conteúdo é removido. Para compensar isso, remova tokens suficientes para que a invalidação do cache valha a pena. Use o parâmetro clear_at_least para garantir que um número mínimo de tokens seja removido a cada vez. Você incorrerá em custos de escrita de cache cada vez que o conteúdo for removido, mas requisições subsequentes podem reutilizar o prefixo recém-armazenado em cache.

• Limpeza de blocos de pensamento: Quando os blocos de pensamento são mantidos no contexto (não removidos), o cache de prompt é preservado, permitindo acertos de cache e reduzindo custos de tokens de entrada. Quando os blocos de pensamento são removidos, o cache é invalidado no ponto onde a remoção ocorre. Configure o parâmetro keep com base em se você deseja priorizar o desempenho do cache ou a disponibilidade da janela de contexto.



Modelos suportados

A edição de contexto está disponível em todos os modelos Claude suportados.



Uso da limpeza de resultados de ferramentas

A maneira mais simples de habilitar a limpeza de resultados de ferramentas é especificar apenas o tipo de estratégia. Todas as outras opções de configuração usam seus valores padrão:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)



Configuração avançada

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

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Aciona a limpeza quando o limite é excedido
                "trigger": {"type": "input_tokens", "value": 30000},
                # Número de usos de ferramentas a manter após a limpeza
                "keep": {"type": "tool_uses", "value": 3},
                # Opcional: limpar pelo menos esta quantidade de tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Excluir estas ferramentas da limpeza
                "exclude_tools": ["web_search"],
            }
        ]
    },
)



Uso da limpeza de blocos de pensamento

Habilite a limpeza de blocos de pensamento para gerenciar o contexto e o cache de prompt de forma eficaz quando o pensamento estendido estiver habilitado:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)



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:

Manter blocos de pensamento dos últimos 3 turnos do assistente:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

Manter todos os blocos de pensamento (maximiza acertos de cache):

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)



Combinando estratégias

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

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)



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



Resposta da edição de contexto

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

{
  "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 em streaming, as edições de contexto sã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 previamente quantos tokens seu prompt usará após a edição de contexto ser aplicada.

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

{
  "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 que sejam removidos do histórico da conversa.

Essa combinação permite que você:

• Preserve contexto importante: Claude pode escrever informações essenciais de resultados de ferramentas em arquivos de memória antes que esses resultados sejam removidos
• Mantenha fluxos de trabalho de longa duração: Habilite fluxos de trabalho agênticos que, de outra forma, excederiam os limites de contexto, transferindo informações para armazenamento persistente
• Acesse informações sob demanda: Claude pode consultar informações previamente removidas 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 arquivos em que Claude executa muitas operações, Claude pode resumir as alterações concluídas em arquivos de memória à medida que o contexto cresce. Quando os resultados de ferramentas são removidos, Claude mantém acesso a essas informações por meio de seu sistema de memória e pode continuar trabalhando de forma eficaz.

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

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Para a referência completa da ferramenta de memória, incluindo comandos e exemplos, consulte Ferramenta de memória.



Compactação no 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 cresce demais. Diferentemente das estratégias de edição de contexto no lado do servidor que removem conteúdo, a compactação instrui Claude a resumir o histórico da conversa e, em seguida, 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 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 de 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 é retomada a partir do resumo, com Claude continuando de onde parou.



Usando a compactação

Adicione compaction_control à sua chamada de tool_runner para habilitar a sumarização automática quando o uso de tokens exceder o limite.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



O que ocorre durante a compactação

À medida que 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 a compactação (de volta 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 desse resumo como se fosse o histórico original da conversa.



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 os limites.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    # Valores menores compactam com mais frequência; aumente para 150000 quando a tarefa precisar de mais contexto
    compaction_control={"enabled": True, "context_token_threshold": 50000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Usando um modelo diferente para resumos

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

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "model": "claude-haiku-4-5",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



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>.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    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.""",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



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óximos passos: 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 assumidos.

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



Limitações



Ferramentas no lado do servidor

Ao usar ferramentas no lado do servidor, o SDK pode calcular incorretamente o uso de tokens, fazendo com que a compactação seja 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

O SDK calcula o uso total como 63.000 + 0 + 270.000 + 1.400 = 334.400 tokens. No entanto, o valor de cache_read_input_tokens inclui leituras acumuladas de várias chamadas internas de API feitas pela ferramenta no lado do servidor, não o contexto real da sua conversa. O comprimento real do seu contexto pode ser apenas os 63.000 input_tokens, mas o SDK vê 334k e aciona a compactação prematuramente.

Soluções alternativas:

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



Casos extremos de uso de ferramentas

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



Monitorando a compactação

Entender quando a compactação é acionada ajuda você a ajustar limites e verificar o comportamento esperado.

import logging

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

# Os logs mostrarão:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500



Quando usar a 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 várias 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 exigem recordação precisa de detalhes iniciais da conversa
• Fluxos de trabalho que usam ferramentas no lado do servidor extensivamente
• Tarefas que precisam manter estado exato em muitas variáveis



Próximos passos