Agent 365 Observability-Konzepte

Dieser Artikel erklärt das Agent 365 Observability-Datenmodell, einschließlich der Ausstrahlung von Telemetrieagenten, wer sie aussenden darf, wo sie landen und welche Grenzen gelten. Nutzen Sie diese Konzepte, um Ihre Integration zu planen und Telemetrie über die Microsoft OpenTelemetry Distro, das veraltete Agent 365 Observability SDK und Direct OTel hinweg zu verstehen.

Note

Details auf Drahtebene – die URL-Routen in der Authentifizierung, die HTTP-Fehlercodes in Grenzwerten und Dropbedingungen sowie die Größen- und Geschwindigkeitsbeschränkungen pro Anforderung – gelten speziell für den direkten OTel-Pfad. Das SDK und distro abstrahieren diese für Sie. Der Rest dieses Artikels (Glossar, Datenfluss, Identitätsmodelle, Bereiche, Dropbedingungen, wo Daten angezeigt werden) gelten für jeden Pfad.

Wählen Sie Ihren Integrationspfad aus.

Drei Pfade geben dasselbe Datenmodell für die Spannweite in Agent 365 aus. Wählen Sie eins aus:

Path	Description
Microsoft OpenTelemetry Distro	Empfohlen für neue Integrationen. Unified Observability SDK für Agent 365, Microsoft Foundry, Azure Monitor und vieles mehr.
Veralteter Agent 365 Observability SDK	Das Legacy-SDK. Bestehende Integrationen funktionieren weiterhin, aber nutzen Sie es nicht für neue Integrationen. Der Artikel enthält Migrationsleitfäden.
Direktes OTel	Der rohe OTLP/HTTP-Pfad. Nutze es nur, wenn du bereits eine OpenTelemetry-Pipeline hast, dein Agent-Framework den Microsoft OpenTelemetry Distro nicht nutzen kann oder dein Agent in einer Sprache ist, die der Distro noch nicht unterstützt (wie zum Beispiel Java).

Je nachdem, welcher Pfad Sie auswählen, gelten das Datenmodell, Identitätsmodelle, Bereiche, Grenzwerte und nachgeschaltete Oberflächen, die unten beschrieben werden.

Agent 365 Observability-Glossar

Begriff	Description
App-ID (appId)	Die Anwendungskennung wird ausgegeben, wenn eine Microsoft Entra-App oder eine Microsoft Entra-Agent-ID-Agentenidentität registriert wird. - Gleich dem OAuth client_id, nicht der Microsoft Entra-Objekt-ID. - In diesen Dokumenten bedeuten "Agent id" und "Blueprint id" beide ein appId.
Gespräch	Ein logischer Thread von Agenteninteraktionen, wie zum Beispiel ein Teams-Chat-Thread. - Identifiziert durch gen_ai.conversation.id. - Der primäre Join-Schlüssel eines Laufs.
Channel	Die Oberfläche, in der der Agent läuft: msteams, outlook, , webund so weiter.
Laufen	Eine Benutzernachricht ein, eine Agentantwort raus. Modelliert als Baum von OTel-Spannen, die eine traceIdteilen.

Wie die Observabilität von Agent 365 funktioniert

Für einen Überblick über Agent 365 und die von ihm gesammelte Telemetrie siehe Überblick über Microsoft Agent 365.

Sie senden Telemetrie als OpenTelemetry-Ablaufverfolgungsdaten:

• Ein Baum von Spans, der einen Durchlauf beschreibt (eine Benutzernachricht rein, eine Agentenantwort raus).
• Jeder Bereich beschreibt einen einzelnen Schritt – den Aufruf des Agents auf oberster Ebene, einen LLM-Aufruf, einen Toolanruf oder die endgültige Antwort.

Agent 365 Observability-Datenfluss

Das folgende Diagramm zeigt, wie die Telemetriedaten von Agenten über die Authentifizierung und die Erfassung der Observability-Daten von Agent 365 in nachgelagerte Microsoft 365-Erlebnisse fließen.

Identitätsmodelle

Eine vollständige Erläuterung der Agentenidentitätsmodelle (standardmäßige Microsoft Entra-App-Registrierung im Vergleich zu Microsoft Entra-Agent-ID-Vorlage für die Agentenidentität, einschließlich KI-Teammitgliedern) finden Sie unter Agentenidentität. Ihre Wahl des Identitätsmodells bestimmt, welchen Authentifizierungsfluss und welchen Endpunkt Sie verwenden.

