Konzepte von Agent 365 Einblick

Dieser Artikel erläutert das Datenmodell hinter Agent 365 Einblick – welche Telemetrie von Agents ausgesendet wird, wer sie aussenden darf, wo sie ankommt und welche Beschränkungen gelten. Diese Konzepte gelten für alle Integrationspfade: die Microsoft OpenTelemetry Distro, das Agent 365 SDK und direkten OTel-Pfad.

Anmerkung

Details auf Übertragungsebene – die URL-Routen bei der Authentifizierung, die HTTP-Fehlercodes in Grenzen und Bedingungen für das Verwerfen sowie die Größen- und Geschwindigkeitsbeschränkungen pro Anforderung – gelten speziell für den direkten OTel-Pfad. Das SDK und die Distro abstrahieren diese für Sie. Der Rest dieses Artikels (Glossar, Datenfluss, Identitätsmodelle, Bereiche, Bedingungen für das Verwerfen sowie die Stellen, an denen Daten angezeigt werden) gelten für jeden Pfad.

Wählen Sie Ihren Integrationspfad

Drei Pfade senden dasselbe Span-Datenmodell in Agent 365. Wählen Sie eine Option:

  • Microsoft OpenTelemetry Distro - empfohlen für neue Integrationen. Einheitliches Einblick-SDK für Agent 365, Microsoft Foundry, Azure Monitor und mehr.
  • Agent 365 SDK (Einblick-SDK) - die frühere SDK. Funktioniert weiter ohne Breaking Changes, ist aber nicht mehr der empfohlene Weg für neue Integrationen; Migrationsleitfaden für vorhandene SDK-Benutzer werden bereitgestellt.
  • Direct OTel - der rohe OTLP/HTTP-Pfad. Verwenden Sie diese Option nur, wenn Sie bereits eine OpenTelemetry-Pipeline eingerichtet haben, Ihr Agent-Framework das Agent 365 SDK nicht verwenden kann oder Ihr Agent in einer Sprache geschrieben ist, die vom SDK noch nicht unterstützt wird (wie Java).

Unabhängig davon, welchen Pfad Sie wählen, gelten das Datenmodell, die Identitätsmodelle, die Berechtigungsbereiche, die Limits und die unten beschriebenen Downstream-Schnittstellen.

Glossar

  • App-ID (appId): Die Anwendungskennung, die vergeben wird, wenn eine Microsoft Entra-App oder Microsoft Entra-Agent-ID-Identität registriert wird.
    • Entspricht der OAuth client_id, jedoch nicht der Microsoft Entra-Objekt-ID.
    • In diesen Dokumenten bedeuten „Agent-ID“ und „Blueprint-ID“ beide einen appId.
  • Unterhaltung: Eine logische Abfolge von Agentinteraktionen, wie zum Beispiel ein Teams-Chat-Thread.
    • Identifiziert durch gen_ai.conversation.id.
    • Der primäre Verknüpfungsschlüssel für eine Ausführung.
  • Kanal: Die Umgebung, in der der Agent läuft: msteams, outlook, web und so weiter.
  • Ausführung: eine Benutzernachricht als Eingabe, eine Agent-Antwort als Ausgabe. Modelliert als Baumstruktur von OTel-Spans, die sich eine traceId teilen.

Funktionsweise

Für einen Überblick über Microsoft Agent 365 und den Einsatz der Telemetrie siehe Übersicht von Microsoft Agent 365.

Telemetrie wird als OpenTelemetry-Trace-Daten gesendet:

  • Eine Baumstruktur von Spans, die eine Ausführung beschreibt (eEine Benutzernachricht als Eingabe, eine Agent-Antwort als Ausgabe).
  • Jede Spanne beschreibt einen einzelnen Schritt – den obersten Agentaufruf, einen LLM-Aufruf, einen Toolaufruf 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 Erklärung der Agentidentitätsmodelle (Standard-Microsoft Entra-App-Registrierung vs. Microsoft Entra-Agent-ID-Agentidentitäts-Blueprint, einschließlich KI-Teammitgliedern) finden Sie unter Erste Schritte mit der Agent 365-Entwicklung. 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 anhand der alternativen ID-Attribute (siehe Attributreferenz) und wenden Sie sich an das Agent 365-Team wegen des passenden Zugangswegs.

