Configurar o traçado no Microsoft Foundry

Importante

Os itens marcados (pré-visualização) neste artigo encontram-se atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para cargas de trabalho em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

Nota

O rastreamento está geralmente disponível para agentes prompts e alojados. Workflow e os agentes externos estão em versão preliminar.

Use o rastreamento para depurar os seus agentes de IA e monitorizar o seu comportamento em produção. O rastreamento capta telemetria detalhada – incluindo latência, exceções, conteúdo de prompts e operações de recuperação – para que possa identificar e resolver problemas mais rapidamente.

O ponto de partida recomendado é o rastreamento do lado do servidor. O Foundry ativa-o automaticamente depois de ligar um recurso Application Insights ao seu projeto. Não são necessárias alterações de código, e os rastreios estão disponíveis em poucos minutos após a ativação. O rastreamento do lado do servidor funciona para qualquer agente alojado no Foundry. Quando precisar de ter acesso ao seu próprio código de aplicação – por exemplo, para traçar lógica personalizada em torno de uma chamada de agente – pode adicionar instrumentação do lado do cliente como segundo passo.

A Microsoft Foundry Skill pode ajudar a escolher entre o rastreio do lado do servidor e o do lado do cliente, bem como a diagnosticar e resolver problemas de telemetria em falta.

Pré-requisitos

Ligue o Application Insights ao seu projeto Foundry

A Foundry armazena vestígios no Application Insights utilizando convenções semânticas do OpenTelemetry.

  1. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos dizem respeito a Foundry (new).

  2. Abre o teu projeto Foundry.

  3. Na navegação à esquerda, selecione Agentes.

  4. No topo, selecione Traces.

  5. À direita, selecione Ligar para criar ou ligar um recurso Application Insights.

    Captura de ecrã do separador Agentes a mostrar os registos e o botão para ligar.

  • Para ligar um recurso existente, selecione o recurso e depois selecione Conectar.
  • Para criar um novo recurso, selecione Criar novo e depois complete o assistente.

Aparece uma mensagem de confirmação quando a ligação é bem-sucedida.

Use o caminho de ligação dos detalhes do projeto

Se não vir a barra de mensagens ou o botão Conectar, use esta forma alternativa para ativar o Azure Monitor Application Insights.

  1. Selecione Gerir no canto superior direito da navegação e depois selecione Project details. Captura de ecrã da secção Gestão, com a opção Detalhes do Projeto destacada.
  2. Selecione o separador Recursos Conectados e depois selecione Adicionar ligação. Captura de ecrã dos detalhes do Project com o separador Recursos Conectados selecionado e o botão Adicionar Ligação destacado.
  3. Em Escolher uma ligação, selecione Insights de Aplicação. Captura de ecrã de Escolha uma ligação com o Application Insights destacada.

Para a ingestão de traços autenticada com o Entra, consulte Configurar a autenticação do Microsoft Entra para a ingestão de traços do Foundry Agent (pré-visualização).

Depois de ligar o recurso, o seu projeto está pronto para usar o rastreamento.

Importante

Certifica-te de que tens as permissões necessárias para consultar telemetria.

Instrumentar Agentes de IA

Escolha a abordagem que se adapte à forma como constrói e gere o seu agente.

Registros do servidor no portal Foundry

Comece com os registos do servidor. O Foundry regista rastreios para cenários comuns de agentes e fluxos de trabalho sem alterar o teu código.

  • Foundry regista automaticamente os registos de atividade do lado do servidor para agentes Prompt, agentes Host e fluxos de trabalho no portal Foundry. Depois de ativar o rastreio no seu projeto Foundry, tem acesso a rastreios pré-configurados dos últimos 90 dias.
  • O Foundry também suporta integração fácil com frameworks de agentes de topo.

Rastreamentos do lado do cliente com o Microsoft Foundry SDK (Python)

Instale o OpenTelemetry e o plugin de rastreamento do SDK do Azure usando os seguintes passos:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

Referência: azure-ai-projects, azure-core-tracing-opentelemetry

Importante

Para usar o endpoint de um projeto na sua aplicação, precisa de configurar o Microsoft Entra ID. Se não configurar o Microsoft Entra ID, utilize a cadeia de conexão do Application Insights.

Depois de executar o seu agente, pode visualizar e analisar os rastreios no portal do Foundry.

Para instruções detalhadas e exemplos de código específicos de SDK, veja Tracing with azure-ai-projects (Python SDK) e Samples de Telemetria para agentes.

Rastreie localmente com a extensão Microsoft Foundry Toolkit for Visual Studio Code

A extensão Microsoft Foundry Toolkit for Visual Studio Code permite-lhe rastrear localmente no VS Code usando um coletor local compatível com OTLP. Esta abordagem é ideal para desenvolvimento e depuração.

