Entendendo Por Que Agentes Claude Falham em Produção
Um aplicativo Claude que funciona perfeitamente em uma demonstração ainda pode falhar em produção de maneiras que nunca aparecem em testes locais.
//
Busque em todas as páginas da documentação
Um aplicativo Claude que funciona perfeitamente em uma demonstração ainda pode falhar em produção de maneiras que nunca aparecem em testes locais.
O código está correto, o prompt está bem escrito e o caminho feliz é executado de forma limpa toda vez que você o testa manualmente.
Então, ele é lançado, o tráfego real chega e uma nova categoria de falha aparece: não um bug de lógica, mas um modo de falha de produção.
Esta página é um mapa desses modos de falha.
Ela não se aprofunda em nenhum deles individualmente; cada um tem seu próprio artigo dedicado mais adiante nesta seção, mas fornece o modelo mental para reconhecer qual falha você está observando antes de começar a depurar.
Um modo de falha é um padrão recorrente em como um sistema quebra, em oposição a um bug pontual.
Aplicações web tradicionais têm modos de falha bem conhecidos: esgotamento de conexões de banco de dados, consultas N+1, carimbos de cache (cache stampedes).
Aplicativos Claude têm os seus próprios, moldados pelo fato de que uma chamada de rede para uma API de modelo de linguagem está no caminho crítico de quase todas as requisições.
Quatro famílias de modos de falha cobrem quase tudo o que dá errado em um aplicativo Claude em produção.
Falhas de capacidade ocorrem quando seu tráfego excede o que a API, ou a cota da sua própria conta, está disposta a servir no momento.
A assinatura é um código de status 429, e a causa subjacente é ou um limite real de taxa ou um surto de requisições concorrentes que excede sua taxa de transferência configurada.
Falhas de contrato ocorrem quando a saída do modelo não corresponde ao formato que seu código espera.
O exemplo mais comum é uma chamada de uso de ferramenta onde os argumentos não são JSON válido, ou não correspondem ao esquema da ferramenta, porque o modelo produziu uma resposta plausível, mas ligeiramente malformada.
Falhas de ciclo de vida ocorrem quando uma requisição ou uma conversa sobrevive aos recursos alocados para ela.
Uma conversa que cresce além da janela de contexto do modelo, ou uma conexão de streaming que cai no meio da resposta, são ambas falhas de ciclo de vida: algo que estava bem no início tornou-se inválido no meio do caminho.
Falhas de custo e latência são as silenciosas.
Nada dá erro, mas uma tempestade de cache miss pode dobrar seus gastos com tokens e seus tempos de resposta sem que uma única requisição falhe diretamente, então ninguém percebe até que a fatura ou o painel de latência os informe.
Uma maneira simples de manter essas quatro em mente:
Capacidade -> "não há espaço para esta requisição agora"
Contrato -> "a resposta não corresponde ao que combinamos"
Ciclo de Vida -> "isso sobreviveu aos recursos com os quais começou"
Custo/Latência -> "tudo deu certo, mas ficou mais lento ou mais caro"Essas famílias de falhas não existem isoladamente; elas interagem, e as interações são frequentemente onde os incidentes se tornam confusos.
Uma falha de capacidade sob carga frequentemente aciona um loop de retentativa mal projetado, que então se parece com uma falha de ciclo de vida porque as requisições começam a expirar downstream.
Uma falha de contrato em JSON de uso de ferramenta, se ignorada silenciosamente em vez de registrada, pode corromper silenciosamente o estado interno de um agente, o que mais tarde surge como um erro totalmente diferente vários turnos depois.
Uma tempestade de cache miss pode coincidir com uma falha de capacidade, porque os tokens extras não cacheados empurram uma requisição para um limite de taxa que, de outra forma, ela teria permanecido abaixo.
É por isso que o primeiro passo em qualquer incidente deve ser a classificação, não a correção.
Pergunte: isso é um problema de capacidade, um problema de contrato, um problema de ciclo de vida ou um problema de custo/latência?
A resposta determina qual playbook se aplica, e classificar incorretamente uma falha de capacidade como um bug de código (ou vice-versa) é uma das maneiras mais comuns de incidentes se arrastarem mais do que o necessário.
Cada família também tem um raio de explosão diferente, o escopo do que quebra quando a falha ocorre.
Uma única chamada de ferramenta malformada pode corromper uma conversa.
Uma violação do limite de taxa durante um pico de tráfego pode degradar todos os usuários concorrentes simultaneamente.
# Uma forma mínima para marcar um erro com sua família de falha
# no ponto em que é capturado, para que o registro e o alerta downstream
# possam roteá-lo corretamente em vez de tratar cada exceção da mesma forma.
class ClaudeFailure(Exception):
def __init__(self, family: str, detail: str):
# family é um de: "capacity", "contract", "lifecycle", "cost_latency"
self.family = family
super().__init__(detail)Marcar falhas dessa forma no ponto de captura, em vez de depois do fato durante uma RCA, é o que torna os painéis e alertas genuinamente úteis em vez de apenas uma parede de 500s indiferenciados.
Em escala, essas famílias de falhas se compõem de maneiras previsíveis que valem a pena projetar antecipadamente em vez de descobrir durante um incidente.
Falhas de capacidade tendem a se agrupar no tempo; um surto de tráfego não chega uniformemente, então um sistema que lida bem com a carga média ainda pode ser atingido por uma tempestade de 429 durante um pico.
Falhas de contrato tendem a se agrupar por versão de prompt; uma única mudança de prompt que torna os argumentos da chamada de ferramenta ligeiramente mais ambíguos pode aumentar silenciosamente a taxa de JSON malformado em todas as requisições que usam esse prompt, não apenas em uma.
Falhas de ciclo de vida tendem a se agrupar por comprimento de conversa; a falha só aparece depois que uma sessão está em execução há tempo suficiente para se aproximar da janela de contexto ou acionar uma conexão de streaming de longa duração, então ela é frequentemente invisível em conversas de teste curtas.
Falhas de custo e latência tendem a se agrupar por implantação; uma mudança de modelo de prompt que parece inofensiva em um diff pode alterar uma chave de cache o suficiente para transformar um prefixo estável e barato em um que falha constantemente.
| Família de Falha | Sinal Típico | Onde é Coberto |
|---|---|---|
| Capacidade | Respostas 429 repetidas, profundidade crescente da fila | Diagnóstico de 429s, Retentativa e Backoff |
| Contrato | Erros de decodificação JSON, falhas de validação de esquema | JSON Malformado de Uso de Ferramenta |
| Ciclo de Vida | Contexto truncado, stream interrompido no meio da resposta | Estouro de Contexto e Checklist de Streaming |
| Custo/Latência | Aumento de gastos com tokens ou latência p95 sem pico de erros | Tempestades de Cache Miss de Prompt |
Entender a qual família um sintoma pertence também molda como você escreve seu relatório de incidente posteriormente.
Uma RCA que diz "a API falhou" é muito menos útil do que uma que diz "esta foi uma falha de capacidade causada por um padrão de surto que nossa estratégia de backoff não previu", porque a segunda versão aponta diretamente para o que precisa mudar.
"Um 429 significa que algo está quebrado." - Um 429 geralmente significa que o sistema está funcionando como projetado e dizendo que você excedeu um limite de taxa ou cota; a correção está na sua forma de tráfego e estratégia de retentativa, não em encontrar um bug.
"JSON malformado de uso de ferramenta é raro demais para ser ignorado." - É incomum por requisição, mas em volume de produção significativo, acontece com frequência suficiente que falhas de análise não tratadas eventualmente derrubarão uma conversa real se você não planejar para isso.
"Estouro de contexto só importa para conversas muito longas." - Importa no momento em que seu contexto acumulado, incluindo resultados de ferramentas e prompts do sistema, se aproxima da janela do modelo, o que pode acontecer surpreendentemente rápido em loops de agente que anexam a saída da ferramenta a cada turno.
"Se nada está dando erro, o sistema está saudável." - Tempestades de cache miss e latência crescente são falhas de custo e desempenho que produzem zero respostas de erro, que é exatamente por que elas passam despercebidas até que alguém verifique a conta.
"Retentar de forma mais agressiva corrige falhas de capacidade." - Retentativas ingênuas sob uma falha de capacidade pioram o problema adicionando mais carga a um teto já saturado; a correção é backoff e jitter, não persistência.
Pode ser ambos, e descobrir qual é parte do diagnóstico. Um timeout causado pela API estar saturada sob carga é uma falha de capacidade. Um timeout causado por uma requisição que cresceu demais ou uma conexão que sobreviveu à sua duração esperada é uma falha de ciclo de vida.
Os formatos gerais (capacidade, contrato, ciclo de vida, custo/latência) se aplicam amplamente a qualquer integração LLM em produção. Os detalhes nesta seção, assinaturas de limite de taxa, formato JSON de uso de ferramenta, mecânicas de cache de prompt, são escritos contra a API Claude e o SDK Python anthropic.
Sim. Uma mudança no modelo de prompt é um exemplo comum: ela pode simultaneamente aumentar a contagem de tokens (contribuindo para o risco de estouro de contexto), alterar a chave de cache (desencadeando uma tempestade de cache miss) e tornar os argumentos da chamada de ferramenta mais ambíguos (aumentando as falhas de contrato).
Antes, se possível. Marcar erros por família no ponto de captura (como mostrado no trecho de código acima) custa muito pouco para configurar e compensa na primeira vez que você precisar triar um pico rapidamente em vez de ler rastros de pilha brutos.
Se uma resposta malformada de uso de ferramenta for capturada, mas não registrada ou reparada adequadamente, o estado interno do agente pode se desviar do que realmente aconteceu, e o sintoma visível (uma resposta errada, um loop travado) geralmente aparece vários turnos após a causa raiz real.
Não, retentar é a resposta correta, mas apenas quando é uma retentativa adequadamente projetada: backoff exponencial com jitter, não um loop de retentativa imediato ou de intervalo fixo. A distinção é abordada em profundidade no artigo sobre retentativa e backoff.
429 quase sempre significa capacidade.Falhas de capacidade e contrato se aplicam igualmente a chamadas de requisição única. Falhas de ciclo de vida (estouro de contexto, desconexões de streaming) são mais comuns em agentes multi-turn e streams de longa duração, mas uma única requisição muito grande ainda pode desencadear uma falha de ciclo de vida por si só.
Esta página é o mapa conceitual. Cada família se conecta a um artigo dedicado: falhas de capacidade aos artigos de diagnóstico de 429 e retentativa/backoff, falhas de contrato ao artigo de JSON malformado de uso de ferramenta, falhas de ciclo de vida ao artigo de estouro de contexto e checklist de streaming, e falhas de custo/latência aos artigos de tempestades de cache miss de prompt.
Versões de Stack: 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
anthropicpara 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.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026