Janelas de contexto

À medida que as conversas crescem, você eventualmente se aproximará dos limites da janela de contexto. Para conversas de longa duração e fluxos de trabalho agênticos, a compactação no lado do servidor é a estratégia principal para gerenciamento de contexto.



Como a janela de contexto funciona

A "context window" (janela de contexto) refere-se a todo o texto que um modelo de linguagem pode referenciar ao gerar uma resposta, incluindo a própria resposta. Isto é diferente do grande corpus de dados em que o modelo de linguagem foi treinado, e 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, mas mais contexto não é automaticamente melhor. À medida que a contagem de tokens cresce, a precisão e a recuperação se degradam, um fenômeno conhecido como context rot (deterioração de contexto). Isso torna a curadoria do que está no contexto tão importante quanto a quantidade de espaço disponível.

O diagrama a seguir ilustra o comportamento padrão da janela de contexto para requisições de API¹:

¹ Interfaces de chat como o claude.ai também podem gerenciar a janela de contexto de forma contínua no modelo "primeiro a entrar, primeiro a sair".

• 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 acumula dentro da janela de contexto, e os turnos anteriores são preservados completamente.
• Capacidade da janela de contexto: A janela de contexto (até 1M de tokens, dependendo do modelo) contém o histórico da conversa mais a nova saída que Claude gera.
• Fluxo de entrada-saída: Cada turno consiste em:
  • Fase de entrada: Contém todo o histórico de conversa anterior mais a mensagem atual do usuário
  • Fase de saída: Gera uma resposta de texto que se torna parte da entrada para o próximo turno

Tudo na requisição conta para a janela de contexto: o prompt do sistema, cada mensagem em messages (incluindo resultados de ferramentas, imagens e documentos) e suas definições de ferramentas. A saída que Claude gera para o turno, incluindo seu pensamento estendido, também conta. Cada resposta relata o que a requisição consumiu em seu campo usage. Se você usar cache de prompt, a contagem de entrada é dividida entre input_tokens, cache_read_input_tokens e cache_creation_input_tokens, e todos os três contam para a janela. Para estimar uma requisição antes de enviá-la, use a API de contagem de tokens.



Tamanhos de janela de contexto por modelo

Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6 têm uma janela de contexto de 1M de tokens na API do Claude, Amazon Bedrock, Google Cloud e Microsoft Foundry. O Claude Mythos Preview também tem uma janela de contexto de 1M de tokens.

Claude Fable 5 e Claude Mythos 5 (claude-fable-5 e claude-mythos-5) também têm uma janela de contexto de 1M de tokens. Uma única requisição para qualquer modelo com uma janela de contexto de 1M de tokens pode gerar até 128k tokens de saída (max_tokens). Outros modelos Claude, incluindo o Claude Sonnet 4.5, têm uma janela de contexto de 200k tokens.

Para todo modelo com uma janela de contexto de 1M de tokens, 1M é o padrão: você não precisa de um cabeçalho beta, e requisições de contexto longo são cobradas com preços padrão.

Uma única requisição pode incluir até 600 imagens ou páginas de PDF (100 para modelos com uma janela de contexto de 200k tokens). Se você enviar muitas imagens ou documentos grandes, pode atingir os limites de tamanho de requisição antes do limite de tokens.

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



A janela de contexto com pensamento

Com o pensamento, todos os tokens de entrada e saída, incluindo tokens de pensamento, contam para o limite da janela de contexto, com algumas nuances em situações de múltiplos turnos.

Tokens 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 o pensamento adaptativo, Claude determina sua alocação de pensamento dinamicamente, então o uso de tokens de pensamento varia de requisição para requisição.

Se os blocos de pensamento de turnos anteriores do assistente permanecem na janela de contexto depende do modelo. No Claude Opus 4.5 e modelos Opus posteriores, Claude Sonnet 4.6 e modelos Sonnet posteriores, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, a API mantém os blocos de pensamento anteriores por padrão, e eles contam para a janela de contexto como quaisquer outros tokens de entrada. Em modelos Opus e Sonnet anteriores e em todos os modelos Haiku, a API remove automaticamente os blocos de pensamento anteriores do histórico da conversa quando você os passa de volta, o que preserva a capacidade de tokens para o conteúdo da conversa. Para os padrões por modelo, consulte preservação de blocos de pensamento por modelo. Para substituir o padrão em qualquer direção, use a limpeza de blocos de pensamento.

