Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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.
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/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 resultados de rastreamento resolvem isto ao permitir-lhe visualizar as entradas e saídas de cada primitiva envolvida numa execução de agente específica, 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:
- Um projeto Foundry com rastreio ativado. Para configurar, veja Como configurar o traçado no Microsoft Foundry.
- Aceder ao recurso Application Insights relacionado com o seu projeto. Para contextualizar, veja Azure Monitor Application Insights.
- Função de leitor de Log Analytics para visualizar registos, insights e visualizações no Foundry.
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
Aqui fica uma breve visão geral dos conceitos-chave antes de começar:
| 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 capta horas de início e fim, atributos e pode ser aninhado para mostrar relações hierárquicas, permitindo-lhe ver a pilha completa 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. Estas enriquecem os dados de rastreamento, 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 da OpenTelemetry. |
| 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.
Depois de ativar o traçado 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.
Extensão do OpenTelemetry com observabilidade multiagente
Microsoft, em colaboração com a Cisco Outshift, introduziu novas convenções semânticas para sistemas multi-agente, baseadas em OpenTelemetry e W3C Trace Context. Estas convenções padronizam a telemetria para fluxos de trabalho multi-agente, permitindo um registo consistente de métricas de qualidade, desempenho, segurança e custo, incluindo invocações de ferramentas e colaboração.
Estas melhorias estão integradas em:
- Fundição
- Microsoft Agent Framework
- LangChain
- LangGraph
- SDK de Agentes OpenAI
Para saber mais, veja integrações de traço.
A tabela seguinte descreve as convenções semânticas para a observabilidade multi-agente. Os intervalos capturam operações discretas, os subintervalos mostram operações aninhadas dentro de um intervalo pai, os atributos fornecem metadados e os eventos assinalam ocorrências significativas durante a execução.
| Tipo | Contexto/Âmbito Parental | Nome/Atributo/Evento | Finalidade |
|---|---|---|---|
| Vão | — | executar_tarefa | Captura o planeamento de tarefas e a propagação de eventos, fornecendo insights sobre como as tarefas são decompostas e distribuídas. |
| Intervalo Infantil | invoke_agent | interação_entre_agentes | Rastreia a comunicação entre agentes. |
| Intervalo Infantil | invoke_agent | agente.estado.gestão | Contexto eficaz, gestão da memória a curto ou longo prazo. |
| Intervalo Infantil | invoke_agent | planeamento_de_agente | Regista os passos internos de planeamento do agente. |
| Intervalo Infantil | invoke_agent | Orquestração de agentes | Capta a orquestração entre agentes. |
| Atributo | invoke_agent | definições_de_ferramentas | Descreve o propósito ou configuração da ferramenta. |
| Atributo | invoke_agent | llm_spans | Registos do alcance das chamadas do modelo. |
| Atributo | execute_tool | ferramenta.chamada.argumentos | Regista os argumentos passados durante a invocação da ferramenta. |
| Atributo | execute_tool | ferramenta.chamada.resultados | Regista os resultados devolvidos pela ferramenta. |
| Evento | — | Avaliação (nome, tipo de erro, rótulo) | Permite uma avaliação estruturada do desempenho e da tomada de decisão dos agentes. |
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çã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.
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.