Partilhar via

Rastreamento usando o Application Insights

  • Artigo

Determinar o raciocínio por trás das execuções do seu agente é importante para a solução de problemas e depuração. No entanto, pode ser difícil para agentes complexos por uma série de razões:

  • Pode haver um grande número de etapas envolvidas na geração de uma resposta, tornando difícil acompanhar todas elas.
  • A sequência de etapas pode variar de acordo com a entrada do usuário.
  • As entradas/saídas em cada fase podem ser longas e merecer uma inspeção mais aprofundada.
  • Cada etapa do tempo de execução de um agente também pode envolver aninhamento. Por exemplo, um agente pode invocar uma ferramenta, que usa outro processo, que então invoca outra ferramenta. Se você notar uma saída estranha ou incorreta de uma execução de agente de nível superior, pode ser difícil determinar exatamente onde o problema foi introduzido na execução.

O rastreamento resolve isso permitindo que você veja claramente as entradas e saídas de cada primitivo envolvido em uma determinada execução de agente, na ordem em que foram invocados.

Criando um recurso do Application Insights

O rastreamento permite analisar o desempenho e o comportamento do seu agente usando o OpenTelemetry e adicionando um recurso do Application Insights ao seu projeto do Azure AI Foundry.

Para adicionar um recurso do Application Insights, navegue até a guia Rastreamento no portal do Azure AI Foundry e crie um novo recurso se ainda não tiver um.

Uma captura de tela da tela de rastreamento no portal do Azure AI Foundry.

Depois de criado, você pode obter uma cadeia de conexão do Application Insights, configurar seus agentes e observar o caminho de execução completo do seu agente por meio do Azure Monitor. Normalmente, você deseja habilitar o rastreamento antes de criar um agente.

Rastrear um agente

Primeiro, use pip install para instalar o OpenTelemetry e o plug-in de rastreamento do SDK do Azure.

pip install opentelemetry
pip install azure-core-tracing-opentelemetry

Você também precisará de um exportador para enviar os resultados para o seu backend de observabilidade. Pode imprimir rastreios na consola ou utilizar um visualizador local, como o Aspire Dashboard. Para se ligar ao Aspire Dashboard ou a outro back-end compatível com OpenTelemetria, instale o exportador do OpenTelemetry Protocol (OTLP).

pip install opentelemetry-exporter-otlp

Depois de ter os pacotes instalados, você pode usar um dos seguintes exemplos Python para implementar o rastreamento com seus agentes. Os exemplos que usam o rastreamento de console exibem os resultados localmente no console. Os exemplos que usam o Azure Monitor enviam os rastreamentos para o Azure Monitor no portal do Azure AI Foundry, na guia Rastreamento no menu de navegação esquerdo do portal.

Nota

Há um bug conhecido na funcionalidade de rastreamento de agentes. O bug fará com que a ferramenta de função do agente chame informações relacionadas (nomes de funções e valores de parâmetros, que podem conter informações confidenciais) para serem incluídas nos rastreamentos, mesmo quando a gravação de conteúdo não estiver habilitada.

Usando o Azure Monitor

Usando o rastreamento de console