# Como reproduzir uma falha de agente de programação entre versões de modelos? > Reproduza uma falha de agente de programação capturando toda a execução como um fixture versionado e repetindo o mesmo prompt, commit, contrato de ferramentas, ambiente e regras de parada com IDs de modelo fixos. Compare eventos estruturados e o estado final do repositório, não apenas o texto do assistente. # Como reproduzir uma falha de agente de programação entre versões de modelos? Uma reprodução útil é um experimento executável, não uma transcrição copiada. Comece no estado em que o repositório falhou, congele toda entrada visível ao agente e defina uma asserção verificável por máquina. Depois, repita o fixture várias vezes com versões fixas do modelo. Uma execução combina comportamento do modelo, ferramentas, arquivos, rede, orquestração e tempo. Se qualquer parte mudar, um resultado diferente não prova que o modelo causou ou corrigiu o problema. ## Defina a falha como uma asserção Escreva a menor condição observável que separa falha de sucesso. Pode ser um teste ainda vermelho, arquivo alterado indevidamente, comando proibido, migração ausente ou patch que compila mas muda o comportamento. Evite critérios como “a resposta parece pior”. Para uma correção, a aceitação pode exigir: * o teste de regressão original passa; * todos os testes existentes continuam passando; * nenhum arquivo fora da lista permitida muda; * o agente para dentro de um número fixo de chamadas; * o diff final não contém segredos nem alteração acidental de lockfile. ## Capture o envelope completo da execução O prompt é apenas uma entrada. Guarde com o fixture: | Camada | O que congelar | Por que muda o resultado | |---|---|---| | Repositório | Commit, submódulos, patch sujo e arquivos não rastreados | O agente raciocina sobre esse código exato | | Instruções | Prompt de sistema, regras e tarefa | Pequenas mudanças alteram o plano | | Modelo | Provedor, ID imutável e parâmetros | Aliases e padrões podem mudar | | Ferramentas | Nomes, schemas JSON, permissões e timeouts | As capacidades moldam o plano | | Ambiente | Imagem, SO, arquitetura e lockfiles | Comandos e testes podem variar | | Dados externos | HTTP simulado, relógio e aleatoriedade | Serviços vivos introduzem deriva | | Orquestrador | Limite de loops, tentativas e compactação | O modelo pode receber históricos diferentes | Remova segredos, mas preserve se a credencial existia e seu escopo. ## Registre eventos estruturados, não apenas texto Armazene cada solicitação e resposta do modelo, chamada e resultado de ferramenta, tentativa e decisão de parada como eventos ordenados. Para saídas grandes, adicione hash e guarde o artefato separadamente. ```json { "run_id": "agent-regression-042", "fixture": "sha256:...", "model": "provider/model-version", "event": "tool_result", "tool": "run_tests", "exit_code": 1, "stdout_sha256": "..." } ``` Isso mostra se o novo modelo escolheu outra ferramenta, interpretou o erro de outra forma ou recebeu evidência diferente. ## Fixe versões e elimine variação ao vivo Use identificadores datados ou imutáveis quando disponíveis. Não compare uma falha histórica com `latest`, pois ele pode apontar para outra compilação. Execute em contêiner ou VM limpa. Substitua buscas e índices de pacotes mutáveis por respostas gravadas ou snapshots internos. Congele o relógio quando a data importar. Se a rede for necessária, registre respostas e marque o teste como parcialmente controlado. Uma semente ajuda, mas não congela inferência distribuída, tempo das ferramentas ou mudanças do provedor. ## Repita uma matriz, não apenas um par Uma execução por versão não separa regressão de variação. Mantenha o fixture fixo: | Versão do modelo | Repetições | Taxa de aprovação | Mediana de chamadas | Assinatura da falha | |---|---:|---:|---:|---| | ID base fixo | 5 | 4/5 | 9 | Ignorou teste de borda | | ID candidato fixo | 5 | 1/5 | 13 | Editou arquivo gerado | | Candidato com prompt antigo | 5 | 1/5 | 12 | Mesma assinatura | Cinco repetições são um bom começo. Amplie para falhas intermitentes ou críticas. Mantenha temperature e outros controles iguais, salvo quando forem o objeto do teste. ## Compare decisões e estado do repositório Compare separadamente: * eventos normalizados do modelo e das ferramentas; * comandos e códigos de saída; * árvore final e patch; * testes de aceitação e recursos. Não exija raciocínio textual idêntico. Caminhos diferentes podem produzir patches equivalentes, e textos parecidos podem esconder comandos materialmente distintos. ## Minimize o fixture após reproduzir Quando a falha se repetir, remova um por vez arquivos, ferramentas, parágrafos e chamadas externas irrelevantes. Um fixture pequeno executa mais rápido e mostra melhor o limite causal. Mantenha o replay completo para auditoria e o caso mínimo para avaliação contínua. Adicione o caso mínimo à validação de upgrades de modelo. ## Use um adaptador de modelo portátil Um gateway como Atlas Cloud pode colocar vários modelos atrás de um cliente compatível com OpenAI, mas compatibilidade não significa comportamento idêntico. Guarde IDs e opções no adaptador; o harness comum deve controlar fixtures, eventos, tentativas e asserções. Assim, a mesma reprodução roda entre provedores sem reescrever a avaliação. ## Em resumo Congele o envelope da execução, repita modelos fixos e julgue resultados executáveis. Se não puder reproduzir todo o incidente, declare quais entradas continuam vivas e trate o resultado como comparação, não como prova de regressão. ## FAQ ### O que deve ser capturado para reproduzir uma falha de agente? Capture o commit e o patch não confirmado, prompts e instruções, ID e parâmetros do modelo, schemas e resultados das ferramentas, imagem do ambiente, lockfiles, política de credenciais, rede e a asserção exata de sucesso. ### Devo repetir a falha com um alias de modelo latest? Não. Use IDs imutáveis ou datados. Um alias latest pode mudar durante o teste e impedir a atribuição correta de sucesso ou falha. ### Por que uma semente aleatória fixa não é suficiente? A semente não congela a infraestrutura do provedor, o tempo das ferramentas, resultados de recuperação nem revisões do modelo. É apenas um controle, não uma garantia de determinismo. ### Qual é o melhor sinal de aprovação para um agente de programação? Prefira asserções executáveis, como testes, lint, diffs esperados, arquivos proibidos e códigos de saída. Similaridade textual costuma ser fraca demais para tarefas de código. ### Quantas repetições devo executar por versão? Execute o suficiente para separar regressão determinística de variação. Cinco é um bom início para amostra pequena; falhas de alto impacto podem exigir vinte ou mais. ### O mesmo harness pode comparar modelos de provedores diferentes? Sim, se solicitação, contrato de ferramentas, eventos e asserções forem normalizados. Mantenha opções específicas em adaptadores para preservar a portabilidade do fixture.