O kit de ferramentas suporta frameworks de IA como Foundry Agent Service, OpenAI, Anthropic e LangChain através do OpenTelemetry. Consegues ver traços instantaneamente no VS Code sem precisar de acesso à cloud.

Para instruções detalhadas de configuração e exemplos de código específicos para SDK, veja Rastreamento no Foundry Toolkit.

Visualize e analise rastros

Ver trilhos no portal da Fundição

No seu projeto Foundry, aceda ao separador Traces nos seus agentes ou fluxos de trabalho. Pode pesquisar, filtrar ou ordenar vestígios ingeridos dos últimos 90 dias.

Selecione um traçado para percorrer cada espaço, identifique problemas e observe como a sua aplicação responde. Este processo ajuda-o a depurar e identificar problemas na sua aplicação.

Ver rastreios no Azure Monitor

Os seus rastreios são enviados para o Azure Monitor Application Insights, por isso pode vê-los lá.

Para mais informações sobre como enviar traços para Azure Monitor e criar um recurso Azure Monitor, consulte Azure Monitor OpenTelemetry documentation.

Ver resultados das conversas

Uma Conversa é o contexto persistente de um histórico de diálogo de ponta a ponta entre um utilizador e um agente. No portal da Foundry, pode ver os resultados da Conversa para o seu agente, executados diretamente da caixa, juntamente com os traços na página de Rastreios .

Pesquise por ID de Resposta ou por um ID de Rastreio que corresponda a esta conversa. Depois seleciona um ID de Conversa para rever:

  • Detalhes do histórico das conversas
  • Informação de resposta e tokens numa execução
  • Ações ordenadas, passos de execução e chamadas de ferramentas
  • Entradas e saídas entre um utilizador e um agente

Captura de ecrã do painel de detalhes da Conversa no Foundry a mostrar um ID de conversa com uma linha temporal de rastreio e detalhes dos passos de execução.

Verificar que o rastreio funciona

  1. Confirme que o seu projeto está ligado ao Application Insights. Se necessário, siga os passos em Ligar Insights de Aplicação ao seu projeto Foundry.

  2. Execute o seu agente ou fluxo de trabalho pelo menos uma vez (por exemplo, usando o portal ou a sua aplicação).

  3. No seu projeto Foundry, abra a vista Traces e confirme que aparece um novo trace.

    Quando o rastreio está a funcionar corretamente, pode ver uma lista de rastreamentos recentes com marcações temporais, durações e indicadores de estado. Selecione um rasto para ver os detalhes da sua extensão.

Espera alguns minutos e atualiza. Se não vires novos registos, vê a Resolução de Problemas.

Segurança e privacidade

O rastreamento pode captar informações sensíveis, como entradas do utilizador, saídas de modelos e argumentos e resultados de ferramentas. Use estas práticas para reduzir o risco:

  • Não armazene segredos, credenciais ou tokens em prompts, argumentos de ferramentas ou atributos de intervalo.
  • Rediga ou minimize dados pessoais e outros conteúdos sensíveis antes que apareçam na telemetria.
  • Trate os dados de rastreio como telemetria de produção e aplique os mesmos controlos de acesso e políticas de retenção que usa para registos e métricas.

Para mais orientações, consulte Segurança e privacidade.

Retenção de dados e custo

A Foundry armazena vestígios no recurso Application Insights ligado ao seu projeto. A retenção de dados e a faturação seguem a configuração do seu Application Insights e Log Analytics.

Resolução de problemas

Problema Causa Resolução
Não vês quaisquer vestígios no portal da Fundição O rastreamento não está ligado, não há tráfego recente ou a ingestão está atrasada Confirma a ligação ao Application Insights, gera tráfego de novos agentes e atualiza após alguns minutos.
Vê erros de autorização quando consulta ou visualiza telemetria Faltam permissões RBAC no Application Insights ou no Log Analytics. Confirme o acesso no controlo de acesso (IAM) para os recursos ligados. Para consultas de log, atribua a função de Leitor Log Analytics. Se as tabelas estiverem protegidas, atribua também a função Leitor de Dados de Monitorização com Privilégios.
Os registos do lado do cliente não são apresentados A instrumentação não está instalada nem configurada Verifique novamente a instalação do seu pacote e siga as orientações do SDK indicadas em Rastreio do lado do cliente com o SDK Microsoft Foundry (Python).
Conteúdo sensível aparece em rastos Prompts, argumentos de ferramentas ou saídas contêm dados sensíveis Rediga os dados sensíveis antes de entrarem na telemetria e siga as orientações em Segurança e privacidade.

Conteúdo relacionado

Agora que configurou o rastreamento, explore estes recursos para aprofundar a sua compreensão e ampliar as suas capacidades de observabilidade:

  • Last updated on