Conceitos de observabilidade do Agent 365

Este artigo explica o modelo de dados por trás da observabilidade do Agent 365, o que os agentes de telemetria emitem, quem pode emitir, onde os dados chegam e os limites que se aplicam. Esses conceitos se aplicam a todos os caminhos de integração: a Microsoft OpenTelemetry Distro, o Agent 365 SDK e o OTel direto.

Observação

Detalhes em nível de conexão, as rotas de URL na Autenticação, os códigos de erro HTTP nos Limites e condições de descarte, e os limites de tamanho e taxa por requisição, se aplicam especificamente ao caminho do OTel direto. 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 span para o Agent 365. Escolha um:

  • Microsoft OpenTelemetry Distro - recomendado para novas integrações. SDK de observabilidade unificado para Agent 365, Microsoft Foundry, Azure Monitor e outros.
  • SDK do Agent 365 (SDK de Observabilidade) - o SDK anterior. Continua operando sem causar alterações interruptivas, mas não é mais o caminho recomendado para novas integrações; orientações de migração para usuários atuais do SDK estarão disponíveis em breve.
  • OTel Direto - o caminho de OTLP/HTTP bruto. Use-o apenas se você já tiver um pipeline de OpenTelemetry implementado, se o seu framework de agentes não puder usar o Agent 365 SDK ou se o seu agente estiver em uma linguagem que o SDK ainda não suporta (como Java).

Independentemente do caminho escolhido, o modelo de dados, os modelos de identidade, os escopos, os limites e as superfícies downstream descritos abaixo se aplicam.

Glossário

  • ID do aplicativo (appId): o identificador do aplicativo emitido ao registrar um aplicativo do Microsoft Entra ou uma identidade de agente com ID de agente do Microsoft Entra.
    • Igual ao OAuth client_id, não à 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: uma sequência lógica de interações entre agentes, como um chat no 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 spans OTel compartilhando um traceId.

Como funciona

Para obter uma visão geral do Agent 365 e dos destinos da telemetria, consulte Visão Geral do Microsoft Agent 365.

Você envia a telemetria como dados de rastreamento do OpenTelemetry:

  • Uma árvore de intervalos descrevendo uma execução (uma mensagem de usuário, uma resposta do agente).
  • Cada intervalo descreve uma etapa específica, a invocação principal do agente, 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 uma explicação completa dos modelos de identidade do agente (registro padrão de aplicativos Microsoft Entra vs. blueprint de identidade de agente de ID do Agente do Microsoft Entra, incluindo colegas de equipe de IA), consulte Introdução ao desenvolvimento do Agent 365. Sua escolha de modelo de identidade determina qual fluxo de autenticação e ponto de extremidade você usa.

Se seu agente não tem registro no Microsoft Entra, ele não pode usar essas rotas diretamente. Identifique o agente por meio dos atributos de ID alternativo (consulte Referência de atributo) e entre em contato com a equipe do Agent 365 sobre o caminho de entrada apropriado.

Autenticação

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

  • O serviço se autentica por conta própria: nenhum usuário autenticado, autônomo, agendado ou orientado a eventos.

    • Fluxo do OAuth: credenciais de cliente Serviço a serviço (S2S).
    • Declaração de token: roles.
    • Rota da URL: /observabilityService/....

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

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

O mesmo aplicativo 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 obter os modelos completos de tokens para cada combinação de modelo de identidade e fluxo, consulte Modelos completos de autenticação no Guia de Integração.

A identidade do agente é vinculada à URL

O {agentId} na URL deve ser igual ao appId do aplicativo de chamada (o appid ou declaração azp no seu token). Incompatibilidades retornam 403 Forbidden. Para identidades derivadas de blueprint, {agentId} é o appId da identidade do agente, não o appId do blueprint.

Além disso, cada span que você enviar deve definir gen_ai.agent.id como o mesmo appId. O servidor valida a identidade do agente no conteúdo em relação ao 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 para ambos os tipos:

  • Função de aplicativo para o fluxo autônomo (S2S / credenciais do 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).

O Agent 365 também expõe uma permissão de leitura, Agent365.Observability.OtelRead, usada por operadores que realizam consultas na telemetria do Agent 365. A maioria dos parceiros não precisa dessa permissão, esses documentos abrangem somente 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 (função de aplicativo para S2S, escopo para permissões delegadas) em Permissões de API no registro de aplicativo do agente.
  • Para um blueprint: os agentes gerados a partir de um blueprint de identidade de agente do ID do agente Microsoft Entra herdam as permissões do OAuth definidas no blueprint, para que um administrador do locatário provisione previamente as permissões uma única vez. Cada instância de agente criada a partir desse blueprint recebe as permissões automaticamente. Consulte Configurar permissões herdadas para blueprints de identidade de agente.

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

Sem consentimento, a aquisição de token falha com AADSTS65001 ("o usuário ou administrador não concedeu consentimento") ou o token é emitido sem a reivindicação roles / scp e o ponto de extremidade de ingestão rejeita a solicitação com 403.

O consentimento é concedido uma vez por locatário e aplica-se a todas as instâncias criadas de um blueprint. A renovação do consentimento só é necessária quando uma nova permissão é adicionada ao blueprint.

Limites e condições de descarte

Conhecer esses limites desde o início evita surpresas durante a integração, a maioria é silenciosa (a API aceita a solicitação, mas os dados nunca aparecem no destino).

Limites em nível de transmissão:

  • api-version=1 é obrigató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 possuem limites de taxa separados. Em 429, respeite Retry-After (definido como 1 segundo) e use uma estratégia de backoff com jitter.

Respostas de erro:

  • 403 Forbidden– token sem a função de aplicativo/escopo necessário, ou a {agentId} na URL não corresponde à appid / azp do seu token.
  • 413 Payload Too Large--corpo ultrapassa 1 MB.
  • 429 Too Many Requests– limite de taxa atingido; respeite Retry-After: 1 e use uma estratégia de backoff com jitter.

Condições de descarte (solicitação aceita pelo HTTP, mas os dados não aparecem nos sistemas posteriores):

# Condição Comportamental
1 Intervalo 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 possui uma licença do Microsoft 365 E7 ou do Microsoft Agent 365 atribuída. 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 do back-end do Defender). O usuário licenciado não precisa ser necessariamente a pessoa que está chamando o agente. Toda a solicitação é silenciosamente descartada. Retorna 200 { "partialSuccess": null }.

Um código 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 span válido invoke_agent na raiz da execução. Uma execução somente com spans chat / execute_tool / output_messages pode ser consultada na busca avançada do Defender (na tabela CloudAppEvents), mas é invisível em todas as outras superfícies abaixo.

Microsoft Defender. 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 dos campos visíveis para o cliente são mapeados diretamente aos atributos de intervalo enviados ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, e assim por diante. Consulte Referência de atributos 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 somente linhas invoke_agent: os agentes sem telemetria invoke_agent não aparecem no estoque e as execuções que emitem somente chat / execute_tool / output_messages ficam invisíveis aqui. Os atributos que o Centro de administração lê (ID do agente, nome do agente, ID do blueprint, identidade do chamador, ID da conversa, canal, status de erro) vêm do span invoke_agent.

Microsoft Purview. A atividade de agentes também é apresentada aos administradores de conformidade no Microsoft Purview, onde eles podem configurar regras de tratamento de dados e políticas sobre execuções de agentes (prevenção de perda de dados, retenção, conformidade de comunicação e similares). 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

  • Last updated on