Observerbarhetskoncept för Agent 365

Denna artikel förklarar datamodellen bakom Agent 365-observabilitet – vilken telemetri agenter genererar, vem som kan generera den, var den hamnar och vilka gränser som gäller. Dessa koncept gäller alla integrationsvägar: Microsoft OpenTelemetry-distributionen, Agent 365 SDK och direkt OTel.

Kommentar

Trådnivådetaljer – URL-rutterna i Autentisering, HTTP-felkoderna i Gränser och bortfallsvillkor, samt gränserna för storlek och hastighet per begäran – gäller specifikt för den direkta OTel-vägen. SDK:n och distro abstraherar bort dessa åt dig. Resten av denna artikel (ordlista, dataflöde, identitetsmodeller, omfång, bortfallsvillkor, där data visas) gäller för varje integrationsväg.

Välj din integrationsväg

Tre sökvägar skickar samma span-datamodell till Agent 365. Välj en:

  • Microsoft OpenTelemetry Distro - rekommenderas för nya integrationer. Enhetligt observabilitets-SDK över Agent 365, Microsoft Foundry, Azure Monitor och mer.
  • Agent 365 SDK (Observability SDK) – den tidigare SDK:n. Fortsätter att fungera utan icke-bakåtkompatibla ändringar, men är inte längre den rekommenderade vägen för nya integrationer; migreringsvägledning för befintliga SDK-användare är på väg.
  • Direkt OTel – den råa OTLP/HTTP-vägen. Använd det endast om du redan har en OpenTelemetry-pipeline på plats, om ditt agentramverk inte kan använda Agent 365 SDK, eller om din agent är i ett språk som SDK:n ännu inte stödjer (till exempel Java).

Oavsett vilken väg du väljer gäller datamodellen, identitetsmodeller, omfång, gränser och nedströmsytor som beskrivs nedan.

Ordlista

  • App id (appId): Appidentifieraren som utfärdas när en Microsoft Entra-app eller Microsoft Entra Agent-ID-agentidentitet registreras.
    • Samma som OAuth client_id, inte Microsoft Entra objekt-ID.
    • I hela denna dokumentation avser både "agent id" och "blueprint id" en appId.
  • Konversation: En logisk tråd för agentinteraktioner, till exempel en Teams-chatt.
    • Identifieras via gen_ai.conversation.id.
    • Den primära join-nyckeln för en körning.
  • Kanal: Miljön där agenten körs: msteams, outlook, web och så vidare.
  • Körning: Ett användarmeddelande in, ett agentsvar ut. Modellerat som ett träd av OTel spann som delar en traceId.

Hur det fungerar

För en översikt över Agent 365 och vilka system telemetri matas in i, se Översikt över Microsoft Agent 365.

Du skickar telemetri som OpenTelemetry-spårdata:

  • Ett träd av span som beskriver en körning (ett användarmeddelande in, ett agentsvar ut).
  • Varje span beskriver ett enskilt steg – agentens toppnivåanrop, ett LLM-anrop, ett verktygsanrop eller det slutliga svaret.

Dataflöde

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

Identitetsmodeller

För en fullständig förklaring av agentidentitetsmodeller (standard Microsoft Entra-appregistrering vs. Microsoft Entra Agent-ID agentidentitetsblueprint, inklusive AI-assistenter), se Kom igång med utveckling av Agent 365. Ditt val av identitetsmodell avgör vilket autentiseringsflöde och vilken slutpunkt du använder.

Om din agent inte har någon Microsoft Entra-registrering kan den inte använda dessa rutter direkt. Identifiera agenten via alternativa ID-attribut (se Attributreferens) och kontakta Agent 365-teamet angående rätt ingressväg.

Autentisering

