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 esses conceitos para planejar sua integração e entender a telemetria entre a Microsoft OpenTelemetry Distro, o Agent 365 SDK e a OTel direta.

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 span para o Agent 365. Escolha um:

Caminho Description
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.
OTel Direto 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 de observabilidade do Agente 365

Prazo 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 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 a observabilidade do Agente 365

Para uma visão geral do 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.

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 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).
    • Declaraçã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).
    • Declaração de token: scp.
    • Rota de 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 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 (o appid ou declaração azp 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 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 nos dois tipos:

  • Função do 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 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 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 da 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 automaticamente. Consulte Configurar permissões herdáveis para modelos de identidade de agente.

Antes que os tokens incluam a função ou o escopo, é necessário que um administrador do tenant do cliente conceda 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.

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 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 o 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 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.

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 

  • Last updated on