Transbordamento de Contexto e Desconexões de Streaming: Um Checklist de Prevenção

Ambas as falhas compartilham uma causa raiz: algo que estava bem no início de uma solicitação sobreviveu aos recursos alocados para ele. Uma conversa cresce além da janela de contexto do modelo, ou uma conexão de streaming cai no meio da resposta. Este checklist cobre as etapas concretas para prevenir ambos e para se recuperar de forma limpa quando a prevenção não for suficiente.

Como Usar Este Checklist

Trabalhe através dos dois níveis em ordem: gerenciamento de contexto primeiro, resiliência de streaming em segundo, eles se acumulam em loops de agente que transmitem longas conversas de uso de ferramentas.
Trate os itens 1-4 como obrigatórios para qualquer integração Claude multi-turno ou de agente; os itens 5-8 se aplicam assim que você confirmar que o contexto está sob controle.
Os itens 9-14 se aplicam especificamente a qualquer código que use a API de streaming do SDK; pule-os se você usar apenas chamadas não-streaming.
Revise este checklist sempre que adicionar uma nova ferramenta a um loop de agente, pois os resultados das ferramentas são uma fonte comum de crescimento não planejado do contexto.
Registre a contagem de tokens e a contagem de turnos em que qualquer falha ocorreu, esse número lhe diz quanta margem você realmente precisa aparar.

Prevenção de Transbordamento de Contexto (1-8)

Conheça a janela de contexto real do seu modelo antes de construir contra ela. Procure a janela de contexto atual para o modelo específico que você está chamando, não assuma que ela corresponde ao limite de um modelo mais antigo de memória.
Conte os tokens por turno, não apenas por solicitação. Use a contagem de tokens do SDK para medir o total em execução de uma conversa após cada turno, não apenas o tamanho da mensagem mais recente.
Defina um limite de corte bem abaixo do limite rígido. Reserve margem, comumente 15-25% da janela, para a própria resposta do modelo e quaisquer resultados de ferramentas que ainda virão no mesmo turno.
Resuma ou descarte os turnos mais antigos antes de truncar no meio da mensagem. Truncar uma mensagem no meio pode deixar um bloco tool_use sem seu tool_result correspondente, o que a API rejeitará completamente.
Limite o tamanho do resultado da ferramenta antes que ele reentre no contexto. Uma ferramenta que pode retornar uma quantidade ilimitada de dados (um arquivo completo, um grande resultado de consulta) precisa de sua própria truncagem ou sumarização antes de ser anexada de volta à conversa.
Persista o histórico completo fora da janela de contexto, não dentro dela. Mantenha uma transcrição completa em seu próprio armazenamento e alimente o modelo apenas com uma janela de trabalho aparada, para que o aparamento para a API nunca signifique perder dados para seus próprios logs ou uma revisão humana posterior.
Teste com uma conversa longa o suficiente para realmente atingir seu limite de corte. Uma conversa de teste curta nunca exercitará a lógica de corte; construa deliberadamente uma longa em um teste para confirmar que o limite é acionado corretamente.
Alerta sobre limites de contexto se aproximando, não apenas sobre transbordamento. Um aviso em 80% do seu limite de corte lhe dá tempo para investigar uma conversa que está crescendo incomumente rápido, antes que ela falhe de fato.

Recuperação de Desconexões de Streaming (9-14)