Eine vom Blueprint abgeleitete Agenten-Identität wird erst nach Abschluss der Registrierung von Agent 365 zu einer Agent-365-registrierten Agenten-Instanz, etwa durch a365 setup all. Allein das Erstellen einer Microsoft Entra-Identität registriert die Instanz nicht. Standard-Microsoft Entra-App-Registrierungen, wie etwa die, die von benutzerdefinierten Engine-Agenten verwendet werden, sind keine registrierten Agenten-Instanzen.

Wenn Ihr Agent keine Microsoft Entra Registrierung hat, kann er diese Routen nicht direkt verwenden. Identifizieren Sie den Agent über die alternativen ID-Attribute (siehe Attributreferenz) und kontaktieren Sie das Agent 365-Team bezüglich des entsprechenden Eintrittspfads.

Authentication

Die Authentifizierung hängt davon ab, ob sich Ihr Dienst selbst authentifiziert oder im Namen eines Nutzers authentifiziert. Diese Unterscheidung bestimmt den OAuth-Fluss, den Token-Claim, der die Berechtigung enthält, und die URL-Route.

• Der Dienst authentifiziert sich selbst: Kein angemeldeter Benutzer – autonom, geplant oder ereignisgesteuert.

  • OAuth-Flow: Service-to-Service (S2S)-Client-Anmeldedaten.
  • Token anfordern: roles. Eine nicht registrierte Identität benötigt die Agent365.Observability.OtelWrite App-Rolle. Eine Agent 365-registrierte Agenteninstanz kann ein reines App-Token ohne diese Rolle verwenden.
  • URL-Route: /observabilityService/....

• Der Dienst authentifiziert sich im Namen eines Benutzers: Für KI-Teamkollegen oder für das eigene Benutzerkonto des Agents.

  • OAuth-Ablauf: On-behalf-of (OBO).
  • Token anfordern: scp.
  • URL-Route: /observability/....

Dieselbe Agent-App kann in beiden Abläufen eingesetzt werden, etwa als KI-Teamkollege, der auch jede Nacht autonom einen Zusammenfassungslauf ausführt. Weitere Informationen finden Sie unter OAuth-Ablauf für autonome Apps und On-Behalf-Of-Ablauf.

Die vollständigen Tokenrezepte für jede Kombination aus Identitätsmodell und Ablauf finden Sie im Integrationshandbuch unter Authentifizierungsrezepte .

Die Agentidentität ist an die URL gebunden.

Die {agentId} in der URL muss mit der appId der aufrufenden Anwendung übereinstimmen (dem appid- oder azp-Claim in Ihrem Token). Nichtübereinstimmungen geben 403 Forbidden zurück. Bei von Blueprint abgeleiteten Identitäten {agentId} handelt es sich um die Agent-Identitäts-appId, nicht um die Blueprint-AppId.

Außerdem muss jeder gesendete Span gen_ai.agent.id auf dieselbe AppId gesetzt sein. Der Server validiert die Identität des im Payload enthaltenen Agenten mit dem authentifizierten Agenten und lehnt Abweichungen ab. Dieser Schritt verhindert, dass versehentlich Spans von mehreren Agenten in einer einzigen Anfrage gemischt werden.

Bereiche und Zustimmung

Ein Bereich (delegiert) oder eine App-Rolle (Anwendung) ist die benannte Berechtigung, die Microsoft Entra in das Zugriffstoken aufnimmt. Für die Agent 365-Telemetrie ist die Berechtigung Agent365.Observability.OtelWrite für die Agent 365 Observability-Ressource (Zielgruppe 9b975845-388f-4429-889e-eab1ef63949c).

Derselbe Berechtigungsname wird als beide Arten registriert:

• App-Rolle für nicht registrierte Identitäten im autonomen (S2S / Clientanmeldeinformationen) Flow. Landt in der roles Forderung. Ausgewählt von <resource>/.default.
• Delegierter Gültigkeitsbereich für den OBO-Flow. Landt in der scp Forderung. Ausgewählt von <resource>/Agent365.Observability.OtelWrite (oder <resource>/.default).

Auf der S2S-Route kann eine Agent 365-registrierte Agenteninstanz mit einem App-only-Token exportieren, das über keine Agent365.Observability.OtelWrite-Rolle verfügt. Für den Telemetrie-Export benötigt es keine Observability-Berechtigung oder Administrator-Erlaubnis. Eine nicht registrierte Identität benötigt weiterhin die App-Rolle, und der delegierte Pfad benötigt weiterhin den delegierten Bereich plus die Zustimmung des Administrators.

