Visão geral do rastreio de agentes

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.

A Microsoft Foundry fornece uma plataforma de observabilidade para monitorizar e rastrear agentes de IA. Captura detalhes-chave durante a execução de um agente, como entradas, saídas, utilização de ferramentas, tentativas, latências e custos. Compreender a razão por trás das ações do seu agente é importante para a resolução de problemas e debugging. No entanto, compreender agentes complexos apresenta desafios por várias razões:

  • Pode haver um grande número de passos envolvidos na geração de uma resposta, tornando difícil acompanhar todos eles.
  • A sequência de passos pode variar consoante a entrada do utilizador.
  • As entradas e saídas em cada etapa podem ser longas e merecer uma inspeção mais detalhada.
  • Cada etapa do tempo de execução de um agente pode também envolver o aninhamento. Por exemplo, um agente pode invocar uma ferramenta, que utiliza outro processo, que depois invoca outra ferramenta. Se notar uma saída estranha ou incorreta numa execução de agente de topo, pode ser difícil determinar exatamente em que momento da execução o problema foi introduzido.

Os traços resolvem estes desafios ao permitir-lhe visualizar as entradas e saídas de cada primitiva envolvida numa determinada execução de agente, apresentadas pela ordem em que foram invocadas, facilitando a compreensão e depuração do comportamento do seu agente de IA.

Pré-requisitos

Para usar o rastreio fim a fim, precisa de:

Nota

O rastreamento armazena dados de telemetria no Azure Monitor Application Insights, o que pode gerar custos com base no volume de dados e nas definições de retenção. Para detalhes de preços, consulte Preços do Application Insights.

"OpenTelemetry" na "Foundry"

O OpenTelemetry (OTel) fornece protocolos padronizados para recolha e encaminhamento de dados de telemetria. O Foundry utiliza convenções semânticas OpenTelemetry para que os traços sejam consistentes entre as ferramentas e integrações suportadas.

Identificar conceitos-chave

Os seguintes conceitos-chave aplicam-se ao longo deste artigo:

Conceitos-chave Descrição
Vestígios Os traços captam a jornada de um pedido ou fluxo de trabalho através da sua aplicação, registando eventos e alterações de estado (chamadas de funções, valores, eventos do sistema). Ver Rastreios OpenTelemetry.
Intervalos Os spans constituem os fundamentos dos traços, representando operações únicas dentro de um traço. Cada intervalo captura horas de início e fim, atributos e pode ser aninhado para mostrar relações hierárquicas, para que possas ver toda a pilha de chamadas e a sequência de operações.
Atributos Os atributos são pares de chave-valor associados a rastreamentos e intervalos, fornecendo metadados contextuais, como parâmetros de função, valores de retorno ou anotações personalizadas. Estes enriquecem os dados de traço, tornando-os mais informativos e úteis para análise.
Convenções semânticas A OpenTelemetry define convenções semânticas para padronizar nomes e formatos para atributos de dados traçados, facilitando a interpretação e análise entre ferramentas e plataformas. Para saber mais, consulte as convenções semânticas do OpenTelemetry GenAI.
Exportadores de vestígios Os exportadores de traços enviam dados de rastreio para sistemas backend para armazenamento e análise. No Foundry, os rastos são armazenados no Azure Monitor Application Insights. Para saber como ativar e visualizar traços, veja Como configurar o traçado no Microsoft Foundry.

Como funciona o traçado na Foundry

O rastreio ajuda-te a responder a perguntas como "De onde veio esta resposta?" e "Qual etapa introduziu um erro ou pico de latência?"

Num nível elevado, a análise captura:

  • Entradas de utilizador e saídas de agentes.
  • Utilização de ferramentas, incluindo chamadas de ferramentas e resultados.
  • Consumo de tokens.
  • Sinais temporais como duração e latência.

