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 SDK de Observabilidade Agent 365 preterido e o OTel direto.

Note

Os detalhes no nível do protocolo — as rotas de URL em Autenticação, os códigos de erro HTTP em Limites e condições de descarte e os limites de tamanho e taxa por solicitação — aplicam-se especificamente ao caminho direto do OTel. O SDK e a distro abstraem isso para você. O restante deste artigo (glossário, fluxo de dados, modelos de identidade, escopos, condições de descarte, onde os dados são exibidos) se aplica a cada caminho.

Escolha seu caminho de integração

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

Path Description
Microsoft OpenTelemetry Distro Recomendado para novas integrações. SDK de observabilidade unificada no Agente 365, Microsoft Foundry, Azure Monitor e muito mais.
SDK de Observabilidade do Agente 365 descontinuado O SDK legado. Integrações existentes continuam funcionando, mas não use isso para novas integrações. O artigo inclui guias de migração.
OTel Direto O caminho OTLP/HTTP bruto. Use apenas se você já tiver um pipeline OpenTelemetry implementado, se seu framework de agente não puder usar a distro Microsoft OpenTelemetry ou se seu agente estiver em uma linguagem que a distribuição ainda não suporta (como Java).

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

Term Description
ID do aplicativo (appId) O identificador do aplicativo é emitido quando um aplicativo Microsoft Entra ou identidade de agente do Microsoft Entra Agent ID é registrado.
- Igual ao OAuthclient_id, não ao ID do objeto Microsoft Entra.
- Ao longo desta documentação, "ID do agente" e "ID do blueprint" ambos se referem a um appId.
Conversa Uma sequência lógica de interações de agentes, como uma thread de chat do Teams.
- Identificado por gen_ai.conversation.id.
- A chave principal de junção para uma execução.
Channel A superfície em que o agente corre: msteams, outlook, web, e assim por diante.
Executar Uma mensagem do usuário recebida e uma resposta do agente enviada. Modelado como uma árvore de intervalos de OTel compartilhando um traceId.

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.

Diagrama de fluxo de dados de observabilidade do Agente 365.

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).
    • Declaração de token: roles. Uma identidade não registrada precisa da função do aplicativo Agent365.Observability.OtelWrite. 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).
    • Declaração de token: scp.
    • Rota de URL: /observability/....

O mesmo aplicativo do agente pode participar de ambos os fluxos, por exemplo, um colega de equipe de IA que também executa uma passagem noturna autônoma de resumo. Para obter mais informações, consulte fluxo do 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 de chamada (a declaração appid ou azp no 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 no payload contra o agente autenticado e rejeita incompatibilidades. Esta etapa detecta a mistura acidental de spans de vários agentes em uma única solicitação.

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 Observabilidade do Agent 365 (audiência 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). Chega à declaração roles. Selecionado por <resource>/.default.
  • Escopo delegado para o fluxo OBO. Chega à declaração scp. Selecionado por <resource>/Agent365.Observability.OtelWrite (ou <resource>/.default).

Na rota S2S, uma instância do agente 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 sob 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.

Antes que os tokens incluam uma função ou um escopo obrigatório, um administrador de locatários 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 use uma estratégia de retirada 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 de acordo com o cabeçalho Retry-After caso ainda precise 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):

# Condition Behavior
1 Span gen_ai.operation.name ausente ou não está em {invoke_agent, execute_tool, chat, output_messages} Descarte por span. Exibido em partialSuccess.rejectedSpans + errorMessage.
2 Nenhum usuário no locatário do cliente tem atribuída uma licença Microsoft 365 E7 ou Microsoft Agent 365. Pelo menos um usuário no locatário deve ter a licença atribuída (a presença do SKU no locatário não é suficiente — a atribuição inicia o fluxo de trabalho de back-end do Defender). O usuário licenciado não precisa ser a pessoa que faz a chamada para o agente. A solicitação retorna 200 OK, mas cada span tem uma entrada results com status rejected e o motivo tenant_not_licensed.

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

Onde aparecem dados de observabilidade do Agente 365

Depois que você aceita os intervalos, eles aparecem em três experiências voltadas para o cliente. Todas as três experiências dependem de um intervalo de invoke_agent válido 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.

Experience Description
Microsoft Defender A atividade do agente (invoke_agent, execute_tool, chat) aparece nas visualizações de atividade do agente. Os administradores de locatários e analistas de segurança podem analisar execuções individuais, ferramentas e chamadas de inferência. As exibições de atividade do agente usam o span invoke_agent. Sem ele, a execução não aparece lá, embora os spans filho ainda possam ser consultados por meio da busca avançada. A exibição da busca avançada — CloudAppEvents — aceita todas as operações: ActionType reflete a operação (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer), e os campos por span estão dentro de RawEventData. Os nomes de campo visíveis ao cliente são mapeados diretamente para os atributos de intervalo que você enviou: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.ide assim por diante. Consulte a referência de atributo para o mapeamento completo.
Centro de administração do Microsoft 365 A atividade do agente também aparece nas exibições de estoque de agentes e de segurança usadas pelos administradores de locatários para controlar os agentes em seu locatário. O Centro de administração ingere invoke_agentsomente linhas: os agentes sem telemetria invoke_agent não aparecem no estoque e as execuções que emitem somente chat, execute_tool ou output_messages ficam invisíveis aqui. O Centro de administração lê atributos como ID do agente, nome do agente, ID do blueprint, identidade do chamador, ID da conversa, canal e status de erro vêm do span invoke_agent.
Microsoft Purview A atividade dos agentes também fica visível para os administradores de conformidade no Microsoft Purview, onde eles podem configurar regras de tratamento de dados e políticas aplicáveis às execuções de agentes (prevenção contra perda de dados, retenção, conformidade de comunicações, entre outros). Os atributos que as políticas do Purview usam (ID do agente, ID do blueprint, identidade do chamador, conversa, canal, mensagens de solicitação e de resposta) vêm do span invoke_agent e de seus descendentes.

Próximas Etapas 

  • Última atualização em