Agent 365 macht auch eine leseseitige Berechtigung verfügbar, Agent365.Observability.OtelReaddie von Operatoren verwendet wird, die Agent 365-Telemetrie abfragen . Die meisten Partner brauchen es nicht - diese Dokumente decken nur die Aufnahme ab.

Füge die Berechtigung zu deiner App hinzu

• Für eine Standard-Microsoft Entra-App-Registrierung: Fügen Sie im Azure-Portal in der App-Registrierung des Agenten unter API-BerechtigungenAgent365.Observability.OtelWrite hinzu. Nutze die App-Rolle für S2S und den delegierten Scope für OBO.
• Für eine von Blueprint abgeleitete Agenteninstanz auf der S2S-Route: Agent-365-Registrierung für die Agenteninstanz abschließen. Eine registrierte Instanz benötigt weder die Observability-API-Berechtigung noch die Admin-Erlaubnis, um Telemetrie auf der S2S-Route zu exportieren.
• Für eine von Blueprint abgeleitete Agent-Instanz auf der delegierten Route: Füge den delegierten Agent365.Observability.OtelWrite Scope dem Blueprint hinzu, damit Agent-Instanzen ihn übernehmen. Siehe Konfigurieren vererbbarer Berechtigungen für Agentidentitäts-Blueprints. Um sie mit dem Agent 365 CLI-Tool hinzuzufügen, siehe Observability-Berechtigungen.

Mandanten-Zustimmung

Bevor Token eine erforderliche Rolle oder einen erforderlichen Umfang enthalten, muss ein Tenant-Admin im Kunden-Tenant die Zustimmung erteilen. Siehe Grant Agents Zugriff auf Microsoft 365 Ressourcen.

Ohne Zustimmung schlägt die Token-Erwerbung mit AADSTS65001 (The user or administrator has not consented to use the application with ID...) fehl oder das Token wird ohne den roles oder scp Claim ausgegeben, und der Ingestion-Endpunkt lehnt die Anfrage mit 403ab.

Eine Agent-365-registrierte Agent-Instanz, die auf der S2S-Route exportiert, benötigt keine Zustimmung des Observability-Administrators. Die Zustimmung ist weiterhin für nicht registrierte S2S-Identitäten erforderlich, die die App-Rolle nutzen, sowie für alle delegierten Routenexporte, die den delegierten Scope verwenden.

Wenn eine Zustimmung erforderlich ist, wird sie einmal pro Mandant erteilt und gilt danach für jede Instanz, die aus einem Blueprint erstellt wird. Eine erneute Zustimmung ist nur erforderlich, wenn dem Blueprint eine neue Berechtigung hinzugefügt wird.

Grenzwerte und Abbruchbedingungen

Diese Grenzen im Voraus zu kennen, verhindert Überraschungen während der Integration. Einige Fehler geben einen erfolgreichen HTTP-Status zurück, obwohl die Antwort meldet, dass die Telemetrie nicht akzeptiert wurde.

Grenzwerte für Drahtebene:

• Sie müssen api-version=1 in jede Anfrage einschließen.
• Die maximale Request-Body-Größe beträgt 1 MB. Größere Anfragen geben 413 Payload Too Large zurück.
• Die beiden Routen weisen separate Tarifgrenzwerte auf. Bei 429Retry-After beachten (auf 1 Sekunde festgelegt) und mit Jitter verzögern.

Integrierte Drittanbieter-Integrationen, die S2S-Authentifizierung verwenden, können den Mieterberechtigungsendpunkt als optionalen Preflight aufrufen, bevor die Telemetrie gesendet wird. Wenn Sie den Endpunkt verwenden, stützen Sie sich auf dessen Entscheidung, anstatt die Berechtigung allein aus Einwilligung oder Lizenz abzuleiten. Eine Antwort enabled: false bedeutet, dass der Mieter derzeit nicht berechtigt ist. Körperlos 503 Service Unavailable bedeutet, dass die Berechtigung nicht bestimmt werden konnte. Versuche es erneut entsprechend dem zugehörigen Retry-After Header, falls du noch ein Ergebnis zur Berechtigung benötigst.

Fehlerantworten:

