Concetti di osservabilità dell'agente 365

Questo articolo illustra il modello di dati alla base dell'osservabilità di Agent 365, ovvero quali agenti di telemetria generano, chi può emetterlo, dove atterra e i limiti che si applicano. Questi concetti si applicano al percorso di integrazione every: il percorso di integrazione Microsoft OpenTelemetry Distro, Agent 365 SDK e direct OTel.

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:

  • Microsoft OpenTelemetry Distro - consigliata per le nuove integrazioni. SDK di osservabilità unificata in Agent 365, Microsoft Foundry, Monitoraggio di Azure e altro ancora.
  • Agent 365 SDK (Observability SDK) - SDK precedente. 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 : percorso OTLP/HTTP non elaborato. 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.

Glossary

  • ID app (appId): identificatore dell'applicazione rilasciato quando viene registrata un'app Microsoft Entra o un'identità agente ID agente di Microsoft Entra.
    • Corrisponde all'OAuth client_id, non all'ID oggetto di Microsoft Entra.
    • In questi documenti, "ID agente" e "ID blueprint" si riferiscono entrambi a un appId.
  • Conversazione: un thread logico di interazioni dell'agente, ad esempio un thread di chat di Teams.
    • Identificato da gen_ai.conversation.id.
    • Chiave primaria di unione per un'esecuzione.
  • Canale: l'ambiente in cui viene eseguito l'agente: msteams, outlook, web e così via.
  • Esecuzione: un messaggio dell'utente in ingresso, una risposta dell'agente in uscita. Modellata come un albero di OTel span che condividono un traceId.

Come funziona

Per una panoramica di Agent 365 e di ciò in cui confluiscono i dati di telemetria, 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

   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)                  |
  +-------------------------------------+

Modelli di identità

Per una spiegazione completa dei modelli di identità dell'agente (registrazione standard dell'app Microsoft Entra rispetto a Microsoft Entra Agent ID modello di identità dell'agente, compresi i compagni di squadra basati sull'IA), consulta Introduzione allo sviluppo di Agent 365. 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. Identificare l'agente tramite gli attributi ID alternativi (vedere Riferimento agli attributi) e contattare il team di Agent 365 sul 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.

Aggiungere l'autorizzazione 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 dell'ID agente di Microsoft Entra 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 portino il ruolo o l'ambito, un amministratore tenant nel tenant del cliente deve concedere il consenso. Vedere Concedere agli agenti l'accesso alle risorse di Microsoft 365.

Senza il consenso, l'acquisizione del token non riesce con AADSTS65001 ("l'utente o l'amministratore non ha acconsentito") o il token viene rilasciato senza l'attestazioneroles / scpe l'endpoint di inserimento 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 in anticipo impedisce sorprese durante l'integrazione: la maggior parte è invisibile all'utente (l'API accetta la richiesta, ma i dati non vengono mai visualizzati a valle).

Limiti a livello di cavo:

  • api-version=1 è obbligatorio per ogni richiesta.
  • La dimensione massima del corpo della richiesta è 1 MB. Le richieste più grandi ottengono 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.

Risposte di errore:

  • 403 Forbidden--nel token manca il ruolo dell'app o l'ambito richiesto oppure {agentId} nell'URL non corrisponde a appid / azp del token.
  • 413 Payload Too Large--body supera la dimensione di 1 MB.
  • 429 Too Many Requests--limite di flusso in entrata raggiunto; rispetta Retry-After: 1 e riduci i tentativi 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. Intera richiesta scartata senza notifica. Restituisce 200 { "partialSuccess": null }.

Un 200 OK non è la prova dell'avvenuta acquisizione. Utilizza il flusso di verifica per confermare che i dati vengano acquisiti correttamente.

Dove vengono visualizzati i dati

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.

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 vengono visualizzati nell'inventario e le esecuzioni che emettono solo chat / execute_tool / output_messages sono invisibili qui. Gli attributi letti dall'interfaccia di amministrazione (ID agente, nome agente, ID progetto, identità chiamante, ID conversazione, canale, stato errore) provengono tutti dall'intervallo invoke_agent .

Microsoft Purview. L'attività dell'agente viene anche rilevata agli amministratori di conformità in Microsoft Purview, in cui possono configurare la gestione dei dati e le regole dei criteri sulle esecuzioni degli agenti (prevenzione della perdita dei dati, conservazione, conformità delle comunicazioni e simili). I criteri di Purview si basano tutti sugli attributi (ID agente/ID blueprint, identità del chiamante, conversazione/canale, messaggi di richiesta e di risposta) che provengono dall'elemento invoke_agent e dai suoi discendenti.

Passaggi successivi

  • Last updated on