Um agente de IA em produção, rajadas de network_error em cadeia e um mecanismo invisível: o cache de prefixo do provedor morria em 2 minutos.
Este é um post-mortem real de produção, com a calibração medida em A/B e o resultado no settings.yaml. O tipo de diagnóstico que só existe quando o harness é seu.
O sintoma: a cadeia de retries
O quadro inicial: rajadas de network_error logo depois de chamadas de leitura de imagem que devolviam arquivos grandes. A ferramenta demorava, a chamada seguinte falhava, o retry falhava de novo, em cadeia.
O instinto é culpar o gateway instável. O instinto erra o alvo: a falha seguinte era consequência do intervalo anterior, não da instabilidade em si.
O mecanismo: TTL de 2 minutos estourado
A investigação isolou o mecanismo: o cache de prefixo do provedor expira com cerca de 2 minutos sem requisição. A ferramenta longa (leitura de imagem grande) estourava o TTL, o cache morria, e cada retry reenviava o contexto inteiro: 40 mil tokens de texto mais 1 MB de imagens acumuladas.
Upload frio desse tamanho sobre um gateway instável é a rajada inteira explicada. O nome do mecanismo, invalidação de prefixo, é o que transforma o resto em engenharia comum: com a causa nomeada, a correção vira classificação de erro mais calibração medida.
A correção, em duas frentes
No código: gateways sintetizam finish_reason, e esses erros entravam como falha fatal. Remapeei como transporte recuperável, com suíte de testes, e o trabalho virou branch de contribuição para o mainstream do harness.
Na configuração: calibração medida em A/B, cada valor com racional registrado no settings.yaml:
- Teto de 6 MiB por requisição de imagem: rajadas 76% menores, pico 82% menor.
- Timeout de stream em 60 segundos, porque 30 inflava repetições.
- 100 retries com backoff de 750 milissegundos, limitando o pior caso a menos de 2 horas.
E a regra operacional que fecha o desenho: estourou o teto de retries, aborta e compacta o contexto. Resultado: 62 retries por dia absorvidos automaticamente, zero turnos perdidos, com o modelo rodando a janela inteira.
Por que isso exige harness aberto
O mesmo harness atende a nuvem e ao meu data center próprio (DGX H200 servindo GLM via NIM), e o debug foi possível porque o harness é meu: descer até o mecanismo de invalidação de prefixo e corrigir com testes não caberia em um chamado de suporte.
Harness fechado transformaria esse diagnóstico em ticket sem prazo, e provavelmente sem solução: o provedor do cache não é o dono do agente, e o dono do agente não vê o TTL. Harness aberto transforma diagnóstico em correção com testes, e é por isso que a camada de orquestração própria vale o preço.
Conclusão
O mesmo post-mortem ensina três lições: cache de prefixo é recurso vivo que morre no silêncio entre chamadas; falhas de transporte e falhas fatais precisam de classificação diferente; e calibração sem A/B medido é chutagem com arquivo.
Quem roda agentes em produção vai encontrar esse padrão (ou seu primo) mais cedo ou mais tarde. A diferença entre 2 horas de pior caso e um turno perdido é o harness que você controla. Modelo é commodity; a operação que o serve é o produto.