Autentisering beror på om din tjänst autentiserar sig själv eller på uppdrag av en användare. Grenen avgör OAuth-flödet, det tokenanspråk som innehåller behörigheten och URL-vägen.

  • Tjänsten autentiserar sig själv: Ingen inloggad användare – autonom, schemalagd eller händelsestyrd.

    • OAuth-flöde: tjänst till tjänst (S2S) klientautentiseringsuppgifter.
    • Token-anspråk: roles.
    • URL-rutt: /observabilityService/....

  • Tjänsten autentiserar för en användares räkning: För AI-teammedlemmar eller för agentens eget användarkonto.

    • OAuth-flöde: På uppdrag av (OBO).
    • Token-anspråk: scp.
    • URL-rutt: /observability/....

Samma agentapp kan delta i båda flödena, till exempel en AI-assistent som också kör en nattlig autonom sammanfattning. För mer information, se autonom app OAuth-flöde och OBO-flöde.

För fullständiga tokeninstruktioner för varje kombination av identitetsmodell och flöde, se autentiseringsinstruktioner i integrationsguiden.

Agentidentiteten är bunden till URL:en

{agentId} i URL:en måste vara lika med den anropande appens appId (anspråket appid eller azp in din token). Matchningsfel återkommer 403 Forbidden. För blueprint-baserade identiteter är {agentId}agent identity appId, inte blueprint appId.

Dessutom måste varje span du skickar sätta gen_ai.agent.id till samma appId; servern verifierar agentidentiteten i nyttolasten mot den autentiserade agenten och avvisar mismatcher. Det här steget fångar upp om span från flera agenter av misstag blandas i en och samma begäran.

Ett omfång (delegerat) eller approll (app) är den namngivna behörighet som Microsoft Entra utfärdar i åtkomsttoken. För Agent 365-telemetri är behörigheten Agent365.Observability.OtelWrite på Agent 365 Observability-resursen (målgrupp 9b975845-388f-4429-889e-eab1ef63949c).

Samma tillståndsnamn registreras som båda typerna:

  • Approllen för det autonoma (S2S / klientuppgifter) flödet. Landar i roles-anspråket. Utvald av <resource>/.default.
  • Delegerat omfång för OBO-flödet. Landar i scp-anspråket. Utvald av <resource>/Agent365.Observability.OtelWrite (eller <resource>/.default).

Agent 365 exponerar även en läsbehörighet, Agent365.Observability.OtelRead, som används av operatörer som frågar Agent 365-telemetri. De flesta partner behöver det inte – dessa dokument täcker bara intag.

Lägga till behörighet i din app

  • För en standardregistrering av Microsoft Entra-app: i Azure Portal, lägg till Agent365.Observability.OtelWrite(programroll för S2S, delegerad åtkomst för delegerad) under API-behörigheter på agentens appregistrering.
  • För en blueprint: agenter som präglats från en Microsoft Entra agent-ID agentidentitetsblueprint ärver OAuth-behörigheter som definierats för blueprinten, så att en klientorganisationsadministratör kan företablera behörigheter en gång. Varje agentinstans som skapas från den blueprinten får dem automatiskt. Se Konfigurera ärvbara behörigheter för agentidentitetsblueprints.

Innan tokens får rollen eller behörighetsomfånget måste en klientorganisationsadministratör i kundens klientorganisationsmiljö ge sitt samtycke. Se Grant agents åtkomst till Microsoft 365-resurser.

Utan samtycke misslyckas inhämtning av token med AADSTS65001 ("användare eller administratör har inte samtyckt") eller så utfärdas tokenen utan anspråket roles / scp och insamlingsändpunkten avvisar begäran med 403.

Samtycke ges en gång per klientorganisation och gäller sedan för varje instans som skapas från en blueprint. Nytt samtycke krävs endast när en ny behörighet läggs till i blueprinten.

Gränser och bortfallsvillkor

Att känna till dessa gränser i förväg förhindrar överraskningar vid integration – de flesta är tysta (API:et accepterar begäran men data visas aldrig nedströms).

