Concetti chiave dell'osservabilità di Agent 365

Questo articolo illustra il modello dei dati alla base dell'osservabilità di Agent 365: cosa emettono gli agenti di telemetria, chi può emetterli, dove vengono indirizzati e quali limiti si applicano. Questi concetti si applicano a ogni percorso di integrazione: la distribuzione Microsoft OpenTelemetry, l'Agent 365 SDK e OTel diretto.

Nota

I dettagli a livello di collegamento, ad esempio i percorsi in Autenticazione, i codici di errore HTTP in Limiti e condizioni di eliminazione, e i limiti di dimensione e frequenza per richiesta, si applicano esclusivamente al percorso diretto OTel. L'SDK e la distribuzione li gestiscono automaticamente. Il resto di questo articolo (glossario, flusso dei dati, modelli di identità, ambiti, condizioni di eliminazione, dove vengono visualizzati i dati) si applica a ogni percorso.

Scegli il percorso di integrazione

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

  • Microsoft OpenTelemetry Distro - consigliata per le nuove integrazioni. SDK di osservabilità unificata su Agent 365, Microsoft Foundry, Monitoraggio di Azure e altri.
  • SDK Agent 365 (SDK di osservabilità) - l'SDK precedente. Continua a funzionare senza modifiche che interrompano la compatibilità, ma non è più il percorso raccomandato per le nuove integrazioni; le linee guida per la migrazione degli utenti SDK esistenti saranno disponibili a breve.
  • Direct OTel - il percorso OTLP/HTTP non elaborato. Usalo solo se hai già una pipeline OpenTelemetry implementata, il framework del tuo agente non può utilizzare l'SDK di Agent 365 oppure il tuo agente è scritto in un linguaggio non ancora supportato dall'SDK (come Java).

Qualunque percorso tu scelga, si applicano il modello di dati, i modelli di identità, gli ambiti, i limiti e le superfici a valle descritti di seguito.

Glossario

  • ID app (appId): identificatore dell'applicazione rilasciato quando viene registrata un'app Microsoft Entra o un'identità agente ID agente di Microsoft Entra.
    • Equivale all'OAuth client_id, non all'ID oggetto Microsoft Entra.
    • In questi documenti, "ID agente" e "ID blueprint" si riferiscono entrambi a un appId.
  • Conversazione: un thread logico di interazioni tra agenti, come una chat su 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.

Funzionamento

Per una panoramica di Agent 365 e delle destinazioni della telemetria, consulta Panoramica di Microsoft Agent 365.

