Agent 365 Observability-Konzepte

In diesem Artikel wird das Datenmodell hinter Agent 365-Observability erläutert – welche Telemetrie-Agents ausgeben, wer sie ausgeben kann, wo es landet, und welche Grenzwerte gelten. Diese Konzepte gelten für jeden Integrationspfad: Microsoft OpenTelemetry Distro, das Agent 365 SDK und direktes OTel.

Wählen Sie Ihren Integrationspfad aus.

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

• Microsoft OpenTelemetry Distro - für neue Integrationen empfohlen. Unified Observability SDK für Agent 365, Microsoft Foundry, Azure Monitor und vieles mehr.
• Agent 365 SDK (Observability SDK) – das frühere SDK. Funktioniert weiterhin, ohne Änderungen zu unterbrechen, aber nicht mehr der empfohlene Weg für neue Integrationen; Migrationsleitfaden für vorhandene SDK-Benutzer werden bereitgestellt.
• Direct OTel – der unformatierte OTLP/HTTP-Pfad. Verwenden Sie sie nur, wenn Sie bereits über eine OpenTelemetry-Pipeline verfügen, kann Ihr Agentframework das Agent 365 SDK nicht verwenden, oder Ihr Agent ist in einer Sprache, die das SDK noch nicht unterstützt (z. B. Java).

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

Glossar

• App-ID (appId): Der Anwendungsbezeichner, der ausgegeben wird, wenn eine Microsoft Entra App oder Microsoft Entra-Agent-ID Agentidentität registriert ist.
  • Entspricht der OAuth-client_id, nicht der Microsoft Entra-Objekt-ID.
  • In diesen Dokumenten bedeuten "Agent-ID" und "Blueprint-ID" beide eine appId.
• Konversation: Ein logischer Verlauf aus Agentinteraktionen, z. B. ein Chatthread in Teams.
  • Identifiziert durch gen_ai.conversation.id.
  • Der primäre Verknüpfungsschlüssel für eine Ausführung.
• Kanal: Die Oberfläche, in der der Agent ausgeführt wird: msteams, outlook, web, usw.
• Ausführung: Eine Benutzernachricht hinein, eine Agentenantwort hinaus. Als Baum von OTel-Spans modelliert, die sich ein traceId teilen.

So funktioniert es

Eine Übersicht über Agent 365 und wofür Telemetriedaten verwendet werden finden Sie unter Übersicht ü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.

Datenfluss

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

Identitätsmodelle

Eine vollständige Erläuterung der Agentidentitätsmodelle (standardmäßige Microsoft Entra-App-Registrierung im Vergleich zum Microsoft Entra-Agent-ID-Agentidentitätskonzept, einschließlich KI-Teammitgliedern) finden Sie unter Erste Schritte mit der Entwicklung für Agent 365. Ihre Wahl des Identitätsmodells bestimmt, welchen Authentifizierungsfluss und welchen Endpunkt Sie verwenden.

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 wenden Sie sich an das Agent 365-Team über den entsprechenden Eingangspfad.

Authentication

Die Authentifizierung unterscheidet sich danach, ob sich Ihr Dienst selbst oder im Namen eines Benutzers authentifiziert. Der Zweig bestimmt den OAuth-Flow, den Claim im Token, 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.
  • 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.

Darüber hinaus muss jeder von Ihnen gesendete Span gen_ai.agent.id auf dieselbe appId gesetzt werden; der Server gleicht die im Payload angegebene Agent-Identität mit dem authentifizierten Agenten ab und weist Abweichungen zurück. 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:

• Anwendungsrolle für den autonomen Ablauf (S2S / Clientanmeldeinformationsfluss). 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).

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.

Hinzufügen der Berechtigung zu Ihrer App

