Implementing Logging and Traceability

1. A Mudança de Paradigma: Depurando o Raciocínio, Não Apenas o Código

Diferentemente do software tradicional, que é em grande parte determinístico, os agentes de IA operam com base em LLMs não determinísticos. A mesma entrada pode gerar saídas ligeiramente diferentes. Isso significa que a depuração muda de encontrar um bug em uma função para entender uma falha no "raciocínio" do agente. Nossa principal ferramenta para isso é a observabilidade.

Para entender essa mudança fundamental, assista às seções a seguir de uma apresentação da LangChain, uma popular biblioteca de orquestração de agentes.

Esses conceitos — especialmente o de trace como uma gravação completa de cada passo do agente — são a base de qualquer sistema de logging robusto para IA.

2. Rastreabilidade no Ecossistema Atlassian

Felizmente, a plataforma Atlassian já oferece ferramentas integradas para logging e auditoria, que servem como nossa primeira camada de rastreabilidade.

Logs de Auditoria do Jira

Para qualquer ação que o agente execute no Jira (como comentar ou transicionar um ticket), o Jira registra o evento em seus logs de auditoria. Isso fornece uma trilha de auditoria "quem, o quê e quando" para as interações do agente com o sistema de gerenciamento de projetos.

Logging em Rovo e Forge

Quando seu agente está em execução, especialmente em um fluxo de trabalho de automação, você precisa ver o que ele está "pensando". A Atlassian fornece mecanismos para registrar a saída do agente.

A capacidade de forçar a saída em JSON é extremamente poderosa. Em vez de uma resposta em linguagem natural, você pode instruir o agente a gerar um objeto JSON que contenha seu plano, os parâmetros da ferramenta que ele escolheu e seu raciocínio. Esse JSON pode ser registrado diretamente, fornecendo um registro estruturado e pesquisável de cada decisão.

3. Uma Abordagem Padrão da Indústria: OpenTelemetry e Semantic Kernel

Para um desenvolvedor com sua experiência em C#/.NET e DevOps, adotar padrões da indústria para observabilidade é um passo natural e altamente recomendado. O padrão de fato para instrumentar, gerar e coletar dados de telemetria é o OpenTelemetry (OTel).

O OpenTelemetry se baseia em três pilares:

1. Logs: Registros de eventos discretos que acontecem em um determinado momento (ex: "Arquivo X lido com sucesso").
2. Metrics: Medições agregadas ao longo do tempo (ex: tempo médio de execução da função, número de tokens de LLM usados por hora).
3. Traces: Registros detalhados de uma única transação ou solicitação à medida que ela passa por múltiplos componentes de um sistema. Isso se alinha perfeitamente com o conceito de trace de agente que vimos anteriormente.

Felizmente, frameworks de IA modernos, como o Semantic Kernel da Microsoft (que é escrito em .NET), têm suporte de primeira classe para o OpenTelemetry.

A implementação disso em seu código C# é surpreendentemente simples. Você usa pacotes NuGet para configurar o OpenTelemetry e direcionar a saída para um destino, como o console (para desenvolvimento) ou um serviço de monitoramento como o Azure Monitor.

A adoção do OpenTelemetry lhe daria uma solução de logging de nível empresarial que pode crescer com seu agente, fornecendo insights não apenas sobre o comportamento, mas também sobre o custo (uso de tokens) e o desempenho (duração).

4. Estratégia de Rastreabilidade para o Seu Agente

Vamos sintetizar tudo isso em uma estratégia concreta para o seu agente de codificação.

1. ID de Rastreamento Único (Trace ID): No início de cada execução do agente (acionada por uma tarefa do Jira), gere um ID único (por exemplo, um GUID).

2. Log Estruturado por Etapa: Para cada passo no plano do seu agente, registre uma entrada de log estruturada (JSON) contendo:

   • O traceId da execução geral.
   • Um stepId para a etapa atual.
   • timestamp.
   • stepName (ex: "AnalyzeJiraTicket", "SearchBusinessRules", "GenerateCSharpCode", "CreatePullRequest").
   • inputs: Os dados de entrada para a etapa (ex: prompt do LLM, chave do ticket do Jira). Cuidado com dados sensíveis aqui!
   • outputs: O resultado da etapa (ex: resposta do LLM, URL do PR, status de sucesso/falha).
   • metrics: Métricas relevantes como duration_ms e token_usage.

3. Armazenamento de Logs:

   • Desenvolvimento: O log do console do Forge é suficiente.
   • Produção: Envie esses logs estruturados para um sistema centralizado. As ferramentas da Atlassian podem registrar no CloudWatch da AWS. Se você usar uma abordagem baseada em OpenTelemetry, pode enviar para Azure Monitor, Datadog ou qualquer outro backend compatível.

4. Auditoria e Depuração:
   Com logs estruturados, você pode facilmente consultar e visualizar o comportamento do agente.

   • Para auditar: "Mostre-me todas as ações executadas pelo agente para o ticket PROJ-123." (Filtre por inputs.jiraTicket == 'PROJ-123').
   • Para depurar: "A geração de código falhou. Mostre-me o prompt exato enviado ao LLM e a resposta de erro que ele retornou para o traceId xyz-abc."
   • Para otimizar: "Qual etapa do processo está demorando mais?" (Agregue duration_ms por stepName).

Este nível de detalhe transforma seu agente de uma "caixa preta" em um sistema transparente e gerenciável.

Conclusão

Nesta lição, você aprendeu a importância crítica da observabilidade para agentes de IA e explorou métodos práticos para implementá-la. Agora você está equipado para construir um agente que não apenas funciona, mas que também é robusto, depurável e auditável.

Principais Pontos:

• A depuração de agentes de IA foca em entender o raciocínio, e os traços (traces) são a fonte da verdade para isso.
• O ecossistema Atlassian fornece ferramentas integradas como logs de auditoria do Jira e ações de log do Forge/Rovo.
• O uso de saída JSON estruturada do agente é uma técnica poderosa para um logging que pode ser facilmente analisado por máquinas.
• OpenTelemetry é o padrão da indústria para observabilidade, e sua integração com ferramentas como o Semantic Kernel o torna uma escolha ideal para um desenvolvedor .NET.
• Uma estratégia de rastreabilidade robusta envolve um ID de rastreamento único e o logging detalhado e estruturado de cada etapa da execução do agente.

Você completou o Módulo 8, construindo um fluxo de trabalho de ponta a ponta. Agora que temos um agente funcional e observável, a próxima fronteira é garantir que o trabalho que ele produz seja de alta qualidade.

Na próxima lição, iniciaremos o Módulo 9: Garantindo a Qualidade dos Ativos Gerados. Começaremos com a primeira linha de defesa da qualidade do código: integrar ferramentas de linting automatizado para garantir que o código gerado pelo agente siga as convenções do seu projeto.