Janelas de contexto

À medida que as conversas crescem, você eventualmente se aproximará dos limites da janela de contexto. Este guia explica como as janelas de contexto funcionam e apresenta estratégias para gerenciá-las efetivamente.

Para conversas de longa duração e fluxos de trabalho com agentes, compactação do lado do servidor é a estratégia principal para gerenciamento de contexto. Para necessidades mais especializadas, edição de contexto oferece estratégias adicionais como limpeza de resultados de ferramentas e limpeza de blocos de pensamento.

Entendendo a janela de contexto

A "janela de contexto" refere-se a todo o texto que um modelo de linguagem pode referenciar ao gerar uma resposta, incluindo a resposta em si. Isso é diferente do grande corpus de dados em que o modelo de linguagem foi treinado, e em vez disso representa uma "memória de trabalho" para o modelo. Uma janela de contexto maior permite que o modelo lide com prompts mais complexos e longos. Uma janela de contexto menor pode limitar a capacidade do modelo de manter coerência em conversas estendidas.

O diagrama abaixo ilustra o comportamento padrão da janela de contexto para solicitações de API¹:

¹Para interfaces de chat, como para claude.ai, as janelas de contexto também podem ser configuradas em um sistema "primeiro a entrar, primeiro a sair" contínuo.

• Acumulação progressiva de tokens: À medida que a conversa avança através dos turnos, cada mensagem do usuário e resposta do assistente se acumulam dentro da janela de contexto. Os turnos anteriores são preservados completamente.
• Padrão de crescimento linear: O uso de contexto cresce linearmente com cada turno, com os turnos anteriores preservados completamente.
• Capacidade de 200K tokens: A janela de contexto total disponível (200.000 tokens) representa a capacidade máxima para armazenar histórico de conversa e gerar nova saída do Claude.
• Fluxo de entrada-saída: Cada turno consiste em:
  • Fase de entrada: Contém todo o histórico de conversa anterior mais a mensagem do usuário atual
  • Fase de saída: Gera uma resposta de texto que se torna parte de uma entrada futura

A janela de contexto com pensamento estendido

Ao usar pensamento estendido, todos os tokens de entrada e saída, incluindo os tokens usados para pensamento, contam para o limite da janela de contexto, com algumas nuances em situações multi-turno.

Os tokens do orçamento de pensamento são um subconjunto do seu parâmetro max_tokens, são cobrados como tokens de saída e contam para os limites de taxa. Com pensamento adaptativo, Claude decide dinamicamente sua alocação de pensamento, portanto o uso real de tokens de pensamento pode variar por solicitação.

No entanto, os blocos de pensamento anteriores são automaticamente removidos do cálculo da janela de contexto pela API Claude e não fazem parte do histórico de conversa que o modelo "vê" para turnos subsequentes, preservando a capacidade de tokens para conteúdo de conversa real.

O diagrama abaixo demonstra o gerenciamento especializado de tokens quando o pensamento estendido está ativado:

• Remoção de pensamento estendido: Os blocos de pensamento estendido (mostrados em cinza escuro) são gerados durante a fase de saída de cada turno, mas não são levados adiante como tokens de entrada para turnos subsequentes. Você não precisa remover os blocos de pensamento você mesmo. A API Claude faz isso automaticamente para você se você os passar de volta.
• Detalhes de implementação técnica:
  • A API automaticamente exclui blocos de pensamento de turnos anteriores quando você os passa de volta como parte do histórico de conversa.
  • Os tokens de pensamento estendido são cobrados como tokens de saída apenas uma vez, durante sua geração.
  • O cálculo efetivo da janela de contexto se torna: context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens.
  • Os tokens de pensamento incluem blocos thinking e blocos redacted_thinking.

Esta arquitetura é eficiente em tokens e permite raciocínio extenso sem desperdício de tokens, pois os blocos de pensamento podem ser substanciais em comprimento.

A janela de contexto com pensamento estendido e uso de ferramentas

O diagrama abaixo ilustra o gerenciamento de tokens da janela de contexto ao combinar pensamento estendido com uso de ferramentas:

• Considerações para uso de ferramentas com pensamento estendido:
  • Ao postar resultados de ferramentas, o bloco de pensamento completo e não modificado que acompanha essa solicitação de ferramenta específica (incluindo porções de assinatura/redação) deve ser incluído.
  • O cálculo efetivo da janela de contexto para pensamento estendido com uso de ferramentas se torna: context_window = input_tokens + current_turn_tokens.
  • O sistema usa assinaturas criptográficas para verificar a autenticidade do bloco de pensamento. Falhar em preservar blocos de pensamento durante o uso de ferramentas pode quebrar a continuidade de raciocínio do Claude. Assim, se você modificar blocos de pensamento, a API retornará um erro.

Janela de contexto de 1M tokens

