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 apenas para agentes de prompt. Fluxo de trabalho, agentes alojados e personalizados estão em pré-visualização.

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 prompt e operações de recuperação — para que possa identificar e resolver problemas mais rapidamente.

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 referem-se à Foundry (nova).
  2. Abre o teu projeto Foundry.
  3. Na navegação à esquerda, selecione Agentes.
  4. No topo, selecione Traces.
  5. À direita, selecione Conectar, para criar ou ligar um recurso Application Insights:
    • Para ligar um recurso existente, selecione o recurso e depois selecione Conectar.
    • Para criar um novo recurso, selecione Criar novo e complete o assistente.

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

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

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

Se não vir a barra de mensagens ou o botão Conectar, aqui está uma forma alternativa de ativar o Azure Monitor Application Insights.

  1. Selecione os detalhes do projeto no menu suspenso do seu nome de projeto. Captura de ecrã do menu do nome do projeto com os detalhes do projeto destacados.
  2. Navega até ao separador Recursos Conectados e depois seleciona Adicionar ligação. Captura de ecrã dos detalhes do projeto com o separador de recursos conectados, destacando a opção para adicionar ligação.
  3. Selecione Application Insights no menu Selecione uma ligação. Captura de ecrã de Escolha uma ligação com o Application Insights destacada.

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. Assim que o rastreio estiver ativado no seu projeto Foundry, terá acesso a rastreios pré-definidos dos últimos 90 dias.
  • O Foundry também permite uma 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:

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

Importante

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

Depois de gerir o seu agente, pode começar a visualizar e analisar as pistas no portal 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.

Efetuar rastreamento local com o Foundry Toolkit no VS Code

O Foundry Toolkit permite-lhe traçar localmente no VS Code usando um coletor local compatível com OTLP, o que é ideal para desenvolvimento e depuração.

O kit de ferramentas suporta frameworks de IA como Foundry Agents 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 intervalo, identifique problemas e observe como a sua aplicação responde. Isto 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 .

Pode selecionar uma pesquisa de conversa por um ID de Resposta, ou pesquisar por um ID de Traço que corresponda a essa conversa. Depois, selecione ID da Conversa para rever a conversa:

  • 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ção sensível (por exemplo, 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.
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 o rastreio está implementado, explore estes recursos para aprofundar a sua compreensão e ampliar as suas capacidades de observabilidade:

  • Last updated on