Conceitos de observabilidade do Agente 365

Este artigo explica o modelo de dados de observabilidade do Agent 365, incluindo quais dados de telemetria os agentes emitem, quem pode emiti-los, onde esses dados são armazenados e os limites aplicáveis. Use estes conceitos para planejar sua integração e entender a telemetria entre o Microsoft OpenTelemetry Distro, o obsoleto SDK de Observabilidade Agent 365 e o OTel direto.

Escolha seu caminho de integração

Três caminhos emitem o mesmo modelo de dados de span para o Agent 365. Escolha um:

Seja qual for o caminho escolhido, o modelo de dados, os modelos de identidade, os escopos, os limites e as superfícies downstream descritas abaixo se aplicam a todos.

Glossário de observabilidade do Agente 365

Como funciona a observabilidade do Agente 365

Para uma visão geral do Microsoft Agent 365 e da telemetria que ele coleta, veja Visão Geral do Microsoft Agent 365.

Você envia telemetria como dados de rastreamento do OpenTelemetry:

• Uma árvore de spans descrevendo uma execução (uma mensagem do usuário recebida e uma resposta do agente enviada).
• Cada intervalo descreve uma única etapa : a invocação de agente de nível superior, uma chamada LLM, uma chamada de ferramenta ou a resposta final.

Fluxo de dados de observabilidade do Agente 365

O diagrama a seguir mostra como a telemetria do agente passa pela autenticação e pela ingestão de observabilidade do Agent 365 até chegar às experiências do Microsoft 365 em etapas posteriores.

Modelos de identidade

Para obter uma explicação completa dos modelos de identidade de agente (registro padrão de aplicativo do Microsoft Entra vs. modelo de identidade de agente do ID do agente Microsoft Entra, incluindo companheiros de equipe de IA), consulte Identidade de agente. O modelo de identidade escolhido determina qual fluxo de autenticação e endpoint você usa.

Uma identidade de agente derivada do blueprint torna-se uma instância de agente registrada no Agente 365 somente após a conclusão do registro do Agente 365, como através de a365 setup all. Criar uma identidade Microsoft Entra sozinha não registra a instância. Registros padrão de aplicativos Microsoft Entra, como os usados por agentes de motores personalizados, não são instâncias de agente registradas.

Se o agente não tiver registro Microsoft Entra, ele não poderá usar essas rotas diretamente. Identifique o agente por meio dos atributos de ID alternativo (veja Referência de atributo) e entre em contato com a equipe do Agente 365 sobre o caminho de entrada apropriado.

Authentication

A autenticação depende se seu serviço se autentica a si mesmo ou autentica em nome de um usuário. Essa distinção determina o fluxo OAuth, a claim do token que carrega a permissão e a rota da URL.

• O serviço autentica a si mesmo: nenhum usuário conectado — autônomo, agendado ou acionado por eventos.

  • Fluxo de OAuth: credenciais de cliente serviço para serviço (S2S).
  • Reivindicação de token: roles. Uma identidade não registrada precisa da Agent365.Observability.OtelWrite função de aplicativo. Uma instância de agente registrada no Agent 365 pode usar um token exclusivo do app sem essa função.
  • Rota de URL: /observabilityService/....

• O serviço é autenticado em nome de um usuário: para colegas de IA ou para a conta de usuário do próprio agente.

  • Fluxo OAuth: Em nome de (OBO).
  • Reivindicação de token: scp.
  • Rota de URL: /observability/....

O mesmo aplicativo agente pode participar de ambos os fluxos, como, por exemplo, um colega de equipe de IA que também executa uma rotina noturna autônoma de sumarização. Para obter mais informações, consulte o fluxo OAuth de aplicativo autônomo e o fluxo em nome de.

Para ver as receitas completas de tokens para cada combinação de modelo de identidade e fluxo, consulte Receitas de autenticação no guia de integração.

A identidade do agente está associada à URL

O {agentId} na URL deve ser igual ao appId do aplicativo chamador (o appid ou azp claim no seu token). Incompatibilidades resultam em 403 Forbidden. Para identidades derivadas do blueprint, {agentId} é a appId da identidade do agente, não a appId do blueprint.

Além disso, todo intervalo que você enviar deve definir gen_ai.agent.id para o mesmo appId. O servidor valida a identidade do agente dentro do payload contra o agente autenticado e rejeita discrepâncias. Esta etapa detecta a mistura acidental de spans de vários agentes em uma única requisição.

Escopos e consentimento

Um escopo (delegado) ou uma função de aplicativo (aplicativo) é a permissão nomeada que o Microsoft Entra emite no token de acesso. Para a telemetria do Agent 365, a permissão é Agent365.Observability.OtelWrite no recurso de Observabilidade do Agent 365 (audience 9b975845-388f-4429-889e-eab1ef63949c).

O mesmo nome de permissão é registrado nos dois tipos:

• Função de aplicativo para identidades não registradas no fluxo autônomo (S2S / credenciais de cliente). Se enquadra na reivindicação roles. Selecionado por <resource>/.default.
• Escopo delegado para o fluxo OBO. Se enquadra na reivindicação scp. Selecionado por <resource>/Agent365.Observability.OtelWrite (ou <resource>/.default).

Na rota S2S, uma instância registrada no Agent 365 pode exportar com um token somente de aplicativo que não tem a função Agent365.Observability.OtelWrite. Não precisa de permissão de observabilidade ou consentimento do administrador para exportação de telemetria. Uma identidade não registrada ainda precisa do papel do app, e a rota delegada ainda precisa do escopo delegado mais consentimento do administrador.

O Agente 365 também disponibiliza uma permissão de leitura, Agent365.Observability.OtelRead, usada por operadores que consultam a telemetria do Agente 365. A maioria dos parceiros não precisa dele - esses documentos abrangem apenas a ingestão.

Adicione a permissão ao seu app

• Para um registro padrão de aplicativo Microsoft Entra: no portal Azure, adicione Agent365.Observability.OtelWrite em Permissões de API no registro do aplicativo do agente. Use a função de aplicativo para S2S e o escopo delegado para OBO.
• Para uma instância de agente derivada de blueprint na rota S2S: complete o registro do Agente 365 para a instância do agente. Uma instância registrada não precisa da permissão da API de Observabilidade ou do consentimento do administrador para exportar telemetria na rota S2S.
• Para uma instância de agente derivada do blueprint na rota delegada: adicione o escopo delegado Agent365.Observability.OtelWrite ao blueprint para que as instâncias do agente o herdem. Consulte Configurar permissões herdáveis para modelos de identidade de agente. Para adicioná-la com a CLI do Agente 365, veja permissões de observabilidade.

Consentimento do locatário

Antes de os tokens terem um papel ou escopo exigido, um administrador do locatário no locatário do cliente deve conceder consentimento. Consulte Conceder aos agentes acesso aos recursos do Microsoft 365.

Sem consentimento, a aquisição do token falha com AADSTS65001 (The user or administrator has not consented to use the application with ID...) ou o token é emitido sem a declaração roles ou scp, e o endpoint de ingestão rejeita a solicitação com 403.

Uma instância registrada no Agent 365 que exporta pela rota S2S não precisa do consentimento do administrador da Observabilidade. O consentimento ainda é exigido para identidades S2S não registradas que utilizam o papel do app e para todas as exportações de rotas delegadas que utilizam o escopo delegado.

Quando o consentimento é necessário, ele é concedido uma vez por locatário e se aplica a toda instância construída a partir de um blueprint a partir daí. Um novo consentimento é necessário apenas quando uma nova permissão é adicionada ao modelo.

Limites e condições de descarte

Conhecer esses limites desde o início evita surpresas durante a integração. Algumas falhas retornam um status HTTP bem-sucedido mesmo que a resposta informe que a telemetria não foi aceita.

Limites de nível de fio:

• Você deve incluir api-version=1 em cada pedido.
• O tamanho máximo do corpo da solicitação é 1 MB. Solicitações maiores retornam 413 Payload Too Large.
• As duas rotas têm limites de taxa separados. Em 429, respeite Retry-After (definido como 1 segundo) e aplique recuo com jitter.

Integrações de terceiros integradas que usam autenticação S2S podem chamar o endpoint de elegibilidade do locatário como uma verificação prévia opcional antes de enviar a telemetria. Quando você usa o endpoint, confie na decisão dele em vez de inferir a elegibilidade apenas pelo consentimento ou licenciamento. Uma enabled: false resposta significa que o inquilino não está elegível no momento. Um 503 Service Unavailable sem corpo significa que a elegibilidade não pôde ser determinada. Tente novamente conforme o cabeçalho Retry-After se ainda precisar de um resultado de elegibilidade.

Respostas de erro:

• 403 Forbidden: O token não tem a função do aplicativo ou o escopo exigido, ou {agentId} na URL não corresponde ao appid ou azp do seu token.
• 413 Payload Too Large: Corpo superior a 1 MB.
• 429 Too Many Requests: Limite de taxa atingido; honra Retry-After: 1 e recua com nervosismo.

Condições de descarte (solicitação aceita via HTTP, mas os dados não aparecem nas etapas posteriores):

A 200 OK não é prova de ingestão. Inspecione a results da resposta e use o fluxo de verificação para confirmar se os dados são recebidos.

Onde aparecem dados de observabilidade do Agente 365

Depois que você aceita os spans, eles aparecem em três experiências voltadas para o cliente. Todas as três experiências dependem de um span válido invoke_agent na raiz da execução. Uma sequência com apenas chat, execute_tool, ou output_messages spans pode ser consultada no Defender advanced hunting (a CloudAppEvents tabela), mas é invisível para todas as outras superfícies.

Próximas Etapas 

• Referência de atributo – especificação por atributo, requisitos e diretrizes de seleção de valor.
• Solução de problemas – verificação de ingestão, armadilhas comuns e respostas de erro.