Authentifizierung

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

  • Dienst authentifiziert sich: Kein angemeldeter Nutzer – autonom, geplant oder ereignisgesteuert.

    • OAuth-Fluss: Service-to-Service (S2S) Client-Anmeldeinformationen.
    • Tokenanspruch: roles
    • URL-Pfad: /observabilityService/....

  • Der Dienst authentifiziert sich stellvertretend für einen Benutzer: Für KI-Teammitglieder oder für das eigene Benutzerkonto des Agents.

    • OAuth flow: On-behalf-of (OBO).
    • Tokenanspruch: scp
    • URL-Pfad: /observability/....

Dieselbe Agent-App kann in beiden Flows 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-Fluss.

Die vollständigen Token-Konfigurationen für jede Kombination aus Identitätsmodell und Flow finden Sie unter Authentifizierungsanleitungen im Integrationsleitfaden.

Die Agentidentität ist an die URL gebunden

Der {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 handelt es sich bei {agentId} um die appId der Agent-Identität, nicht um die appId des Blueprints.

Darüber hinaus muss jeder von Ihnen gesendete Span gen_ai.agent.id auf dieselbe appId festlegen. Der Server gleicht die in den Nutzdaten angegebene Agent-Identität mit dem authentifizierten Agent ab und weist Abweichungen zurück. Dieser Schritt verhindert, dass versehentlich Spans von mehreren Agents in einer einzigen Anforderung gemischt werden.

Ein Umfang (delegiert) oder eine App-Rolle (Anwendung) ist die benannte Berechtigung, die Microsoft Entra im Access-Token ausstellt. Bei der Agent 365-Telemetrie ist die Berechtigung Agent365.Observability.OtelWrite für die Agent 365 Observability-Ressource (Zielgruppe 9b975845-388f-4429-889e-eab1ef63949c).

Der gleiche Berechtigungsname ist als beide Arten registriert:

  • App-Rolle für den autonomen Flow (S2S/Clientanmeldeinformationen). Landet im roles-Anspruch. Ausgewählt von <resource>/.default.
  • Delegierter Umfang für den OBO-Flow. Landet im scp-Anspruch. Ausgewählt von <resource>/Agent365.Observability.OtelWrite (oder <resource>/.default).

Agent 365 stellt außerdem eine Leseberechtigung Agent365.Observability.OtelRead bereit, die von Operatoren genutzt wird, um die Agent 365-Telemetrie abzufragen. Die meisten Partner benötigen sie nicht – diese Dokumente behandeln nur die Erfassung.

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, Scope für Delegierung) unter API-Berechtigungen in der App-Registrierung des Agents hinzu.
  • Für einen Blueprint gilt: Agents, die auf der Grundlage eines Agent-Identity-Entwurfs einer Microsoft Entra-Agent ID erstellt werden, erben die im Blueprint definierten OAuth-Berechtigungen, sodass ein Mandantenadmin die Berechtigungen einmalig im Voraus bereitstellt. Jede Agentinstanz, die aus diesem Blueprint erstellt wurde, erhält sie automatisch. Siehe Konfiguration vererbbarer Berechtigungen für Agentidentität-Blueprints.

Bevor Token die Rolle bzw. den Bereich übernehmen, muss ein Mandantenadmin im Mandanten des Kunden die Zustimmung erteilen. Siehe Agenten Zugriff auf Microsoft 365-Ressourcen gewähren.

Ohne Zustimmung schlägt die Token-Anforderung mit AADSTS65001 („Benutzer oder Administrator hat nicht zugestimmt“) fehl oder das Token wird ohne den roles / scp Anspruch ausgestellt und der Ingestion-Endpunkt lehnt die Anfrage mit 403 ab.

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

Grenzen und Drop-Bedingungen

Diese Grenzen im Voraus zu kennen verhindert Überraschungen während der Integration … die meisten sind unsichtbar (die API akzeptiert die Anfrage, aber die Daten erscheinen nie nachgelagert).

