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 OpenTelemetrie-Distribution, das Agent 365 SDK und Direct OTel zu verstehen.

Note

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 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 aus.

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

Pfad Description
Microsoft OpenTelemetry Distro Empfohlen für neue Integrationen. Unified Observability SDK für Agent 365, Microsoft Foundry, Azure Monitor und vieles mehr.
Agent 365 SDK (Observability SDK) Das 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.
Direktes OTel Der rohe 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.

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 welche Telemetrie es sammelt, siehe Überblick über Microsoft Agent 365.

Sie senden Telemetrie als OpenTelemetry-Ablaufverfolgungsdaten:

  • Eine Baumstruktur von Spans, die eine Ausführung beschreibt (eine Benutzernachricht als Eingabe, eine Agent-Antwort als Ausgabe).
  • 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 des Agents über die Authentifizierung und Agent 365-Observability-Erfassung in nachgelagerte Microsoft 365-Erlebnisse fließen.

Agent 365 Observability-Datenflussdiagramm.

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.

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.

Authentifizierung

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 Flows eingesetzt werden, etwa als KI-Teammitglied, das 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 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 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 Anfrage gemischt werden.

Ein Bereich (delegiert) oder eine App-Rolle (Anwendung) ist die benannte Berechtigung, die Microsoft Entra in das Zugriffstoken aufnimmt. Bei der Agent 365-Telemetrie lautet 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 den autonomen Flow (S2S/Clientanmeldeinformationen). Landet im roles-Anspruch. Ausgewählt von <resource>/.default.
  • Delegierter Gültigkeitsbereich für den OBO-Flow. Landet im scp-Anspruch. 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.

Füge die Berechtigung zu deiner App hinzu

  • 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 Blueprint gilt: Agents, die auf der Grundlage eines Agent-Identitätsblueprints von 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, empfängt sie automatisch. Siehe Konfigurieren vererbbarer Berechtigungen für Agentidentitäts-Blueprints.

Bevor Token die Rolle bzw. den Bereich übernehmen, muss ein Mandantenadmin im Mandanten des Kunden 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.

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

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 429 muss Retry-After beachtet werden (auf 1 Sekunde festgelegt); Backoff mit Jitter.

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: Ratengrenzwert erreicht; Retry-After: 1 beachten und Backoff mit Jitter durchführen.

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} Verwerfen pro Span. Angezeigt 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 gibt 200 OK zurück, 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

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.

Experience Description
Microsoft Defender Agentaktivität (invoke_agent, execute_tool, chat) wird in den Agent-Aktivitätsansichten angezeigt. 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 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 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: 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

  • Last updated on