• 403 Forbidden: Dem Token fehlt die erforderliche App-Rolle oder der erforderliche Berechtigungsbereich, oder {agentId} in der URL stimmt nicht mit dem appid oder azp Ihres Tokens überein.
• 413 Payload Too Large: Der Nachrichtentext überschreitet 1 MB.
• 429 Too Many Requests: Rate limit erreicht; Ehre Retry-After: 1 und Rückzug mit Jitter.

Bedingungen für das Verwerfen (von HTTP akzeptierte Anfrage, aber die Daten erscheinen nicht in nachgelagerten Systemen):

#	Zustand	Behavior
1	Span gen_ai.operation.name fehlt oder ist nicht in {invoke_agent, execute_tool, chat, output_messages}	Abfall pro Intervall. Eingeführt in partialSuccess.rejectedSpans + errorMessage.
2	Keinem Benutzer im Kundenmandanten ist eine Microsoft 365 E7- oder Microsoft Agent 365-Lizenz zugewiesen. Mindestens einem Benutzer im Mandanten muss die Lizenz zugewiesen sein (es reicht nicht aus, dass die SKU im Mandanten vorhanden ist – die Zuweisung startet den Defender-Back-End-Workflow). Der lizenzierte Benutzer muss nicht der menschliche Anrufer des Agents sein.	Die Anfrage liefert 200 OK, aber der results-Eintrag jedes Span hat den Status rejected und den Grund tenant_not_licensed.

200 OK ist kein Nachweis für eine Aufnahme. Inspiziere die Antworten resultsund nutze den Verifizierungsfluss, um zu bestätigen, dass die Daten landen.

Wo Agent 365-Beobachtbarkeitsdaten angezeigt werden

Nachdem Sie die Spannen akzeptiert haben, erscheinen sie in drei kundenorientierten Bereichen. Alle drei Erfahrungen beruhen auf einem gültigen invoke_agent Span an der Wurzel des Run. Ein Durchlauf mit nur chat, execute_tool oder output_messages Bereichen ist in Defender Advanced Hunting (der Tabelle CloudAppEvents) abfragbar, ist aber für alle anderen Oberflächen unsichtbar.

Experience	Description
Microsoft Defender	Agentaktivität (invoke_agent, execute_tool, chat) wird in den Agent-Aktivitätsansichten angezeigt. Mandantenadministratoren und Sicherheitsanalysten können Details zu einzelnen Ausführungen, Tools und Inferenzaufrufen aufrufen. Die Agent-Aktivitätsansichten richten sich nach dem invoke_agent-Span; ohne einen solchen wird der Lauf dort nicht angezeigt, obwohl untergeordnete Spans weiterhin über Advanced Hunting abgefragt werden können. Die erweiterte Suchansicht - CloudAppEvents - unterstützt jeden Vorgang: ActionType spiegelt den Vorgang wider (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer), und die Felder pro Span befinden sich in RawEventData. Die vom Kunden sichtbaren Feldnamen werden direkt den von Ihnen gesendeten Spannattributen zugeordnet: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.idusw. Siehe Attributreferenz für die vollständige Zuordnung.
Microsoft 365 Admin Center	Agentaktivitäten werden auch in den Von Mandantenadministratoren zum Steuern von Agents in ihrem Mandanten verwendeten Agentinventar- und Sicherheitsansichten angezeigt. Das Admin Center erfasst nur invoke_agent Zeilen: Agenten ohne invoke_agent-Telemetrie erscheinen nicht im Inventar, und Läufe, die nur chat, execute_tool oder output_messages ausgeben, sind hier nicht sichtbar. Das Verwaltungszentrum liest Attribute wie Agenten-ID, Agentenname, Blueprint-ID, Anruferidentität, Konversations-ID, Kanal und Fehlerstatus aus dem Span invoke_agent .
Microsoft Purview	Agentenaktivitäten werden auch Compliance-Administratoren in Microsoft Purview angezeigt, wo sie Datenverarbeitung und Richtlinienregeln über Agentenläufe konfigurieren können (Datenverlustprävention, Aufbewahrung, Kommunikationscompliance und Ähnliches). Die Attribute, auf denen die Purview-Richtlinien basieren (Agenten-ID, Blueprint-ID, Identität des Aufrufers, Konversation, Kanal, Anfrage- und Antwortnachrichten), stammen aus dem invoke_agent-Span-Element und seinen untergeordneten Elementen.

Nächste Schritte

• Attributreferenz – Spezifikation , Anforderungen und Richtlinien für die Wertauswahl pro Attribut.
• Problembehandlung : Überprüfen der Aufnahme, allgemeiner Fallstricke und Fehlerantworten.