Invii la telemetria come dati di tracciamento OpenTelemetry:

  • Un albero di span che descrive un run (un messaggio utente in entrata, una risposta dell'agente in uscita).
  • Ogni span descrive un singolo passaggio: l'invocazione dell'agente di livello superiore, una chiamata LLM, una chiamata a uno 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 un approfondimento sui modelli di identità degli agenti (registrazione standard dell'app Microsoft Entra rispetto a blueprint di identità dell'agente con Microsoft Entra Agent ID, inclusi i collaboratori IA), vedi Guida allo sviluppo di Agent 365. La scelta del modello di identità determina quale flusso di autenticazione e quale endpoint utilizzerai.

Se il tuo agente non ha una registrazione Microsoft Entra, non può utilizzare direttamente questi percorsi. Identifica l’agente tramite gli attributi ID alternativi (vedi Riferimento agli attributi) e contatta il team di Agent 365 per il percorso di ingresso appropriato.

Autenticazione

L'autenticazione si suddivide in base al fatto che il servizio si autentichi autonomamente o 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 autonomamente: nessun utente autenticato - autonomo, programmato o guidato da eventi.

    • Flusso OAuth: credenziali client Da servizio a servizio (S2S).
    • Attestazione del token: roles.
    • Percorso URL: /observabilityService/....

  • Il servizio si autentica per conto di un utente: per i membri del team IA o per l'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 configurazioni complete dei token per ogni combinazione di modello di identità e flusso, vedi Istruzioni per l'autenticazione nella Guida all'integrazione.

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

Il {agentId} nell'URL deve essere uguale al appId dell'applicazione chiamante (l'attestazione appid o azp nel tuo token). Le mancate corrispondenze restituiscono 403 Forbidden. Per le identità derivate da blueprint, {agentId} è l'appId dell'identità dell'agente, non dell'appId del blueprint.

Inoltre, ogni span inviato deve impostare gen_ai.agent.id sullo stesso appId; il server convalida l'identità dell'agente nel payload rispetto all'agente autenticato e respinge le discrezioni. 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 la telemetria di Agent 365, l'autorizzazione è Agent365.Observability.OtelWrite sulla risorsa di osservabilità di Agent 365 (gruppo di destinatari 9b975845-388f-4429-889e-eab1ef63949c).

La stessa autorizzazione è registrata come entrambi i tipi:

  • Ruolo dell'app per il 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).

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

Aggiunta dell'autorizzazione all'app

  • Per una registrazione di un'app Microsoft Entra standard: nel portale di Azure, aggiungi Agent365.Observability.OtelWrite(ruolo applicazione per S2S, ambito per delegato) tra le autorizzazioni API sulla 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 di agente creata da quel blueprint riceve automaticamente le autorizzazioni definite su di esso. Vedi Configurare le autorizzazioni ereditabili per i blueprint 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. Vedi Concedi agli agenti l'accesso alle risorse di Microsoft 365.

Senza consenso, l'acquisizione del token non riesce con AADSTS65001 ("l'utente o l'amministratore non ha fornito il consenso") oppure il token viene emesso senza l'attestazione roles / scp e 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 da un blueprint successivamente. Il consenso deve essere rinnovato solo quando viene aggiunta una nuova autorizzazione al blueprint.

Limiti e condizioni di eliminazione

Conoscere questi limiti fin dall'inizio evita sorprese durante l'integrazione: la maggior parte opera in modo silenzioso (l'API accetta la richiesta ma i dati non vengono mai visualizzati a valle…).

Limiti a livello di collegamento:

  • 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.
  • I due percorsi hanno limiti di flusso in entrata separati. Su 429, rispetta Retry-After (impostato su 1 secondo) e attendi prima di riprovare con jitter.

Risposte di errore:

  • 403 Forbidden--token che non contiene il ruolo o l'ambito richiesto dall'app, oppure {agentId}qualcosa nell'URL non corrisponde a appid / azp del tuo token.
  • 413 Payload Too Large--Il corpo supera 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 appaiono a valle):

# Condizione Comportamento
1 Span gen_ai.operation.name mancante o non in {invoke_agent, execute_tool, chat, output_messages} Rilascio per intervallo. Visualizzato in partialSuccess.rejectedSpans + errorMessage.
2 Nel tenant cliente, nessun utente ha una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata. Almeno un utente del tenant deve avere la licenza assegnata (la presenza dello SKU nel tenant non è sufficiente: l'assegnazione avvia il flusso backend di Defender). L'utente con licenza non deve necessariamente essere la persona che invoca l'agente. L'intera richiesta viene eliminata in modo silenzioso. 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 compaiono i tuoi 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 viste dell'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 vista advanced hunting - CloudAppEvents - accetta ogni operazione: ActionType riflette l'operazione (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) e i campi relativi a ciascuno span sono all'interno di RawEventData. I nomi dei campi visibili al cliente eseguono il mapping direttamente agli attributi dello span che hai inviato: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, e così via. Vedi riferimento Attributi per il mapping completo.

Interfaccia di amministrazione di Microsoft 365. L'attività degli agenti compare anche nelle viste di inventario e sicurezza utilizzate dagli amministratori del tenant per la governance degli agenti nel loro tenant. L'interfaccia di amministrazione inserisce solo le righe invoke_agent: gli agenti senza telemetria invoke_agent non vengono visualizzati nell'inventario e le esecuzioni che emettono solo chat / execute_tool / output_messages non sono visibili qui. Gli attributi che l'interfaccia di amministrazione legge (ID agente, nome agente, ID blueprint, identità chiamante, id conversazione, canale, stato dell'errore) provengono tutti dallo span invoke_agent.

Microsoft Purview L'attività degli agenti è inoltre resa disponibile agli amministratori della conformità in Microsoft Purview, dove possono configurare regole di gestione dei dati e criteri applicati alle esecuzioni degli agenti (prevenzione della perdita dei dati, conservazione, conformità alla comunicazione 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