Concetti di osservabilità dell'agente 365

Questo articolo spiega il modello di osservabilità dell'Agente 365, inclusi ciò che gli agenti emettono in telemetria, chi può emetterlo, dove atterra e i limiti applicabili. Usa questi concetti per pianificare la tua integrazione e comprendere la telemetria tra la Microsoft OpenTelemetry Distro, il obsoleto Agent 365 Observability SDK e l'OTel diretto.

Note

Dettagli a livello di protocollo: i percorsi URL in Authentication, i codici di errore HTTP in Limits and drop conditions e i limiti di dimensione e di frequenza per richiesta si applicano specificamente al percorso diretto di OTel. L’SDK e la distribuzione si occupano di astrarre questi dettagli per te. Il resto di questo articolo (glossario, flusso di dati, modelli di identità, ambiti, condizioni di rilascio, dove vengono visualizzati i dati) si applica a ogni percorso.

Selezionare il percorso di integrazione

Tre percorsi generano lo stesso modello di dati span in Agent 365. Selezionarne uno:

Path Description
Distribuzione Microsoft OpenTelemetry Consigliato per nuove integrazioni. SDK di osservabilità unificata in Agent 365, Microsoft Foundry, Monitoraggio di Azure e altro ancora.
SDK di osservabilità deprecato di Agent 365 L'SDK legacy. Le integrazioni esistenti continuano a funzionare, ma non usarle per nuove integrazioni. L'articolo include guide alla migrazione.
Direct OTel Il percorso OTLP/HTTP diretto. Usalo solo se hai già una pipeline OpenTelemetry attiva, se il framework degli agenti non può usare la distro OpenTelemetry di Microsoft, o se il tuo agente è in un linguaggio che la distribuzione non supporta ancora (come Java).

A qualsiasi percorso scelto, il modello di dati, i modelli di identità, gli ambiti, i limiti e le superfici downstream descritte di seguito si applicano tutti.

Glossario di osservabilità dell'Agente 365

Termine Description
ID dell'app (appId) L'identificativo dell'applicazione viene rilasciato quando viene registrata un'app Microsoft Entra o un'identità di agente Microsoft Entra Agent ID.
- Uguale all'OAuthclient_id, non all'ID oggetto Microsoft Entra.
- In tutta questa documentazione, "agent id" e "blueprint id" significano entrambi un appId.
Conversazione Un filo logico di interazioni con gli agenti, come una chat su Teams.
- Identificato da gen_ai.conversation.id.
- La chiave primaria di join per una run.
Channel La superficie su cui corre l'agente: msteams, outlook, web, e così via.
Esegui Un messaggio dell’utente in ingresso, una risposta dell’agente in uscita. Modellato come un albero di OTel span che condividono un traceId.

Come funziona l'osservabilità dell'Agente 365

Per una panoramica di Agent 365 e della telemetria che raccoglie, vedi Panoramica di Microsoft Agent 365.

I dati di telemetria vengono inviati come dati di traccia OpenTelemetry:

  • Un albero di span che descrive un run (un messaggio dell'utente in input, una risposta dell'agente in output).
  • Ogni intervallo descrive un singolo passaggio, ovvero la chiamata dell'agente di primo livello, una chiamata LLM, una chiamata allo strumento o la risposta finale.

Flusso di dati di osservabilità dell'Agente 365

Il diagramma seguente mostra come la telemetria degli agenti fluisce attraverso l'autenticazione e l'acquisizione dei dati di osservabilità di Agent 365 fino alle esperienze di Microsoft 365 a valle.

Diagramma di flusso dei dati di osservabilità dell'Agente 365.

Modelli di identità