Grenzwerte auf Wire-Ebene:

  • api-version=1 ist bei jeder Anfrage erforderlich.
  • Die maximale Größe des Anfrageinhalts beträgt 1 MB. Größere Anfragen erhalten 413 Payload Too Large.
  • Die beiden Routen haben separate Ratenbegrenzungen. Bei 429 muss Retry-After beachtet werden (auf 1 Sekunde festgelegt); mit Jitter abwarten.

Fehlerantworten:

  • 403 Forbidden--Token fehlt die erforderliche App-Rolle / Umfang oder {agentId} in der URL passt nicht zu appid / azp Ihres Tokens.
  • 413 Payload Too Large--Text überschreitet 1 MB.
  • 429 Too Many Requests--Rate-Grenzwert erreicht; Retry-After: 1 beachten und mit Jitter abwarten.

Drop-Bedingungen (Anfrage wird von HTTP akzeptiert, aber die Daten erscheinen nicht im Zielsystem):

# Bedingung Verhalten
1 Spanne gen_ai.operation.name fehlt oder ist nicht in {invoke_agent, execute_tool, chat, output_messages} Verwerfen pro Span. Angezeigt in partialSuccess.rejectedSpans + errorMessage.
2 Kein Nutzer im Kundenmandant hat eine Microsoft 365 E7- oder Microsoft Agent 365-Lizenz zugewiesen. Mindestens ein Benutzer im Mandanten muss die Lizenz zugewiesen bekommen (das bloße Vorhandensein der SKU im Mandanten reicht nicht aus – die Zuweisung startet den Defender-Backend-Workflow). Der lizenzierte Benutzer muss nicht der menschliche Anrufer des Agent sein. Die gesamte Anfrage wird stillschweigend verworfen. Gibt 200 { "partialSuccess": null } zurück.

Ein 200 OK ist kein Beweis für die Erfassung. Nutzen Sie den Verifizierungsfluss, um zu bestätigen, dass die Daten landen.

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 im Stamm der Ausführung ab. Eine Ausführung mit ausschließlich chat / execute_tool / output_messages-Spans ist im erweiterten Hunting von Defender (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) erscheint in den Agentaktivitätsansichten. Mandantenadmins und Sicherheitsanalysten können Details zu einzelnen Ausführungen, Tools und Rückschlussaufrufen aufrufen. Die Ansichten zur Agent-Aktivität richten sich nach dem invoke_agent-Span; ohne einen solchen wird die Ausführung dort nicht angezeigt, obwohl untergeordnete Spans weiterhin über erweitertes Hunting abgefragt werden können. Die erweiterte Hunting-Ansicht – CloudAppEvents – akzeptiert jede Operation: ActionType spiegelt die Operation wider (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) und die Felder pro Spanne befinden sich in RawEventData. Die kundensichtbaren Feldnamen werden direkt den von Ihnen gesendeten Span-Attributen zugeordnet: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id usw. Siehe Attributreferenz für die vollständige Zuordnung.

Microsoft 365 Admin Center. Agent-Aktivitäten werden auch in den von Mandantenadmins zum Steuern von Agents in ihrem Mandanten verwendeten Ansichten zu Agent-Inventar und -Sicherheit angezeigt. Das Admin Center erfasst nur invoke_agent-Zeilen: 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 ausliest (Agenten-ID, Agentname, Blueprint-ID, Anruferidentität, Konversations-ID, Kanal, Fehlerstatus), stammen alle aus dem invoke_agent-Span.

Microsoft Purview. Agentaktivitäten werden auch Compliance-Administratoren in Microsoft Purview bereitgestellt, wo sie Datenverarbeitungs- und Richtlinienregeln für Agentenläufe konfigurieren können (Datenverlustprävention, Aufbewahrung, Kommunikationscompliance und Ähnliches). 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 Leitfaden zur Auswahl von Werten pro Attribut.
  • Fehlerbehebung – Überprüfung der Erfassung, häufige Fallstricke und Fehlerantworten.
  • Last updated on