Conceitos de observabilidade do Agente 365

Este artigo explica o modelo de dados por trás da observabilidade do Agente 365 – quais agentes de telemetria emitem, quem pode emitê-lo, onde ele aterrissa e os limites que se aplicam. Esses conceitos se aplicam ao caminho de integração every: o Microsoft OpenTelemetry Distro, o SDK Agent 365 e direct OTel.

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 aparecem) se aplica a cada percurso.

Escolha seu caminho de integração

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

  • Microsoft OpenTelemetry Distro - recomendado para novas integrações. SDK de observabilidade unificada no Agente 365, Microsoft Foundry, Azure Monitor e muito mais.
  • SDK do Agente 365 (SDK de Observabilidade) – o SDK anterior. Continua funcionando sem mudanças significativas, mas não é mais a abordagem recomendada para novas integrações; as diretrizes de migração para usuários atuais do SDK serão publicadas em breve.
  • Direct OTel - o caminho OTLP/HTTP bruto. Use-o somente se você já tiver um pipeline OpenTelemetry em vigor, sua estrutura de agente não poderá usar o SDK do Agent 365 ou seu agente estiver em um idioma que o SDK ainda não dá suporte (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

  • App id (appId): o identificador de aplicativo emitido quando um aplicativo Microsoft Entra ou ID do agente Microsoft Entra identidade do agente está registrado.
    • Igual ao OAuth client_id, não ao ID do objeto do Microsoft Entra.
    • Ao longo desta documentação, "id do agente" e "id do blueprint" ambos se referem a um appId.
  • Conversa: Um encadeamento lógico de interações de agente, como uma conversa de chat do Teams.
    • Identificado por gen_ai.conversation.id
    • A chave de junção primária para uma execução.
  • Canal: A superfície na qual o agente é executado: msteams, outlook, web, e assim por diante.
  • Execução: entra uma mensagem do usuário, sai uma resposta do agente. Modelada como uma árvore de OTel spans compartilhando um traceId.

Como funciona

Para obter uma visão geral do Microsoft Agent 365 e do que a telemetria alimenta, consulte 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

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

Modelos de identidade

Para obter uma explicação completa dos modelos de identidade de agente (registro de aplicativo padrão do Microsoft Entra versus blueprint de identidade de agente do ID do agente Microsoft Entra, incluindo colegas de IA), consulte Introdução ao desenvolvimento do Agent 365. O modelo de identidade escolhido determina qual fluxo de autenticação e endpoint você usa.

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 alternativos (consulte referência de atributo) e entre em contato com a equipe do Agent 365 sobre o caminho de entrada apropriado.

Authentication

A autenticação depende de se o serviço autentica a si próprio ou em nome de um usuário. O branch determina o fluxo OAuth, a declaração de token que carrega a permissão e a rota de 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.
    • 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, cada span que você enviar deve definir gen_ai.agent.id com o mesmo appId; o servidor valida a identidade do agente no payload em relação ao agente autenticado e rejeita correspondências incorretas. Esta etapa detecta a mistura acidental de spans de vários agentes em uma única requisiçã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 de Observabilidade do Agent 365 (audience 9b975845-388f-4429-889e-eab1ef63949c).

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

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

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.

Adicionando a permissão ao seu aplicativo

  • Para um registro de aplicativo padrão do Microsoft Entra: no portal do Azure, adicione Agent365.Observability.OtelWrite (Agent365.Observability.OtelWritefunção de aplicativo para S2S, escopo para permissões delegadas) em Permissões de API no registro de aplicativo do agente.
  • Para um modelo: os agentes gerados a partir de um modelo de identidade de agente do ID do agente Microsoft Entra herdam as permissões OAuth definidas no modelo, de modo que um administrador do locatário provisiona previamente as permissões uma única vez. Cada instância de agente criada a partir desse blueprint recebe-as automaticamente. Consulte Configurar permissões herdáveis para modelos de identidade de agente.

Antes que os tokens carreguem a função/escopo, um administrador de locatário no locatário do cliente deve conceder consentimento. Consulte Conceder aos agentes acesso aos recursos do Microsoft 365.

Sem consentimento, a obtenção do token falha com AADSTS65001 ("o usuário ou o administrador não concedeu consentimento") ou o token é emitido sem a declaração roles / scp, e o endpoint de ingestão rejeita a requisição com 403.

O consentimento é concedido uma vez por locatário e se aplica a todas as instâncias criadas a partir de um blueprint depois disso. Um novo consentimento é necessário apenas quando uma nova permissão é adicionada ao modelo.

Limites e condições de descarte

Conhecer esses limites antecipadamente evita surpresas durante a integração – a maioria é silenciosa (a API aceita a solicitação, mas os dados nunca aparecem downstream).

Limites de nível de fio:

  • api-version=1 é necessário em cada solicitação.
  • O tamanho máximo do corpo da solicitação é de 1 MB. Solicitações maiores recebem 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.

Respostas de erro:

  • 403 Forbidden--token sem a função/escopo de aplicativo necessário, ou {agentId} na URL não corresponde ao appid / azp do seu token.
  • 413 Payload Too Large--body excede 1 MB.
  • 429 Too Many Requests--limite de taxa atingido; respeite Retry-After: 1 e aplique recuo com variação aleatória.

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} Queda por intervalo. 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. Toda a solicitação foi descartada silenciosamente. Retorna 200 { "partialSuccess": null }.

Um 200 OK não é prova de ingestão. Use o fluxo de verificação para confirmar que os dados chegaram.

Onde seus dados são exibidos

Depois de aceitos, seus spans aparecem em três experiências voltadas ao cliente. Os três dependem de um intervalo válido invoke_agent na raiz da execução. Uma execução com apenas segmentos chat / execute_tool / output_messages pode ser consultada na Busca Avançada do Defender (na tabela CloudAppEvents), mas é invisível em todas as outras interfaces abaixo.

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 dependem do invoke_agent span; sem ele, a execução não aparece lá, embora os spans filho ainda possam ser consultados por meio da busca avançada. A visualização de 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 inventário de agente e segurança usadas pelos administradores de locatários para controlar os agentes em seu locatário. O centro de administração ingere apenas linhasinvoke_agent: agentes sem invoke_agent telemetria não aparecem no inventário e as execuções que emitem sóchat / execute_tool / output_messagessão invisíveis aqui. Os atributos que a Central de administração lê (ID do agente, nome do agente, ID do modelo, identidade do chamador, ID da conversa, canal, status de erro) vêm da tag invoke_agent span.

Microsoft Purview. A atividade do agente também é exibida para administradores de conformidade no Microsoft Purview, em que eles podem configurar regras de tratamento de dados e políticas em execuções de agente (prevenção contra perda de dados, retenção, conformidade de comunicação e similares). Os atributos nos quais as políticas do Purview se baseiam (ID do agente / ID do blueprint, identidade do chamador, conversa / canal, mensagens de solicitação e resposta) vêm do span invoke_agent e de seus descendentes.

Próximas Etapas 

  • Last updated on