Gränser på protokollnivå:

  • api-version=1 är obligatoriskt vid varje begäran.
  • Begärandetext får vara högst 1 MB. Större begäranden får 413 Payload Too Large.
  • De två vägarna har separata hastighetsgränser. På 429, respektera Retry-After (inställd på 1 sekund) och backa med jitter.

Felsvar:

  • 403 Forbidden--token saknar den nödvändiga approllen/omfattningen, eller {agentId} i URL:en matchar inte appid / azp i din token.
  • 413 Payload Too Large--texten överstiger 1 MB.
  • 429 Too Many Requests--rate limit uppnådd; respektera Retry-After: 1 och backa med jitter.

Drop-villkor (begäran accepteras av HTTP men data visas inte nedströms):

# Villkor Funktionssätt
1 Span gen_ai.operation.name saknas eller finns inte i {invoke_agent, execute_tool, chat, output_messages} Borttagning per span. Visas i partialSuccess.rejectedSpans + errorMessage.
2 Ingen användare i kundklientorganisationen har en Microsoft 365 E7- eller Microsoft Agent 365-licens tilldelad. Minst en användare i klientorganisationen måste ha licensen tilldelad (det räcker inte att SKU:n finns i klientorganisationen – tilldelningen startar Defender-serverdelsarbetsflödet). Den licensierade användaren behöver inte vara den mänskliga användaren som anropar agenten. Hela begäran tas tyst bort. Returnerar 200 { "partialSuccess": null }.

Ett godkännande på 200 är inte ett bevis på intag. Använd verifieringsflödet för att bekräfta att data landar.

Var din data visas

När de har accepterats blir dina spans synliga i tre kundvända gränssnitt. Alla tre beror på ett giltigt invoke_agent-span i roten av körningen. En körning med endast chat / execute_tool / output_messages-span är sökbar i Defender avancerad jakt (tabellen CloudAppEvents) men syns inte i övriga vyer nedanför.

Microsoft Defender. Agentaktivitet (invoke_agent, execute_tool, chat) visas i agentaktivitetsvyerna. Administratörer och säkerhetsanalytiker kan fördjupa sig i enskilda körningar, verktyg och inferensanrop. Agentaktivitetsvyerna är avstängda av invoke_agent span; utan en sådan visas inte körningen där även om underordnade span fortfarande kan frågas via avancerad jakt. Vyn för avancerad jakt – CloudAppEvents – accepterar varje åtgärd: ActionType speglar åtgärden (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) och fälten per span finns inuti RawEventData. De fältnamn som är synliga för kunden motsvarar direkt de span-attribut du skickade: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id och så vidare. Se Attributreferens för fullständig mappning.

Administrationscenter för Microsoft 365. Agentaktivitet visas även i de vyer för agentinventering och säkerhet som klientorganisationsadministratörer använder för att styra agenter i sin klientorganisation. Administratörscenter hämtar endast invoke_agent-rader: agenter utan invoke_agent telemetri visas inte i inventeringen, och körningar som endast genererar chat / execute_tool / output_messages är osynliga här. De attribut som administrationscentret läser (agent-id, agentnamn, blueprint-id, uppringaridentitet, konversations-id, kanal, felstatus) kommer alla från spannet invoke_agent.

Microsoft Purview. Agentaktivitet visas också för compliance-administratörer i Microsoft Purview, där de kan konfigurera datahanterings- och policyregler för agentkörningar (dataförlustskydd, retention, kommunikationsefterlevnad och liknande). De attribut som Purview-policyer använder som nycklar (agent-id, blueprint-id, anroparens identitet, konversation/kanal, förfrågnings- och svarsmeddelanden) hämtas alla från invoke_agentspan och dess underordnade.

Nästa steg

  • Attributreferens – Specifikation, krav och vägledning för val av attributvärden per attribut.
  • Felsökning – Verifierar intagning, vanliga fallgropar och felsvar.
  • Last updated on