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.
Importante
Itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou ter recursos restritos. Para obter mais informações, consulte Supplemental Terms of Use for Microsoft Azure Previews.
Nota
O rastreamento geralmente está disponível para agentes hospedados e prompt. O fluxo de trabalho e os agentes externos estão em versão prévia.
Microsoft Foundry fornece uma plataforma de observabilidade para monitorar e rastrear agentes de IA. Ele captura os principais detalhes durante uma execução de agente, como entradas, saídas, uso da ferramenta, repetições, latências e custos. Entender o raciocínio por trás das execuções do agente é importante para a resolução de problemas e depuração. No entanto, a compreensão de agentes complexos apresenta desafios por vários motivos:
- Pode haver um grande número de etapas envolvidas na geração de uma resposta, dificultando o acompanhamento de todas elas.
- A sequência de etapas pode variar com base na entrada do usuário.
- As entradas e saídas em cada estágio podem ser extensas e merecem uma inspeção mais detalhada.
- Cada etapa do tempo de execução de um agente também pode envolver aninhamento. Por exemplo, um agente pode invocar uma ferramenta, que utiliza outro processo, que então invoca outra ferramenta. Se você observar uma saída estranha ou incorreta de uma execução de agente de nível superior, pode ser difícil determinar exatamente onde na execução o problema foi introduzido.
Os rastreamentos resolvem esses desafios permitindo que você exiba as entradas e saídas de cada primitivo envolvido em uma execução de agente específica, exibidas na ordem em que foram invocadas, facilitando a compreensão e a depuração do comportamento do agente de IA.
Pré-requisitos
Para usar o rastreamento de ponta a ponta, você precisa:
- Um projeto do Foundry com o rastreamento habilitado. Para configurá-lo, consulte Como configurar o rastreamento no Microsoft Foundry.
- Acesso ao recurso do Application Insights conectado ao seu projeto. Para obter informações em segundo plano, consulte Azure Monitor Application Insights.
- Uma função de leitor do Log Analytics para visualizar rastreamentos, insights e visualizações no Foundry.
Nota
O rastreamento armazena dados de telemetria no Azure Monitor Application Insights, o que pode incorrer em custos com base nas configurações de volume e retenção de dados. Para obter detalhes sobre preços, consulte os preços do Application Insights.
OpenTelemetry na Foundry
O OpenTelemetry (OTel) fornece protocolos padronizados para coletar e rotear dados de telemetria. A Foundry usa convenções semânticas OpenTelemetry para que os rastreamentos sejam consistentes em ferramentas e integrações suportadas.
Rastrear os principais conceitos
Os seguintes conceitos principais se aplicam ao longo deste artigo:
| Principais conceitos | Descrição |
|---|---|
| Rastreamentos | Os rastreamentos capturam o percurso de uma solicitação ou fluxo de trabalho por meio de seu aplicativo registrando eventos e alterações de estado (chamadas de função, valores, eventos do sistema). Consulte Rastreamentos OpenTelemetry. |
| Abrange | Spans são os blocos de construção dos rastreamentos, representando operações individuais dentro de um rastreamento. Cada intervalo captura horários de início e término, atributos e pode ser aninhado para mostrar relações hierárquicas, para que você possa ver a pilha de chamadas completa e a sequência de operações. |
| Atributos | Atributos são pares de chave-valor anexados a rastreamentos e spans, fornecendo metadados contextuais, como parâmetros de função, valores de retorno ou anotações personalizadas. Eles enriquecem os dados de rastreamento, tornando-os mais informativos e úteis para análise. |
| Convenções semânticas | O OpenTelemetry define convenções semânticas para padronizar nomes e formatos para atributos de dados de rastreamento, facilitando a interpretação e a análise entre ferramentas e plataformas. Para saber mais, confira as convenções semânticas do OpenTelemetry GenAI. |
| Rastrear exportadores | Os exportadores de rastreamento enviam dados de rastreamento para sistemas de back-end para armazenamento e análise. No Foundry, os rastreamentos são armazenados no Azure Monitor Application Insights. Para saber como habilitar e exibir rastreamentos, consulte Como configurar o rastreamento no Microsoft Foundry. |
Como o rastreamento funciona na Foundry
O rastreamento ajuda você a responder perguntas como "De onde veio essa resposta?" e "Qual etapa introduziu um pico de erro ou latência?"
Em um nível macro, o rastreamento registra:
- Entradas do usuário e saídas de agente.
- Uso de ferramentas, incluindo chamadas de ferramenta e resultados.
- Consumo de token.
- Sinais de tempo, como duração e latência.
Ao habilitar o rastreamento para seu projeto, você pode inspecionar rastreamentos no portal do Foundry e no Azure Monitor Application Insights. Para obter as opções de configuração e exibição passo a passo, consulte Como configurar o rastreamento no Microsoft Foundry.
Estender o OpenTelemetry com a observabilidade de vários agentes
Microsoft, em colaboração com o Cisco Outshift, contribui com convenções semânticas para sistemas de vários agentes. Essas convenções se baseiam no agente e nos intervalos de estrutura do OpenTelemetry GenAI e no Contexto de Rastreamento W3C. Eles padronizam a telemetria para fluxos de trabalho de vários agentes, incluindo invocações de agente, orquestração de fluxo de trabalho, planejamento, chamadas de modelo e execução de ferramentas.
Importante
As convenções semânticas do OpenTelemetry GenAI têm status de desenvolvimento e podem mudar em versões futuras.
Esses aprimoramentos são integrados a:
- Fundição
- Estrutura do agente do Microsoft
- LangChain
- LangGraph
- SDK de agentes do OpenAI
Para obter mais informações, consulte integrações de rastreamento.
A tabela a seguir descreve convenções comuns do OpenTelemetry GenAI para observabilidade de vários agentes. Os spans capturam operações, os spans filho mostram operações aninhadas, e os atributos fornecem metadados. Os intervalos pai mostrados são exemplos comuns; o aninhamento real depende do agente ou da estrutura instrumentado.
| Tipo | Intervalo de contexto/pai | Nome/atributo/evento | Propósito |
|---|---|---|---|
| Intervalo | — | invoke_agent |
Invoca um agente por meio de um serviço remoto ou dentro do mesmo processo. |
| Intervalo filho | invoke_agent |
invoke_agent |
Rastreia uma invocação de outro agente por meio de uma relação pai-filho entre spans. |
| Intervalo filho | invoke_agent |
plan |
Registra a fase de planejamento ou de decomposição de tarefas de um agente. |
| Intervalo | — | invoke_workflow |
Invoca um fluxo de trabalho coordenado que contém agentes ou outras operações de IA generativas. |
| Intervalo filho |
invoke_agent ou invoke_workflow |
execute_tool |
Registra uma execução de uma ferramenta. |
| Intervalo filho |
invoke_agent ou invoke_workflow |
create_memory, search_memory, update_memory, upsert_memory ou delete_memory |
Registra uma operação de memória. |
| Atributo | invoke_agent |
gen_ai.tool.definitions |
Registra definições de ferramentas disponíveis para um agente ou modelo. |
| Atributo | execute_tool |
gen_ai.tool.call.arguments |
Registra os argumentos passados para uma chamada de ferramenta. |
| Atributo | execute_tool |
gen_ai.tool.call.result |
Registra o resultado retornado por uma chamada de ferramenta bem-sucedida. |
Práticas recomendadas
- Use atributos de intervalo consistentes: aplique os mesmos nomes e formatos de atributo em todos os agentes e ferramentas para simplificar a consulta e a análise.
- Correlacionar IDs de execução de avaliação: vincule dados de rastreamento com execuções de avaliação para analisar a qualidade e o desempenho em uma exibição unificada.
- Editar conteúdo confidencial: remova ou mascare dados pessoais, segredos e credenciais de prompts, argumentos de ferramenta e atributos de intervalo antes que eles alcancem a telemetria.
Segurança e privacidade
O rastreamento pode capturar informações confidenciais, como entradas do usuário, saídas de modelo e argumentos e resultados da ferramenta. Use estas práticas para reduzir o risco:
- Não armazene segredos, credenciais ou tokens em prompts, argumentos de ferramenta ou atributos de intervalo.
- Redigir ou minimizar dados pessoais e outros conteúdos confidenciais antes de serem exibidos na telemetria.
- Trate os dados de rastreamento como telemetria de produção e aplique os mesmos controles de acesso e políticas de retenção que você usa para logs e métricas.
Para saber as etapas para rotear conteúdo confidencial para a tabela dedicada e restringir o acesso a ela, consulte Restringir o acesso a conteúdo confidencial.
Solucionando problemas
Se os rastreamentos não estiverem aparecendo no portal do Foundry ou no Application Insights:
- Verifique se o projeto do Foundry está conectado a um recurso do Application Insights.
- Verifique se sua conta tem as permissões necessárias para consultar a telemetria.
- Assegure-se de que o código do agente inclua a instrumentação necessária. Para configuração específica da estrutura, consulte integrações de rastreamento.
Dica
O rastreamento está disponível em todas as regiões em que o Foundry tem suporte. Rastreie a retenção e a amostragem de dados seguindo a configuração do Application Insights. Para obter detalhes, consulte Data retention and archive in Azure Monitor Logs.