Rastreie a saída parcial à medida que ela é transmitida, não apenas na conclusão. Armazene em buffer os deltas de texto à medida que eles chegam, para que uma desconexão no meio do stream deixe você com o que já foi gerado, não nada.
Diferencie um fim de stream limpo de uma conexão interrompida. Um stream que termina com um evento message_stop adequado foi bem-sucedido; um stream que levanta um erro de conexão no meio não o fez, e precisa de um tratamento diferente.
Defina uma política de reconexão para streams interrompidos, usando a mesma disciplina de backoff de qualquer outra falha transitória. Uma nova tentativa bruta em um stream interrompido deve seguir a mesma abordagem de backoff com jitter de qualquer outra falha transitória da API Claude, não um loop ad hoc separado.
Decida antecipadamente se uma reconexão retoma ou reinicia. A API Messages não retoma uma resposta parcialmente transmitida de onde parou; uma reconexão emite uma nova solicitação, portanto, decida se deve reenviar o prompt completo ou continuar a partir da saída parcial que você já armazenou em buffer.
Divida saídas grandes para o consumidor, independentemente de como o modelo as transmite. Se o seu próprio consumidor downstream (uma interface de usuário, outro serviço) não puder lidar com um stream ilimitado, divida o que você encaminha para ele, independentemente de como o Claude entrega os tokens.
Registre a contagem de bytes/tokens realmente entregue antes de uma desconexão. Esse número é o que lhe diz, após o fato, se o leitor viu uma resposta quase completa ou quase nada, o que muda se a recuperação correta é "apenas mostre o que temos" ou "reinicie limpo".

import anthropic
 
client = anthropic.Anthropic()
 
def stream_with_recovery(prompt: str) -> str:
    collected = ""
    try:
        with client.messages.stream(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}],
        ) as stream:
            for text in stream.text_stream:
                collected += text
        return collected
    except anthropic.APIConnectionError:
        # A saída parcial é preservada em `collected` mesmo que o
        # stream tenha caído; o chamador decide se deve mostrá-la ou tentar novamente.
        return collected

Aplicando o Checklist em Ordem

Os itens de contexto (1-8) vêm primeiro porque um contexto transbordando pode, por si só, fazer com que uma resposta transmitida seja cortada no meio da geração, uma falha de ciclo de vida disfarçada de falha de streaming.
Os itens de streaming (9-14) assumem que o contexto já está sob controle, portanto, uma desconexão que você está depurando é genuinamente um problema de conexão, não um sintoma de uma solicitação excessivamente grande.
Revise ambos os níveis juntos após qualquer alteração nas definições de ferramentas, pois novas ferramentas são a fonte mais comum de crescimento de contexto e de saídas transmitidas maiores.

Armadilhas

Aparar no meio da mensagem em vez de no meio do turno. Cortar uma mensagem no meio de um par tool_use/tool_result produz uma conversa inválida que a API rejeitará. Sempre apare nos limites do turno.
Assumir que um stream interrompido pode continuar de onde parou. Não pode; uma reconexão é uma nova solicitação, e seu código precisa decidir explicitamente se reinicia ou continua a partir da saída parcial em buffer.
Não alertar até a falha rígida. Esperar por um erro real de transbordamento de contexto para notar que uma conversa está crescendo muito grande significa que você descobre a partir de uma falha voltada para o usuário, não de um painel.

FAQs

Quanta margem devo reservar abaixo do limite de contexto rígido?

Um ponto de partida comum é 15-25% da janela, o suficiente para cobrir a própria resposta do modelo mais quaisquer resultados de ferramentas ainda esperados no mesmo turno. Ajuste isso com base em quão grandes são seus resultados de ferramentas típicos.

Por que não posso simplesmente truncar a mensagem mais antiga quando uma conversa fica longa?

Se a mensagem truncada for um bloco tool_use, seu tool_result correspondente mais adiante na conversa fica órfão, e a API rejeitará a sequência de mensagens resultante. Apare turnos inteiros, não fragmentos de mensagens arbitrários.

A API Claude suporta a retomada de um stream interrompido de onde parou?

Não. Uma reconexão após um stream interrompido é uma nova solicitação. Seu código precisa decidir explicitamente se reenviará o prompt original ou continuará a conversa usando qualquer saída parcial que você já armazenou em buffer.

Devo persistir o histórico completo da conversa mesmo que eu apare o que envio para o modelo?

