Conceitos de observabilidade do Agent 365

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

Nota

Os detalhes ao nível da ligação – as rotas de URL em Autenticação, os códigos de erro HTTP em Limites e condições de remoção, e os limites de tamanho e taxa por pedido – aplicam-se especificamente ao caminho de OTel direto. O SDK e o Distro abstraem estes detalhes. O restante deste artigo (glossário, fluxo de dados, modelos de identidade, âmbitos, condições de remoção, onde os dados são apresentados) aplica-se a todos os caminhos.

Escolher o 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 unificado de observabilidade para Agent 365, Microsoft Foundry, Azure Monitor e outros.
  • SDK do Agent 365 (SDK de Observabilidade) - o SDK anterior. Continua a funcionar sem alterações interruptivas, mas já não é o caminho recomendado para novas integrações; orientações de migração para utilizadores existentes do SDK estão a caminho.
  • OTel direto - o caminho OTLP/HTTP não processado. Utilize-o apenas se já tiver um pipeline OpenTelemetry implementado, se a sua estrutura de agentes não puder utilizar o SDK do Agent 365, ou se o seu agente estiver numa linguagem que o SDK ainda não suporta (como Java).

Qualquer que seja o caminho escolhido, o modelo de dados, os modelos de identidade, os âmbitos, os limites e as superfícies a jusante descritos abaixo aplicam-se.

Glossário

  • ID da aplicação (appId): O identificador da aplicação emitido quando uma aplicação Microsoft Entra ou uma identidade de agente com ID do Agente Microsoft Entra é registada.
    • Igual ao client_id do OAuth, e não ao ID do objeto Microsoft Entra.
    • Ao longo destes documentos, "id de agente" e "id de esquema" referem-se ambos a um appId.
  • Conversação: Uma thread lógica de interações com agentes, como uma thread de chat no Teams.
    • Identificado pelo gen_ai.conversation.id.
    • A chave de associação primária para uma execução.
  • Canal: A superfície onde o agente é executado: msteams, outlook, web e assim sucessivamente.
  • Executar: Uma mensagem de utilizador de entrada, uma resposta de agente de saída. Modelada como uma árvore de spans OTel que partilham um traceId.

Como funciona

Para uma descrição geral do Agent 365 e dos destinos da telemetria, consulte Descrição Geral do Microsoft Agent 365.

A telemetria é enviada como dados de rastreio do OpenTelemetry:

  • Uma árvore de spans que descreve uma execução (uma mensagem de utilizador de entrada, uma resposta de agente de saída).
  • Cada span descreve um único passo – a invocação de agente de nível superior, uma chamada ao 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 de agentes (registo de aplicação Microsoft Entra padrão vs. esquema de identidade de agente do ID do Agente Microsoft Entra, incluindo colegas de IA), consulte Introdução ao desenvolvimento com o Agent 365. A sua escolha de modelo de identidade determina qual o fluxo de autenticação e qual o ponto final que irá utilizar.

Se o seu agente não tiver um registo no Microsoft Entra, não poderá utilizar estas rotas diretamente. Identifique o agente usando os atributos de ID alternativos (consulte Referência de atributos) e contacte a equipa do Agent 365 sobre o caminho de ingresso apropriado.

Autenticação

A autenticação ramifica-se consoante o serviço se autentica a si próprio ou em nome de um utilizador. O ramo determina o fluxo OAuth, a afirmação do token que transporta a permissão e a rota do URL.

  • O Service autentica-se a si próprio: Sem utilizador com sessão iniciada — autónomo, agendado ou condicionado por eventos.

    • Fluxo OAuth: Credenciais de cliente Service-to-service (S2S)
    • Afirmação do token: roles.
    • Rota do URL: /observabilityService/....

  • O Service autentica-se em nome de um utilizador: Para colegas de IA ou para a própria conta de utilizador do agente.

    • Fluxo OAuth: On-behalf-of (OBO).
    • Afirmação do token: scp.
    • Rota do URL: /observability/....

A mesma aplicação de agente pode participar em ambos os fluxos, como um colega de IA que também executa um processo de resumo autónomo noturno. Para mais informações, consulte fluxo OAuth de aplicação autónoma e fluxo on-behalf-of.

Para obter as configurações completas de tokens para cada combinação de modelo de identidade e fluxo, consulte Configurações de Autenticação no guia de integração.

A identidade do agente está vinculada ao URL

O {agentId} no URL deve ser igual ao appId da aplicação chamadora (a afirmação appid ou azp no seu token). As discrepâncias devolvem 403 Forbidden. Para identidades derivadas de esquema, o {agentId} é o appId da identidade do agente e não ao appId do esquema.

Além disso, cada span que enviar deve definir gen_ai.agent.id para o mesmo appId; o servidor valida a identidade do agente em payload em relação ao agente autenticado e rejeita as discrepâncias. Este passo deteta misturas acidentais de spans de múltiplos agentes num único pedido.

Um âmbito (delegado) ou a função de aplicação (aplicação) é 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 (audiência 9b975845-388f-4429-889e-eab1ef63949c).

