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 do lado do servidor é a principal estratégia 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 consultar ao gerar uma resposta, incluindo a própria resposta. 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, 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 esquema "primeiro a entrar, primeiro a sair".

• Acúmulo progressivo de tokens: À medida que a conversa avança pelos 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 o Claude gera.
• Fluxo de entrada e saída: Cada turno consiste em:
  • Fase de entrada: Contém todo o histórico anterior da conversa 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 o Claude gera para o turno, incluindo seu pensamento estendido, também conta. Cada resposta informa 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 da janela de contexto por modelo

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 e Claude Mythos Preview têm uma janela de contexto de 1M de tokens. Uma única requisição para qualquer um deles 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 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 pelo preço padrão.

Uma única requisição pode incluir até 600 imagens ou páginas de PDF (100 para modelos com janela de contexto de 200k tokens). Se você enviar muitas imagens ou documentos grandes, poderá 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.

Os 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, o Claude determina sua alocação de pensamento dinamicamente, portanto 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.1, Claude Mythos 5.1, 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 envia 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 enviar de volta, a API do Claude os remove automaticamente.
• Cobrança: Os 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 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 "tool use" (uso de ferramentas) em um modelo que remove blocos de pensamento anteriores:

1. 1

   Arquitetura do primeiro turno

   • Componentes de entrada: Configuração de ferramentas e mensagem do usuário
   • Componentes de saída: Pensamento + resposta de texto + solicitação de uso de ferramenta
   • Cálculo de tokens: Todos os componentes de entrada e saída contam para a janela de contexto, e todos os componentes de saída são cobrados como tokens de saída.
2. 2

   Tratamento do resultado da ferramenta (turno 2)

   • Componentes de entrada: Todos os blocos do primeiro turno e o tool_result. Você deve retornar o bloco de pensamento com os resultados de ferramenta correspondentes. Este é o único caso em que você precisa retornar blocos de pensamento.
   • Componentes de saída: Depois que os resultados de ferramentas são enviados de volta ao Claude, o Claude responde apenas com texto (sem pensamento adicional até a próxima mensagem user, a menos que o pensamento intercalado esteja habilitado).
   • Cálculo de tokens: Todos os componentes de entrada e saída contam para a janela de contexto, e todos os componentes de saída são cobrados como tokens de saída.
3. 3

   Novo turno do usuário (turno 3)

   • Componentes de entrada: Todas as entradas e a saída do turno anterior são levadas adiante. O bloco de pensamento do ciclo de uso de ferramentas concluído não precisa mais permanecer no contexto: em modelos que removem blocos de pensamento anteriores, a API o descarta automaticamente quando você o envia de volta, e em modelos que mantêm blocos de pensamento anteriores, ele permanece a menos que você o limpe com a limpeza de blocos de pensamento. É também aqui que você adiciona o próximo turno user.
   • Componentes de saída: Como há um novo turno user fora do ciclo de uso de ferramentas, o Claude gera um novo bloco de pensamento e continua a partir daí.
   • Cálculo de tokens: Em modelos que removem blocos de pensamento anteriores, os tokens de pensamento anteriores não contam mais para a janela de contexto. Todos os outros blocos anteriores ainda contam para a janela de contexto, assim como o bloco de pensamento no turno assistant atual.

• Considerações para uso de ferramentas com pensamento:
  • Ao enviar resultados de ferramentas, você deve incluir o bloco de pensamento inteiro e não modificado que acompanha aquela solicitaçã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 acompanham 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 sobraram. A consciência de contexto é automática: não há nada para você habilitar, e você nunca envia por conta própria as tags mostradas nesta seção. A API as injeta.

Como funciona

No prompt do sistema de cada requisição, a API informa ao 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 janela de contexto de 200k tokens.

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

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

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

O Claude Opus 4.7 e modelos Opus posteriores, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 e Claude Mythos 5 não recebem essas tags injetadas. Nesses modelos, você pode dar ao modelo um orçamento explícito com os 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.

Gerenciar contexto com compactação

Se suas conversas se aproximam regularmente dos limites da janela de contexto, use a compactação do lado do servidor. A compactação resume automaticamente as partes anteriores da conversa no servidor, para que a conversa possa continuar além do limite da janela de contexto. Ela 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 de ferramentas antigos 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.

Nos 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. Para optar pelo comportamento model_context_window_exceeded nesses modelos, use o cabeçalho beta model-context-window-exceeded-2025-08-26. Consulte Motivos 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 ao Claude.

Próximos passos