Sim. Mantenha a transcrição completa em seu próprio armazenamento e envie apenas uma janela de trabalho aparada para a API. Dessa forma, o aparamento por motivos de janela de contexto nunca significa perder dados para seus próprios logs, auditorias ou uma revisão humana posterior.

Qual é a diferença entre um stream terminando limpo e um stream se desconectando?

Um fim limpo entrega um evento de parada adequado após o modelo terminar de gerar. Uma desconexão levanta um erro de conexão no meio, antes que esse evento de parada chegue, e precisa de tratamento de recuperação explícito em vez de ser tratado como uma conclusão normal.

Como sei se uma ferramenta corre o risco de causar transbordamento de contexto?

Qualquer ferramenta cuja saída não tenha tamanho limitado, uma leitura de arquivo, um conjunto de resultados de pesquisa, uma consulta de banco de dados, é um candidato. Limite ou resuma sua saída antes que ela seja anexada de volta à conversa, em vez de assumir que ela sempre será pequena.

Reconectar a um stream interrompido é o mesmo que tentar novamente uma chamada não-streaming com falha?

A disciplina de backoff deve ser a mesma (backoff exponencial com jitter), mas a decisão do que enviar na reconexão é diferente: uma nova tentativa não-streaming geralmente reenvia a mesma solicitação inalterada, enquanto uma reconexão de stream precisa decidir se reenviará o prompt completo ou continuará a partir da saída parcial.

Devo alertar apenas quando o transbordamento de contexto realmente acontece, ou antes?

Mais cedo. Alerte em um limite abaixo do seu ponto de corte (por exemplo, 80% dele) para que você tenha tempo de investigar por que uma conversa específica está crescendo incomumente rápido, em vez de descobrir apenas quando o corte ou uma falha direta já ocorreu.

Como testo se minha lógica de corte realmente funciona?

Construa deliberadamente uma longa conversa de teste que exceda seu limite de corte e afirme que o corte é acionado no ponto esperado. Uma conversa curta em uma suíte de teste típica nunca exercitará esse caminho.

O chunking de saída para minha própria interface de usuário importa se o Claude já transmite token por token?

Sim, são preocupações independentes. O streaming em nível de token do Claude não garante que seu consumidor downstream, um navegador, um cliente móvel, outro serviço, possa lidar com um stream ilimitado ou não dividido; divida o que você encaminha com base no que esse consumidor realmente precisa.

O que devo registrar quando um stream se desconecta no meio?

A quantidade de saída já entregue (contagem de tokens ou bytes) antes da desconexão. Esse número diz se o usuário viu uma resposta quase completa que vale a pena manter, ou quase nada, o que muda se a recuperação correta é mostrar a saída parcial ou descartá-la e tentar novamente.

O transbordamento de contexto é mais provável em loops de uso de ferramentas de agente do que em chat simples?

Sim. Cada chamada de ferramenta e seu resultado adicionam ao contexto em execução, e os loops de agente frequentemente executam muitas voltas seguidas sem uma pausa natural, então o contexto pode crescer mais rápido e de forma menos previsível do que em um chat direto de ida e volta.

Relacionados

Entendendo Por Que Agentes Claude Falham em Produção - onde as falhas de ciclo de vida se encaixam na taxonomia mais ampla de falhas.
Noções Básicas de Solução de Problemas e Confiabilidade - a base de logging que este checklist assume que já está em vigor.
Estratégias de Retentativa e Backoff Exponencial para Falhas Transitórias da API Claude - a disciplina de backoff a ser aplicada ao reconectar um stream interrompido.
Tempestades de Perda de Cache de Prompt: Diagnosticando Picos Súbitos de Custo e Latência - como as escolhas de corte de contexto também podem afetar a estabilidade do cache.
Melhores Práticas de Solução de Problemas e Confiabilidade - onde este checklist se encaixa no conjunto mais amplo de práticas.

Versões da Pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.