• Für eine standard-Microsoft Entra-App-Registrierung: Fügen Sie im Azure-Portal Agent365.Observability.OtelWrite (App-Rolle für S2S, Bereich für delegierte) unter API-Berechtigungen zur App-Registrierung des Agents hinzu.
• Für einen Entwurf gilt: Agents, die auf der Grundlage eines Microsoft Entra-Agent-ID-Agent-Identity-Entwurfs erstellt werden, übernehmen die im Entwurf definierten OAuth-Berechtigungen, sodass ein Mandantenadministrator die Berechtigungen einmalig im Voraus bereitstellt. Jede agentinstanz, die aus diesem Blueprint erstellt wurde, empfängt sie automatisch. Siehe Konfigurieren vererbbarer Berechtigungen für Agentidentitäts-Blueprints.

Mandanten-Zustimmung

Bevor Tokens die Rolle bzw. den Bereich enthalten, muss ein Mandantenadministrator im Mandanten des Kunden die Zustimmung erteilen. Siehe Grant Agents Zugriff auf Microsoft 365 Ressourcen.

Ohne Zustimmung schlägt der Tokenerwerb mit AADSTS65001 ("Benutzer oder Administrator hat nicht zugestimmt") fehl, oder das Token wird ohne denroles / scpAnspruch ausgegeben, und der Aufnahmeendpunkt lehnt die Anforderung mit .403

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

Grenzwerte und Abbruchbedingungen

Wenn Sie diese Grenzen im Vorfeld kennen, vermeiden Sie Überraschungen bei der Integration – die meisten bleiben unbemerkt (die API akzeptiert die Anfrage, aber die Daten kommen in nachgelagerten Systemen nie an).

Grenzwerte für Drahtebene:

• api-version=1 ist für jede Anforderung erforderlich.
• Die maximale Anforderungstextgröße beträgt 1 MB. Größere Anfragen erhalten 413 Payload Too Large.
• Die beiden Routen weisen separate Tarifgrenzwerte auf. Bei 429Retry-After beachten (auf 1 Sekunde festgelegt) und mit Jitter verzögern.

Fehlerantworten:

• 403 Forbidden--Token, dem die erforderliche App-Rolle bzw. der erforderliche Berechtigungsbereich fehlt, oder {agentId} in der URL stimmt nicht mit dem appid / azp Ihres Tokens überein.
• 413 Payload Too Large--body ist größer als 1 MB.
• 429 Too Many Requests--Ratenlimit erreicht; Retry-After: 1 beachten und mit Jitter abwarten.

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

Ein 200 OK ist kein Beweis für die Aufnahme. Verwenden Sie den Verifizierungsablauf, um zu bestätigen, dass Daten ankommen.

Wo Ihre Daten angezeigt werden

Sobald sie akzeptiert wurden, erscheinen Ihre Spans in drei kundenorientierten Ansichten. Alle drei hängen von einem gültigen invoke_agent Span an der Wurzel des Durchlaufs ab. Ein Durchlauf mit ausschließlich chat / execute_tool / output_messages Spans ist in Defender Advanced Hunting (in der Tabelle CloudAppEvents) abfragbar, bleibt jedoch auf allen anderen unten aufgeführten Oberflächen unsichtbar.

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 nimmt nur invoke_agent Zeilen auf: Agents ohne invoke_agent Telemetrie werden nicht im Inventar angezeigt, und Ausführungen, die nur chat / execute_tool / output_messages ausgeben, sind hier nicht sichtbar. Die Attribute, die das Admin Center liest (Agent-ID, Agentname, Blueprint-ID, Anruferidentität, Unterhaltungs-ID, Kanal, Fehlerstatus) stammen aus der invoke_agent Spanne.

Microsoft Purview. Die Agentaktivität wird auch Complianceadministratoren in Microsoft Purview angezeigt, in denen sie die Datenverarbeitung und Richtlinienregeln über Agentausführungen konfigurieren können (Verhinderung von Datenverlust, Aufbewahrung, Kommunikationscompliance und ähnlich). Die Attribute, auf denen Purview-Richtlinien basieren (Agent-ID / Blueprint-ID, Identität des Aufrufers, Unterhaltung / Kanal, Anforderungs- und Antwortnachrichten), stammen alle aus dem invoke_agent-Span 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.