Quickstart: Rastreie o seu agente alojado

Note

O rastreamento está atualmente em pré-visualização.

Neste guia de início rápido, verá os rastreios de ponta a ponta do agente alojado que implementou em Implemente o seu primeiro agente alojado. Invoca o seu agente para gerar dados de rastreio e consultar os rastreios no portal da Foundry.

As bibliotecas anfitriãs (azure-ai-agentserver-responses e azure-ai-agentserver-invocations) integram perfeitamente a distribuição do Microsoft OpenTelemetry, que fornece instrumentação pronta a usar para o Microsoft Agent Framework e o LangChain, e exporta traces para o Application Insights. Além disso, o Foundry Agent Service emite automaticamente telemetria no lado do servidor para a invocação do agente — sem necessidade de alterações ao código.

O rastreamento dá-lhe visibilidade sobre como o seu agente lida com cada pedido, para que possa depurar problemas, monitorizar a latência e compreender o comportamento do agente antes de divulgar alterações aos utilizadores.

Pré-requisitos

Antes de começar, você precisa:

Passo 1: Invocar o seu agente

Gera dados de rastreio enviando um pedido ao teu agente implementado.

A partir do diretório do seu azd projeto, envie um prompt de teste:

azd ai agent invoke "Summarize the benefits of distributed tracing for AI agents."

Deves ver uma resposta dentro de alguns segundos.

Cada invocação gera um rasto completo. Para trilhas mais ricas, envie prompts que desencadeiam chamadas de ferramenta ou raciocínio com múltiplas voltas.

Passo 2: Visualizar os rastos no portal da Fundição

Os vestígios podem ser vistos no portal da Fundição após a invocação.

  1. No portal da Foundry, abra o seu projeto.
  2. Na navegação à esquerda, selecione Agentes.
  3. No topo, selecione Traces.
  4. Encontre o seu rasto na lista. Pode pesquisar por ID de Traço, ID de Resposta ou filtrar por intervalo temporal.

Trajetória

Captura de ecrã da visualização em cascata do rastreio no portal Foundry que mostra os segmentos de invoke_agent, conclusões de chat e pedidos de tokens, com os detalhes de entrada/saída à direita.

Vista do utilizador

Animação da visualização dos rastreios pelo utilizador no portal Foundry.

Sugestão

Se o seu agente usar o Microsoft Agent Framework, ele emite automaticamente os seus próprios OpenTelemetry Spans. Estes spans aparecem como filhos dos spans da camada de alojamento, proporcionando-lhe uma árvore de rastreamento completa desde o pedido HTTP, passando pela orquestração de agentes, até às chamadas individuais a ferramentas e às interações com LLMs.

Limpeza de recursos

Os dados de rastreamento são armazenados no Application Insights e seguem as definições de retenção de dados do seu espaço de trabalho. Este quickstart não cria recursos extra. Para limpar o início rápido anterior, execute azd down o diretório do seu agente do projeto. O que o comando elimina depende se a inicialização criou ou reutilizou o projeto Foundry.

Warning

Se o ambiente atual azd criou o projeto Foundry, azd down apaga permanentemente o grupo de recursos do projeto e tudo o que nele existe. Se selecionou um projeto existente durante a inicialização, azd down deixa o projeto, o seu grupo de recursos, o agente alojado e outros recursos de início rápido no local. Para eliminar recursos que já não precisa do projeto existente, elimine-os separadamente.

Solução de problemas

Problema Solução
Não usar agentes alojados no Foundry e os vestígios não aparecem Este guia de introdução rápida abrange apenas agentes alojados. Para agentes de rastreamento alojados fora do Foundry, consulte Registar um agente externo.
Não aparecem vestígios após a invocação do agente Confirme que o Application Insights está ligado ao seu projeto Foundry. Se não estiver ativado, consulte Configurar o rastreio no Microsoft Foundry. Verifique se o agente respondeu com sucesso com azd ai agent invoke.
Os rastreios aparecem, mas faltam aos spans os atributos de dados de entrada/saída Ative a gravação de conteúdo definindo a variável OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true de ambiente na configuração do seu agente.
AuthorizationFailed ao visualizar os traços Precisa da função de Log Analytics Reader no recurso do Application Insights. Se as tabelas estiverem protegidas, atribua também a função Leitor de Dados de Monitorização com Privilégios.
Os rastreios aparecem, mas faltam os intervalos das chamadas de ferramenta Verifica se o teu agente define ferramentas e o modelo as invoca durante o pedido. Se estiver a usar o Microsoft Agent Framework, confirme que as ferramentas estão registadas no Agent construtor através do tools parâmetro. Veja Adicionar ferramentas ao seu agente.
AuthenticationError ou DefaultAzureCredential falha Atualize as credenciais com azd auth logout e depois azd auth login.

O que aprendeste

Neste guia de início rápido, você irá:

  • Aprendi que as bibliotecas de alojamento integram a distribuição Microsoft OpenTelemetry para instrumentação pronta a usar.
  • Invocou o seu agente implementado para gerar dados de rastreamento.
  • Visualizei os rastreios de ponta a ponta no portal da Foundry.

Passos seguintes

Configurar o traçado no Microsoft Foundry

Conteúdo relacionado

  • Última atualização a