Quando ativa o rastreio para o seu projeto, pode inspecionar os traços no portal Foundry e no Azure Monitor Application Insights. Para as opções de configuração e visualização passo a passo, veja Como configurar o traçado no Microsoft Foundry.

Estenda a OpenTelemetry com observabilidade multiagente

A Microsoft, em colaboração com a Cisco Outshift, contribui com convenções semânticas para sistemas multi-agente. Estas convenções baseiam-se nos OpenTelemetry GenAI agent and framework spans e no W3C Trace Context. Padronizam a telemetria para fluxos de trabalho multi-agente, incluindo invocações de agentes, orquestração de fluxos de trabalho, planeamento, chamadas de modelos e execução de ferramentas.

Importante

As convenções semânticas do OpenTelemetry GenAI têm o estado de Desenvolvimento e podem mudar em lançamentos futuros.

Estas melhorias estão integradas em:

  • Fundição
  • Estrutura do Microsoft Agent
  • LangChain
  • LangGraph
  • SDK de Agentes OpenAI

Para mais informações, veja integrações de rastreamento.

A tabela seguinte descreve as convenções comuns da OpenTelemetry GenAI para observabilidade multiagente. Os spans capturam operações, os spans filhos mostram atividade aninhada e os atributos fornecem metadados. Os intervalos parentais apresentados são exemplos comuns; o aninhamento real depende do agente ou framework instrumentado.

Tipo Contexto/Âmbito Parental Nome/Atributo/Evento Finalidade
Vão — invoke_agent Invoca um agente através de um serviço remoto ou dentro do mesmo processo.
Intervalo de filhos invoke_agent invoke_agent Traça uma invocação de outro agente através de uma relação de extensão entre pais e filhos.
Intervalo de filhos invoke_agent plan Regista uma fase de planeamento de um agente ou de decomposição de uma tarefa.
Vão — invoke_workflow Invoca um fluxo de trabalho coordenado que contém agentes ou outras operações de IA generativa.
Intervalo de filhos invoke_agent ou invoke_workflow execute_tool Regista a execução de uma ferramenta.
Intervalo de filhos invoke_agent ou invoke_workflow create_memory, search_memory, update_memory, upsert_memoryou delete_memory Regista uma operação de memória.
Atributo invoke_agent gen_ai.tool.definitions Regista definições de ferramentas disponíveis para um agente ou modelo.
Atributo execute_tool gen_ai.tool.call.arguments Regista os argumentos passados para uma chamada de ferramenta.
Atributo execute_tool gen_ai.tool.call.result Regista o resultado devolvido por uma invocação da ferramenta bem-sucedida.

Melhores práticas

  • Use consistentes atributos span: Aplique os mesmos nomes e formatos de atributos a todos os agentes e ferramentas para simplificar a consulta e a análise.
  • Correlacionar IDs de execuções de avaliação: Associar dados de rastreio a execuções de avaliação para analisar tanto a qualidade como o desempenho numa visão unificada.
  • Rediga conteúdos sensíveis: Remova ou oculte dados pessoais, segredos e credenciais de prompts, argumentos de ferramentas e atributos de alcance antes que cheguem à telemetria.

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 aprender os passos para encaminhar conteúdos sensíveis para a tabela dedicada e restringir o acesso a ele, veja Restrição de acesso a conteúdos sensíveis.

Resolução de problemas

Se os vestígios não aparecerem no portal Foundry ou no Application Insights:

  • Verifique se o seu projeto Foundry está ligado a um recurso do Application Insights.
  • Verifique se a sua conta tem as permissões necessárias para consultar telemetria.
  • Certifique-se de que o seu código de agente inclui a instrumentação necessária. Para configuração específica do framework, veja Integrações de Rastreio.

Dica

O rastreamento está disponível em todas as regiões onde o Foundry é suportado. A retenção e amostragem de dados de telemetria seguem a configuração do seu Application Insights. Para mais detalhes, consulte retenção e arquivamento de dados no Azure Monitor Logs.

Conteúdo relacionado

  • Last updated on