Per una spiegazione completa dei modelli di identità degli agenti (registrazione standard dell'app Microsoft Entra vs. blueprint dell'identità dell'agente Microsoft Entra Agent ID, inclusi i compagni di squadra AI), vedi Identità dell'agente. La scelta del modello di identità determina il flusso di autenticazione e l'endpoint usati.

Un'identità di agente derivata dal blueprint diventa un'istanza di agente registrata in Agent 365 solo dopo il completamento della registrazione in Agent 365, ad esempio tramite a365 setup all. Creare un'identità Microsoft Entra da sola non registra l'istanza. Le registrazioni standard delle app Microsoft Entra, come quelle usate dagli agenti custom engine, non sono istanze di agenti registrati.

Se l'agente non ha Microsoft Entra registrazione, non può usare direttamente queste route. Identifica l'agente tramite gli attributi ID alternativi (vedi riferimento attributo) e contatta il team dell'Agente 365 riguardo al percorso di ingresso appropriato.

Authentication

L'autenticazione dipende dal fatto che il tuo servizio si autentichi da solo o autentichi per conto di un utente. Questa distinzione determina il flusso OAuth, la claim del token che porta il permesso e la rotta URL.

  • Il servizio si autentica: nessun utente connesso - autonomo, pianificato o basato su eventi.

    • Flusso OAuth: credenziali client Da servizio a servizio (S2S).
    • Attestazione del token: roles. Un'identità non registrata ha bisogno del ruolo dell'app Agent365.Observability.OtelWrite . Un'istanza di agente registrato con Agent 365 può utilizzare un token solo per l'app senza quel ruolo.
    • Percorso URL: /observabilityService/....

  • Il servizio esegue l'autenticazione per conto di un utente: per i colleghi di intelligenza artificiale o per il proprio account utente dell'agente.

    • Flusso OAuth: (on-behalf-of, OBO).
    • Attestazione del token: scp.
    • Percorso URL: /observability/....

La stessa app agente può partecipare a entrambi i flussi, ad esempio un compagno di intelligenza artificiale che esegue anche un passaggio di riepilogo autonomo notturno. Per ulteriori informazioni, vedi flusso OAuth dell'app autonoma e flusso On-Behalf-Of.

Per le ricette complete dei token per ogni combinazione di modello di identità e flusso, vedere Ricette di autenticazione nella guida all'integrazione.

L'identità dell'agente è associata all'URL

Il valore di {agentId} nell'URL deve corrispondere a appId dell'applicazione chiamante (il claim appid o azp nel token). Le mancate corrispondenze restituiscono 403 Forbidden. Per le identità derivate dal progetto, {agentId} è l'id appId dell'agente, non l'appId del progetto.

Inoltre, ogni span che invii deve impostare gen_ai.agent.id sullo stesso appId. Il server convalida l'identità dell'agente in-payload rispetto all'agente autenticato e rifiuta le discordanze. Questo passaggio rileva accidentalmente la combinazione di intervalli da più agenti in una sola richiesta.

Un ambito (delegato) o un ruolo dell'app (applicazione) è l'autorizzazione denominata che Microsoft Entra include nel token di accesso. Per i dati di telemetria di Agent 365, l'autorizzazione è Agent365.Observability.OtelWrite per la risorsa Agent 365 Observability (gruppo di destinatari 9b975845-388f-4429-889e-eab1ef63949c).

Lo stesso nome di permesso viene registrato come entrambi i tipi:

  • Ruolo nell'app per identità non registrate nel flusso autonomo (S2S / credenziali client). Entra nella richiesta roles. Selezionato da <resource>/.default.
  • Ambito delegato per il flusso OBO. Entra nella richiesta scp. Selezionato da <resource>/Agent365.Observability.OtelWrite (o <resource>/.default).

Nel percorso S2S, un'istanza agente registrata in Agent 365 può esportare con un token solo app che non ha Agent365.Observability.OtelWrite alcun ruolo. Non serve un permesso di osservabilità o un consenso amministrativo per l'esportazione della telemetria. Un'identità non registrata richiede comunque il ruolo dell'app, e la route delegata richiede ancora l'ambito delegato più il consenso dell'amministratore.

Agent 365 espone anche un'autorizzazione lato lettura, Agent365.Observability.OtelRead, usata dagli operatori che eseguono query sui dati di telemetria di Agent 365. La maggior parte dei partner non ne hanno bisogno: questi documenti coprono solo l'acquisizione.

Aggiungi il permesso alla tua app

  • Per una registrazione di un'app Microsoft Entra standard: nel portale di Azure, aggiungi Agent365.Observability.OtelWrite tra le autorizzazioni API sulla registrazione dell'app dell'agente. Usa il ruolo dell'app per S2S e l'ambito delegato per OBO.
  • Per un'istanza di agente derivata da blueprint sulla rotta S2S: completa la registrazione Agent 365 per l'istanza dell'agente. Un'istanza registrata non ha bisogno del permesso dell'API di Observability o del consenso dell'amministratore per esportare la telemetria sulla rotta S2S.
  • Per un'istanza di agente derivata dal blueprint sulla route delegata: aggiungi l'ambito Agent365.Observability.OtelWrite delegato al blueprint così che le istanze dell'agente lo ereditino. Vedi Configurare i permessi ereditabili per i modelli di identità dell'agente. Per aggiungerlo alla CLI dell'Agente 365, vedi Permessi di osservabilità.

Prima che i token assumano un ruolo o un ambito richiesto, un tenant admin nel tenant del cliente deve concedere il consenso. Vedere Concedere agli agenti l'accesso alle risorse di Microsoft 365.

Senza consenso, l'acquisizione del token fallisce con AADSTS65001 (The user or administrator has not consented to use the application with ID...) oppure il token viene emesso senza la roles rivendicazione o scp e l'endpoint di ingestione rifiuta la richiesta con 403.

Un'istanza di agente registrata Agent 365 che esporta sulla route S2S non ha bisogno del consenso dell'amministratore di Observability. Il consenso è ancora richiesto per le identità S2S non registrate che utilizzano il ruolo dell'app e per tutte le esportazioni delegate che utilizzano l'ambito delegato.

Quando è richiesto il consenso, viene concesso una volta per ogni tenant e si applica a ogni istanza costruita da un blueprint successivamente. È necessario fornire nuovamente il consenso solo se viene aggiunto un nuovo permesso al blueprint.

Limiti e condizioni di rilascio

Conoscere questi limiti fin dall'inizio evita sorprese durante l'integrazione. Alcuni errori restituiscono un codice di stato HTTP di esito positivo anche se la risposta segnala che la telemetria non è stata accettata.

Limiti a livello di cavo:

  • Devi includere api-version=1 in ogni richiesta.
  • La dimensione massima richiesta è di 1 MB. Le richieste più grandi restituiscono 413 Payload Too Large.
  • Le due route hanno limiti di velocità separati. Su 429, rispetta Retry-After (impostato su 1 secondo) e attendi prima di riprovare con jitter.

Le integrazioni di terze parti abilitate che utilizzano l'autenticazione S2S possono chiamare l'endpoint di idoneità del tenant come verifica preliminare facoltativa prima di inviare la telemetria. Quando usi l'endpoint, affidati alla sua decisione invece di dedurre l'idoneità solo dal consenso o dalla licenza. Una enabled: false risposta significa che l'inquilino non è attualmente idoneo. Un 503 Service Unavailable senza corpo significa che non è stato possibile determinare l'idoneità. Riprova secondo l'intestazione Retry-After se hai ancora bisogno di un risultato di idoneità.

Risposte di errore:

  • 403 Forbidden: Il token che manca il ruolo o l'ambito dell'app richiesto, o {agentId} nell'URL, non corrisponde al appid o azp del tuo token.
  • 413 Payload Too Large: Il corpo supera 1 MB.
  • 429 Too Many Requests: Limite di richieste raggiunto; rispetta Retry-After: 1 e attendi prima di riprovare con jitter.

Condizioni di eliminazione (richiesta accettata da HTTP, ma i dati non vengono visualizzati a valle):

# Condition Behavior
1 Intervallo gen_ai.operation.name mancante o non presente in {invoke_agent, execute_tool, chat, output_messages} Rilascio per intervallo. Visualizzato in partialSuccess.rejectedSpans + errorMessage.
2 Nessun utente nel tenant del cliente ha una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata. Almeno un utente nel tenant deve avere la licenza assegnata (la sola presenza dello SKU nel tenant non è sufficiente - l'assegnazione avvia il flusso di lavoro back-end di Defender). L'utente con licenza non deve essere il chiamante umano dell'agente. La richiesta restituisce 200 OK, ma la voce results di ogni span ha stato rejected e il motivo tenant_not_licensed.

Un 200 OK non è una prova dell'acquisizione. Ispezionare la risposta resultse utilizzare il flusso di verifica per confermare che i dati arrivano.

Dove compaiono i dati di osservabilità dell'Agente 365

Dopo aver accettato gli span, appaiono in tre esperienze rivolte al cliente. Tutte e tre le esperienze dipendono da uno span valido invoke_agent alla radice del run. Un'esecuzione contenente solo intervalli chat, execute_tool o output_messages può essere interrogata in Ricerca avanzata di Defender (la tabella CloudAppEvents), ma non è visibile a nessun'altra superficie.

Experience Description
Microsoft Defender L'attività dell'agente (invoke_agent, execute_tool, chat) viene visualizzata nelle visualizzazioni delle attività dell'agente. Gli amministratori del tenant e gli analisti della sicurezza possono esaminare singole esecuzioni, strumenti e chiamate di inferenza. Le visualizzazioni delle attività dell'agente si basano sullo span invoke_agent; in sua assenza, l'esecuzione non viene visualizzata lì, anche se gli span figlio sono ancora interrogabili tramite Ricerca avanzata. La visualizzazione di ricerca avanzata - CloudAppEvents - accetta tutte le operazioni: ActionType riflette l'operazione (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) e i campi per intervallo sono all'interno di RawEventData. I nomi dei campi visibili dal cliente vengono mappati direttamente agli attributi di intervallo inviati: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.ide così via. Vedere Informazioni di riferimento sugli attributi per il mapping completo.
Interfaccia di amministrazione di Microsoft 365 L'attività dell'agente viene inoltre visualizzata nelle visualizzazioni di inventario e sicurezza degli agenti usate dagli amministratori tenant per gestire gli agenti nel tenant. Il centro di amministrazione acquisisce solo le righe invoke_agent: gli agenti senza dati di telemetria invoke_agent non compaiono nell'inventario e le esecuzioni che emettono solo chat, execute_tool o output_messages qui non sono visibili. Il centro di amministrazione legge attributi quali l'ID dell'agente, il nome dell'agente, l'ID del blueprint, l'identità del chiamante, l'ID della conversazione, il canale e lo stato di errore dall'elemento invoke_agent.
Microsoft Purview L'attività degli agenti si manifesta anche agli amministratori di conformità in Microsoft Purview, dove possono configurare le regole di gestione dei dati e le policy durante le esecuzioni degli agenti (prevenzione della perdita di dati, conservazione, conformità alla comunicazione e simili). Gli attributi che le politiche di Purview attivano (ID agente, ID blueprint, identità del chiamante, conversazione, canale, richiesta e messaggi di risposta) provengono dallo invoke_agent span e dai suoi discendenti.

Passaggi successivi

  • Ultimo aggiornamento: