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 distribuzione Microsoft OpenTelemetry, l'Agent 365 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:

Percorso Description
Distribuzione Microsoft OpenTelemetry Consigliato per nuove integrazioni. SDK di osservabilità unificata in Agent 365, Microsoft Foundry, Monitoraggio di Azure e altro ancora.
SDK Agent 365 (SDK di osservabilità) Il precedente SDK. Continua a funzionare senza modifiche di rilievo, ma non più il percorso consigliato per le nuove integrazioni; verranno fornite indicazioni sulla migrazione per gli utenti dell'SDK esistenti.
Direct OTel Il percorso OTLP/HTTP diretto. Usarlo solo se è già disponibile una pipeline OpenTelemetry, il framework agente non può usare Agent 365 SDK oppure l'agente si trova in un linguaggio non ancora supportato dall'SDK, ad esempio 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 delle telemetrie 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.

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 si distingue a seconda che il servizio autentichi se stesso o operi per conto di un utente. Il ramo determina il flusso OAuth, l'attestazione del token che contiene l'autorizzazione e la route dell'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.
    • 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 verifica l'identità dell'agente nel payload rispetto all'agente autenticato e rifiuta eventuali discrepanze. 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 dell'app per il flusso autonomo (S2S/client-credentials). 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).

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 standard di un'app Microsoft Entra: nel portale di Azure, aggiungere Agent365.Observability.OtelWrite (ruolo dell'app per S2S, ambito per delega) in Autorizzazioni API della registrazione dell'app dell'agente.
  • Per un blueprint: gli agenti creati da un blueprint dell'identità agente Microsoft Entra Agent ID ereditano le autorizzazioni OAuth definite nel blueprint, quindi un amministratore del tenant preconfigura le autorizzazioni una sola volta. Ogni istanza dell'agente creata da tale progetto le riceve automaticamente. Vedi Configurare i permessi ereditabili per i modelli di identità dell'agente.

Prima che i token assumano il ruolo o l'ambito, 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.

Il consenso viene concesso una sola volta per tenant e si applica a ogni istanza creata a partire 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

Una volta accettati, i tuoi span vengono visualizzati in tre esperienze visibili ai clienti. Tutti e tre dipendono da un intervallo valido invoke_agent nella radice dell'esecuzione. Un'esecuzione contenente solo intervalli chat / execute_tool / output_messages può essere interrogata in Ricerca avanzata di Defender (tabella CloudAppEvents), ma non è visibile in nessun'altra interfaccia riportata di seguito.

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

  • Last updated on