O diagrama a seguir mostra como os tokens são gerenciados quando o pensamento está habilitado em um modelo que remove blocos de pensamento anteriores:

• Remoção de blocos de pensamento: Em modelos que removem blocos de pensamento anteriores, os blocos de pensamento (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 por conta própria: se você os passar de volta, a API do Claude os remove automaticamente.
• Cobrança: Tokens de pensamento são cobrados como tokens de saída uma vez, quando são gerados. Em modelos que mantêm blocos de pensamento anteriores, os blocos mantidos passam então a fazer parte da entrada de requisições posteriores e são cobrados como tokens de entrada, como o restante do histórico da conversa.



A janela de contexto com pensamento e uso de ferramentas

O diagrama a seguir ilustra como os tokens são gerenciados quando você combina pensamento com uso de ferramentas em um modelo que remove blocos de pensamento anteriores:

• Considerações para uso de ferramentas com pensamento:
  • Quando você publica resultados de ferramentas, deve incluir o bloco de pensamento inteiro e não modificado que acompanha aquela requisição de ferramenta, incluindo sua assinatura.
  • A API usa assinaturas criptográficas para verificar a autenticidade dos blocos de pensamento. Se você modificar um bloco de pensamento, a API retorna um erro.

Para reduzir o contexto consumido pelas próprias definições de ferramentas, consulte Gerenciar contexto de ferramentas, ou adie as definições de ferramentas com a ferramenta de busca de ferramentas.



Consciência de contexto

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5 têm consciência de contexto: esses modelos rastreiam sua janela de contexto restante (seu "orçamento de tokens") ao longo de uma conversa. Isso permite que o modelo gerencie tarefas de longa duração com base no espaço que resta, em vez de adivinhar quantos tokens restam. A consciência de contexto é automática: não há nada para você habilitar, e você nunca envia as tags mostradas nesta seção por conta própria. A API as injeta.



Como funciona

No prompt do sistema de cada requisição, a API informa a Claude sua janela de contexto total:

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

O orçamento corresponde à janela de contexto disponível para sua requisição: 1M de tokens para Claude Sonnet 5 e Claude Sonnet 4.6, e 200k tokens para Claude Sonnet 4.5 e Claude Haiku 4.5. Os exemplos nesta seção mostram um modelo com uma janela de contexto de 200k tokens.

Após cada chamada de ferramenta, a API dá a Claude uma atualização sobre sua capacidade restante:

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

Tokens de imagem estão incluídos nesses orçamentos.

Claude Opus 4.7 e modelos Opus posteriores, Claude Fable 5 e Claude Mythos 5 não recebem essas tags injetadas. No Claude Opus 4.7 e modelos Opus posteriores, Claude Fable 5 e Claude Mythos 5, você pode dar ao modelo um orçamento explícito com orçamentos de tarefa, que estão em beta.

Para orientações de prompting sobre o uso da consciência de contexto, consulte Melhores práticas de prompting.



Gerencie o contexto com compactação

Se suas conversas se aproximam regularmente dos limites da janela de contexto, use a compactação no lado do servidor. A compactação resume automaticamente partes anteriores da conversa no servidor, para que a conversa possa continuar além do limite da janela de contexto. Está disponível em beta para modelos Claude 4.6 e posteriores e para o Claude Mythos Preview.

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

• Limpeza de resultados de ferramentas: Limpe resultados antigos de ferramentas em fluxos de trabalho agênticos
• Limpeza de blocos de pensamento: Gerencie blocos de pensamento quando você usa pensamento estendido

Prefixos de prompt em cache ainda ocupam a janela de contexto: o cache de prompt muda o que você paga por esses tokens, não se eles contam.



Comportamento de estouro da janela de contexto

Se a entrada sozinha já exceder a janela de contexto do modelo, a API retorna um erro 400 invalid_request_error ("prompt is too long") em todos os modelos.

Em modelos Claude 4.5 e mais recentes, se os tokens de entrada mais max_tokens excederem o tamanho da janela de contexto, a API aceita a requisição. Se a geração então atingir o limite da janela de contexto, ela para com stop_reason: "model_context_window_exceeded". Em modelos anteriores, a API retorna um erro de validação em vez disso. Para optar pelo comportamento model_context_window_exceeded nesses modelos, use o cabeçalho beta model-context-window-exceeded-2025-08-26. Consulte Razões de parada e fallback para detalhes.

Para permanecer dentro dos limites da janela de contexto, use a API de contagem de tokens para estimar o uso de tokens antes de enviar mensagens para Claude.



Próximos passos