Logs de execução reproduzíveis para agentes: registrar cada chamada ao modelo e às ferramentas

O que é

Um log reproduzível é o registro de uma execução de agente a partir do qual cada passo pode ser reconstruído: a requisição exata enviada ao modelo (prompt de sistema, mensagens, definições de ferramentas, parâmetros de amostragem), a resposta (conteúdo, chamadas de ferramentas, motivo de parada, uso) e, para cada chamada de ferramenta, seus argumentos, resultado e status de erro, tudo em ordem e com timestamps. As convenções semânticas GenAI do OpenTelemetry definem nomes de atributos para isso; elas ainda estão marcadas como em desenvolvimento e agora ficam em um repositório separado, semantic-conventions-genai, enquanto o registro de atributos em opentelemetry.io as lista com um aviso de que foram movidas. Entre elas estão gen_ai.request.model, gen_ai.request.temperature, gen_ai.request.seed, gen_ai.response.id, gen_ai.response.finish_reasons, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.tool.call.id, gen_ai.tool.call.arguments, gen_ai.tool.call.result e gen_ai.conversation.id, usado para agrupamento. Os frameworks de avaliação guardam as mesmas informações por amostra; o Inspect, por exemplo, grava um arquivo de log para cada tarefa avaliada e o expõe como um objeto EvalLog.

Por que importa

As saídas dos modelos não são determinísticas, os resultados das ferramentas mudam conforme o estado do mundo e uma execução pode ter centenas de passos. Sem o log, não há como rastrear "o agente apagou o arquivo errado" até o passo em que o caminho incorreto entrou no contexto. Com ele, a requisição que gerou uma decisão ruim pode ser reenviada literalmente para testar uma correção de prompt, e os resultados das ferramentas podem ser simulados (stub) a partir do log, de modo que o restante da execução seja reproduzido sem efeitos colaterais.

Como aplicar

• Registre no ponto em que a requisição sai do processo, e não a partir do template do prompt: o que importa são os bytes realmente enviados.
• Atribua um ID a cada execução e um número de sequência a cada passo; vincule os resultados das ferramentas ao ID da chamada, em vez de depender da ordem.
• Armazene o conteúdo completo, mas remova segredos e dados pessoais antes de gravar (as mesmas regras dos logs de aplicação) e defina um período de retenção.
• Registre o ID da resposta e, quando o provedor oferecer, uma versão ou fingerprint do modelo que atendeu a requisição.
• Construa um modo de replay: dado um log, o harness devolve os resultados de ferramentas gravados para chamadas idênticas e sinaliza as chamadas que divergem da gravação.
• Use os mesmos IDs em traces e métricas, para que os painéis de custo e latência levem de volta a uma transcrição.

Armadilhas

Registrar apenas a resposta final. Truncar os resultados das ferramentas no log, o que esconde a instrução injetada ou o payload malformado que causou a falha. Considerar determinístico o replay contra um modelo real: o replay reproduz as entradas, não a decisão. Logs que repetem todo o conjunto de documentos a cada passo crescem rápido; deduplique por hash de conteúdo.