Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Neste guia de início rápido, você verá rastreamentos completos do agente hospedado que você implantou em Implante seu primeiro agente hospedado. Você aciona seu agente para gerar dados de rastreamento e analisar rastreamentos no portal Foundry.
As bibliotecas de hospedagem (azure-ai-agentserver-responses e azure-ai-agentserver-invocations) se integram perfeitamente à distribuição do Microsoft OpenTelemetry, que fornece instrumentação pronta para uso para o Microsoft Agent Framework e o LangChain, e exporta rastreamentos para o Application Insights. Além disso, o Foundry Agent Service emite a telemetria do lado do servidor para invocação de agente automaticamente — nenhuma alteração de código é necessária.
O rastreamento fornece visibilidade de como seu agente lida com cada solicitação para que você possa depurar problemas, monitorar a latência e entender o comportamento do agente antes de liberar alterações aos usuários.
Pré-requisitos
Antes de começar, você precisa de:
Um agente hospedado implantado e invocável de Implante seu primeiro agente hospedado e o diretório do projeto
azdque você criou nesse guia de início rápido.A função Usuário do Foundry no recurso do Foundry.
Para usar o caminho da interface, acesse o portal do Foundry. Para o caminho do azd, veja os requisitos a seguir.
Azure Developer CLI (azd) 1.36.0 ou posterior com a
microsoft.foundryextensão:azd ext install microsoft.foundryUma
azdsessão autenticada. Verifique seu status comazd auth statuse executeazd auth loginse você não estiver conectado.Importante
As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.
Um recurso do Azure Monitor Application Insights conectado ao projeto do Foundry. Para configurá-lo, consulte Configurar o rastreamento no Microsoft Foundry.
A função Log Analytics Reader no recurso do Application Insights conectado ao seu projeto. Se as tabelas de Log Analytics subjacentes estiverem protegidas, atribua também a função Leitor de Dados de Monitoramento Privilegiado.
Etapa 1: Invocar seu agente
Gere dados de rastreamento enviando uma solicitação ao agente implantado.
No diretório azd do projeto, envie um prompt de teste:
azd ai agent invoke "Summarize the benefits of distributed tracing for AI agents."
Você deverá ver uma resposta dentro de alguns segundos.
Cada invocação gera um rastreamento completo. Para rastreamentos mais complexos, envie prompts que acionem chamadas de ferramentas ou raciocínio em várias etapas.
Etapa 2: Visualizar rastros no portal do Foundry
Os rastros podem ser visualizados no portal do Foundry após a invocação.
- No portal do Foundry, abra seu projeto.
- Na navegação à esquerda, selecione Agentes.
- Na parte superior, selecione Rastreamentos.
- Encontre seu rastreamento na lista. Você pode pesquisar por ID de rastreamento, ID de resposta ou filtro por intervalo de tempo.
Trajetória
Visão do usuário
Tip
Se o seu agente usa o Microsoft Agent Framework, ele gera automaticamente seus próprios intervalos do OpenTelemetry. Esses intervalos aparecem como filhos dos intervalos da camada hospedeira, fornecendo uma árvore de rastreamento completa, desde a solicitação HTTP, passando pela orquestração de agentes, até chamadas de ferramentas individuais e interações com LLM.
Limpar os recursos
Os dados de rastreamento são armazenados no Application Insights e seguem as configurações de retenção de dados do espaço de trabalho. Este quickstart não cria quaisquer recursos adicionais. Para limpar o quickstart anterior, execute azd down no diretório do projeto do agente. O que o comando exclui depende se a inicialização criou ou reutilizou o projeto foundry.
Aviso
Se o ambiente atual azd criou o projeto Foundry, azd down exclui permanentemente o grupo de recursos do projeto e tudo nele. Se você selecionou um projeto existente durante a inicialização, azd down mantém o projeto, seu grupo de recursos, o agente hospedado e outros recursos de inicialização rápida. Para excluir recursos que você não precisa mais do projeto existente, exclua-os separadamente.
Resolução de problemas
| Questão | Solução |
|---|---|
| Não está usando agentes hospedados no Foundry e os rastreamentos não estão sendo exibidos | Este guia de início rápido trata apenas de agentes hospedados. Para rastrear agentes hospedados fora do Foundry, consulte Registrar um agente externo. |
| Nenhum rastreamento é exibido depois de acionar o agente | Confirme se o Application Insights está conectado ao projeto do Foundry. Se ele não estiver habilitado, consulte Configurar o rastreamento no Microsoft Foundry. Verifique se o agente respondeu com êxito com azd ai agent invoke. |
| Rastros aparecem, mas os spans não têm atributos de dados de entrada/saída | Habilite a gravação de conteúdo definindo a variável OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true de ambiente na configuração do agente. |
AuthorizationFailed ao visualizar rastros |
Você precisa da função Log Analytics Leitor no recurso Application Insights. Se as tabelas estiverem protegidas, atribua também o Leitor de Dados de Monitoramento Privilegiado. |
| Rastreamentos aparecem, mas faltam intervalos de chamadas de ferramenta | Verifique se o agente define as ferramentas e se o modelo as invoca durante a solicitação. Se estiver usando Microsoft Agent Framework, confirme se as ferramentas são registradas com o Agent construtor por meio do tools parâmetro. Consulte Adicionar ferramentas ao seu agente. |
AuthenticationError ou DefaultAzureCredential falha |
Atualize as credenciais com azd auth logout e depois azd auth login. |
O que você aprendeu
Neste guia de início rápido, você:
- Aprendeu que as bibliotecas de hospedagem integram a distribuição do Microsoft OpenTelemetry para instrumentação pronta para uso.
- Invocou o agente implantado para gerar dados de rastreamento.
- Visualizou rastreamentos completos no portal do Foundry.
Próximas Etapas
- Configure o rastreamento no Microsoft Foundry para uma configuração de rastreamento detalhada.
- Configure o rastreamento para frameworks de agentes de IA para instrumentar o LangChain e outros frameworks.
- Monitore agentes de IA com o Painel de Monitoramento do Agente para monitoramento de produção.