O mesmo nome de permissão está registado como ambos os tipos:

  • Função de aplicação para o fluxo autónomo (S2S / credenciais do cliente). É incluída na afirmação roles. Selecionada por <resource>/.default.
  • Âmbito delegado para o fluxo OBO. É incluído na afirmaçã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, utilizada por operadores que consultam a telemetria do Agent 365. A maioria dos parceiros não precisa desta permissão — esta documentação aborda apenas a ingestão.

Adicionar a permissão à sua aplicação

  • Para um registo de aplicação padrão do Microsoft Entra: no portal do Azure, adicione Agent365.Observability.OtelWrite (função de aplicação para S2S, âmbito para delegado) nas permissões de API no registo de aplicação do agente.
  • Para um esquema: os agentes gerados a partir de um esquema de identidade de agente do ID do Agente Microsoft Entra herdam as permissões OAuth definidas no esquema, pelo que um administrador do inquilino aprovisiona previamente as permissões apenas uma vez. Cada instância de agente criada a partir desse esquema recebe-as automaticamente. Consulte Configurar permissões herdáveis para esquemas de identidade de agentes.

Antes de os tokens transportarem a função / o âmbito, um administrador do inquilino no inquilino do cliente tem de conceder consentimento. Consulte Conceder acesso aos agentes aos recursos do Microsoft 365.

Sem consentimento, a aquisição do token falha com AADSTS65001 ("o utilizador ou o administrador não consentiu") ou o token é emitido sem a afirmação roles / scp e o ponto final de ingestão rejeita o pedido com 403.

O consentimento é concedido uma única vez por inquilino e aplica-se a todas as instâncias criadas a partir de um esquema daí em diante. Voltar a conceder consentimento só é necessário quando uma nova permissão é adicionada ao esquema.

Limites e condições de remoção

Conhecer estes limites antecipadamente evita surpresas durante a integração — na maioria dos casos, são silenciosos (a API aceita o pedido, mas os dados nunca aparecem a jusante).

Limites ao nível da ligação:

  • api-version=1 é obrigatório em todos os pedidos.
  • O tamanho máximo do corpo do pedido é 1 MB. Pedidos maiores obtêm 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--o token não contém a função de aplicação / o âmbito necessários, ou o {agentId} no URL não corresponde ao appid / azp do seu token.
  • 413 Payload Too Large--o corpo excede 1 MB.
  • 429 Too Many Requests--limite de taxa atingido; respeite Retry-After: 1 e aplique recuo com jitter.

Condições de remoção (pedido aceite por HTTP mas os dados não aparecem a jusante):

# Condição Comportamento
1 Span gen_ai.operation.name em falta ou não incluído em {invoke_agent, execute_tool, chat, output_messages} Remoção por span. Aparece em partialSuccess.rejectedSpans + errorMessage.
2 Nenhum utilizador no inquilino do cliente tem uma licença Microsoft 365 E7 ou Microsoft Agent 365 atribuída. Pelo menos um utilizador no inquilino deve ter a licença atribuída (a presença do SKU no inquilino não é suficiente – a atribuição inicia o fluxo de trabalho do back-end do Defender). O utilizador licenciado não tem de ser o chamador humano do agente. Pedido inteiro silenciosamente removido. Devolve 200 { "partialSuccess": null }.

Um 200 OK não é prova de ingestão. Utilize o fluxo de verificação para confirmar que os dados foram ingeridos.

Onde aparecem os seus dados

Depois de aceites, os seus spans aparecem em três experiências visíveis para o cliente. Os três dependem de um span invoke_agent válido na raiz da execução. Uma execução contendo apenas spans de chat / execute_tool / output_messages fica consultável na investigação avançada do Defender (a tabela CloudAppEvents), mas permanece invisível para todas as outras superfícies abaixo.

Microsoft Defender. A atividade do agente (invoke_agent, execute_tool, chat) aparece nas vistas de atividade do agente. Os administradores de inquilinos e os analistas de segurança podem aprofundar execuções individuais, ferramentas e chamadas de inferência. As vistas de atividade do agente baseiam-se no span invoke_agent; sem ele, a execução não aparece nessas superfícies, mesmo que os spans subordinados continuem consultáveis via investigação avançada. A vista de investigação 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 correspondem diretamente aos atributos de span que enviou: 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 vistas de inventário de agentes e de segurança, utilizadas pelos administradores do inquilino para governar agentes no respetivo inquilino. O centro de administração ingere apenas linhas de invoke_agent: os agentes sem telemetria invoke_agent não aparecem no inventário e execuções que emitem apenas chat / execute_tool / output_messages são invisíveis aqui. Os atributos que o centro de administração lê (id do agente, nome do agente, id do esquema, identidade do chamador, id da conversação, canal, estado do erro) vêm todos do span invoke_agent.

Microsoft Purview. A atividade do agente também é apresentada aos administradores de conformidade no Microsoft Purview, onde podem configurar regras de processamento de dados e políticas sobre execuções de agentes (prevenção de perda de dados, retenção, conformidade de comunicações, entre outros). Os atributos nos quais as políticas do Purview se baseiam (id de agente / id de esquema, identidade do chamador, conversação / canal, mensagens de pedidos e de respostas) vêm todos do span invoke_agent e dos seus descendentes.

Passos seguintes

  • Last updated on