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. A API fornece diferentes estratégias para gerenciar contexto:

• Limpeza de resultados de ferramentas (clear_tool_uses_20250919): Limpa automaticamente pares de uso/resultado de ferramentas quando o contexto da conversa excede seu limite configurado
• Limpeza de blocos de pensamento (clear_thinking_20251015): Gerencia blocos de pensamento limpando blocos de pensamento mais antigos de turnos anteriores

Cada estratégia pode ser configurada independentemente e aplicada em conjunto para otimizar seu caso de uso específico.

Estratégias de edição de contexto

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 resultados de ferramentas quanto 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.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 maneira 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:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

response = client.beta.messages.create(
    model="claude-sonnet-4-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"}
        ]
    }
)

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

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

Configuração avançada

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-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
            }
        ],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 3
                    },
                    "clear_at_least": {
                        "type": "input_tokens",
                        "value": 5000
                    },
                    "exclude_tools": ["web_search"]
                }
            ]
        }
    }'

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:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "messages": [...],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "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:

// 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:

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[...],
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[...],
    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
                }
            }
        ]
    }
)

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

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": [...]
    }
}

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.

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

{
    "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 de agentes que de outra forma excederiam limites de contexto descarregando 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 essa informação 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:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Your other tools
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {"type": "clear_tool_uses_20250919"}
        ]
    }
)