Claude Opus 4.6, Sonnet 4.5 e Sonnet 4 suportam uma janela de contexto de 1 milhão de tokens. Esta janela de contexto estendida permite que você processe documentos muito maiores, mantenha conversas mais longas e trabalhe com bases de código mais extensas.

Para usar a janela de contexto de 1M tokens, inclua o cabeçalho beta context-1m-2025-08-07 em suas solicitações de API:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: context-1m-2025-08-07" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Process this large document..."}
    ]
  }'

Considerações importantes:

• Status beta: Esta é uma funcionalidade beta sujeita a alterações. Recursos e preços podem ser modificados ou removidos em versões futuras.
• Requisito de nível de uso: A janela de contexto de 1M tokens está disponível para organizações no nível de uso 4 e organizações com limites de taxa personalizados. Organizações de nível inferior devem avançar para o nível de uso 4 para acessar este recurso.
• Disponibilidade: A janela de contexto de 1M tokens está atualmente disponível na API Claude, Microsoft Foundry, Amazon Bedrock e Google Cloud's Vertex AI.
• Preços: Solicitações que excedem 200K tokens são automaticamente cobradas com taxas premium (2x entrada, 1,5x preço de saída). Consulte a documentação de preços para detalhes.
• Limites de taxa: Solicitações de contexto longo têm limites de taxa dedicados. Consulte a documentação de limites de taxa para detalhes.
• Considerações multimodais: Ao processar um grande número de imagens ou pdfs, esteja ciente de que os arquivos podem variar no uso de tokens. Ao emparelhar um prompt grande com um grande número de imagens, você pode atingir limites de tamanho de solicitação.

Consciência de contexto em Claude Sonnet 4.5 e Haiku 4.5

Claude Sonnet 4.5 e Claude Haiku 4.5 apresentam consciência de contexto. Esta capacidade permite que esses modelos rastreiem sua janela de contexto restante (ou seja, "orçamento de tokens") ao longo de uma conversa. Isso permite que Claude execute tarefas e gerencie contexto de forma mais eficaz, entendendo quanto espaço tem para trabalhar. Claude é treinado para usar este contexto com precisão, persistindo na tarefa até o final em vez de adivinhar quantos tokens permanecem. Para um modelo, a falta de consciência de contexto é como competir em um programa de culinária sem um relógio. Os modelos Claude 4.5 mudam isso informando explicitamente ao modelo sobre seu contexto restante, para que ele possa aproveitar ao máximo os tokens disponíveis.

Como funciona:

No início de uma conversa, Claude recebe informações sobre sua janela de contexto total:

<budget:token_budget>200000</budget:token_budget>

O orçamento é definido como 200K tokens (padrão), 500K tokens (claude.ai Enterprise) ou 1M tokens (beta, para organizações elegíveis).

Após cada chamada de ferramenta, Claude recebe uma atualização sobre a capacidade restante:

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

Esta consciência ajuda Claude a determinar quanto de capacidade permanece para trabalho e permite execução mais eficaz em tarefas de longa duração. Os tokens de imagem estão incluídos nestes orçamentos.

Benefícios:

A consciência de contexto é particularmente valiosa para:

• Sessões de agente de longa duração que requerem foco sustentado
• Fluxos de trabalho de múltiplas janelas de contexto onde transições de estado importam
• Tarefas complexas que requerem gerenciamento cuidadoso de tokens

Para orientação de prompting sobre como aproveitar a consciência de contexto, consulte o guia de melhores práticas de prompting.

Gerenciando contexto com compactação

Se suas conversas regularmente se aproximam dos limites da janela de contexto, compactação do lado do servidor é a abordagem recomendada. A compactação fornece sumarização do lado do servidor que condensa automaticamente as partes anteriores de uma conversa, permitindo conversas de longa duração além dos limites de contexto com trabalho de integração mínimo. Está atualmente disponível em beta para Claude Opus 4.6.

Para necessidades mais especializadas, edição de contexto oferece estratégias adicionais:

• Limpeza de resultado de ferramenta - Limpar resultados de ferramentas antigos em fluxos de trabalho com agentes
• Limpeza de bloco de pensamento - Gerenciar blocos de pensamento com pensamento estendido

Gerenciamento de janela de contexto com modelos Claude mais novos

Modelos Claude mais novos (começando com Claude Sonnet 3.7) retornam um erro de validação quando tokens de prompt e saída excedem a janela de contexto, em vez de truncar silenciosamente. Esta mudança fornece comportamento mais previsível, mas requer gerenciamento de tokens mais cuidadoso.

Use a API de contagem de tokens para estimar o uso de tokens antes de enviar mensagens para Claude. Isso ajuda você a planejar e permanecer dentro dos limites da janela de contexto.

Consulte a tabela de comparação de modelos para uma lista de tamanhos de janela de contexto por modelo.

Próximos passos