Agent-Observability direkt mit OTel integrieren

Dieser Leitfaden führt Sie Schritt für Schritt durch den gesamten Prozess des Sendens von Agent-Telemetrie an Agent 365 direkt über OpenTelemetry (OTLP/HTTP+JSON). Bevor Sie beginnen, lesen Sie die Konzepte der Agent 365-Observierbarkeit , um das Modell zu verstehen, die Authentifizierungsflüsse und die Oberflächen, in die Ihre Daten gelangen.

Prerequisites

Stellen Sie sicher, dass die folgenden Konfigurationen eingerichtet sind, bevor Telemetriedaten übertragen werden.

Authentifizierungsrezepte

Alle vier Rezepte verwenden den standardmäßigen Microsoft Entra Tokenendpunkt:

Die nachstehenden Rezepte zeigen unformatiertes HTTP zur Übersichtlichkeit. Bevorzugen Sie in der Produktion Microsoft. Identity.Web oder eine andere MSAL-Bibliothek, die die Tokenaktualisierung und -zwischenspeicherung verarbeitet.

Welches Rezept benötige ich?

S2S, Standard Microsoft Entra App

Ein POST an den Tokenendpunkt des Mandanten mit grant_type=client_credentials. Authentifizieren Sie die App mithilfe eines geheimen Clientschlüssels, eines Zertifikats (signierter JWT-Assertion) oder einer verwalteten Identität oder Verbundanmeldeinformationen.

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_secret={secret}
&grant_type=client_credentials

Das zurückgegebene Token enthält appid/azp = {your-app-id}, roles enthält Agent365.Observability.OtelWriteund .aud = 9b975845-... Verwenden Sie es auf der /observabilityService/.../traces-Route.

Ersetzen Sie für die zertifikatbasierte Authentifizierung client_secret={secret} durch client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, Vom Blueprint abgeleitete Agentidentität

Agentidentitäten besitzen keine eigenen Anmeldeinformationen. Der Agentidentitäts-Blueprint enthält die Anmeldeinformationen (verwaltete Identitäten FIC, Zertifikat oder geheimen Clientschlüssel) und stellt Token im Auftrag seiner untergeordneten Agentidentitäten über einen zweistufigen Austausch bereit. Weitere Informationen finden Sie unter OAuth-Ablauf für eigenständige Apps.

1. Der Blueprint authentifiziert sich und ruft ein Verbundidentitätsaustauschtoken T1ab:

   • {blueprint-credential} ist das MSI-Token, das zertifikatsignierte JWT oder die geheime Exchange-Token-Assertion des Blueprints – je nach Blueprint-Konfiguration.

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={blueprint-app-id}
   &scope=api%3A%2F%2FAzureADTokenExchange%2F.default
   &fmi_path={agent-identity-app-id}
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={blueprint-credential}
   &grant_type=client_credentials
   

2. Die Agentenidentität tauscht T1 gegen das Ressourcentoken für Agent 365 Observability ein:

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={agent-identity-app-id}
   &scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={T1}
   &grant_type=client_credentials
   

   • Das zurückgegebene Token enthält appid/azp = {agent-identity-app-id}, roles enthält Agent365.Observability.OtelWriteund .aud = 9b975845-...
   • Verwenden Sie dieses Token auf der /observabilityService/.../traces Route.
   • Die URL {agentId} ist die Agent-Identitäts-appId, nicht die Blueprint-AppId.

OBO, Standard Microsoft Entra App

Empfangen Sie das eingehende Token Tc des Benutzers von Ihrem upstream-Aufrufer (Bearer oder PFAT), und tauschen Sie es aus:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_secret={secret}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

Ersetzen Sie bei der Zertifikatauthentifizierung client_secret={secret} durch dasselbe client_assertion_type + client_assertion-Paar wie bei S2S.

Das zurückgegebene Token enthält appid/azp = {your-app-id}, scp enthält Agent365.Observability.OtelWriteund .aud = 9b975845-... Verwenden Sie sie auf der /observability/.../traces Route. Zusätzlich wird ein Refresh-Token zurückgegeben; speichern Sie es im Cache und verwenden Sie es wieder, anstatt den Austauschvorgang bei jedem Aufruf erneut auszuführen.

OBO, Vom Blueprint abgeleitete Agentidentität (einschließlich KI-Teamkollegen)

Es gibt drei Hauptschritte des On-behalf-of-Flows. Weitere Informationen finden Sie unter "Agent OAuth flows: On behalf of flow".

1. Empfangen des Benutzertokens Tc. Für einen KI-Teamkollegen stellt dieses Token das eigene Benutzerkonto des Agenten dar; andernfalls stellt sie den menschlichen Aufrufer dar.

2. Das Blueprint authentifiziert sich und ruft T1 ab, genauso wie der aus dem S2S-Blueprint abgeleitete Agent-Identitätsfluss.

3. Die Agentenidentität tauscht T1 und Tc gegen ein delegiertes Ressourcentoken aus:

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={agent-identity-app-id}
   &scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={T1}
   &grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
   &assertion={Tc}
   &requested_token_use=on_behalf_of
   

Das zurückgegebene Token enthält appid/azp = {agent-identity-app-id}, scp enthält Agent365.Observability.OtelWriteund stellt den Benutzer des Agents dar. Verwenden Sie es für die /observability/.../traces-Route. Die URL {agentId} ist die Agent-Identitäts-appId, nicht die Blueprint-AppId. Daneben wird ein Aktualisierungstoken zurückgegeben; zwischenspeichern und wiederverwenden.

Erforderliche Ansprüche für das zurückgegebene Token

S2S-Route (/observabilityService/...) – Nur-App-Token:

Delegierte Route (/observability/...) - benutzerdelegiertes Token (Bearer oder PFAT):

Die delegierte Route akzeptiert sowohl Bearer- als auch MSAuth1.0 PFAT-Token. Direkte Anrufer sollten verwenden Bearer. Wenn Sie nicht wissen, welches Sie haben, verwenden Sie Bearer.

Endpoints

Zwei Routen; wählen Sie aus, wie Sich Ihr Dienst authentifiziert, nicht durch die Aktionen des Benutzers:

POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1   # S2S
POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1          # OBO

Kopfzeilen:

Authorization: Bearer <token>      # or MSAuth1.0 ... for delegated PFAT
Content-Type: application/json

URL-Parameter

• {tenantId} - die Kundenmandanten-GUID. Der Server behandelt dies als autoritativ; wenn Ihre Spanne festgelegt microsoft.tenant.id ist und dies nicht stimmt, wird die Anforderung abgelehnt.
• {agentId} - die appId der aufrufenden Anwendung (auch OAuth client_id). Bei aus Blueprints abgeleiteten Identitäten ist dies die appId der Agent-Identität, nicht die appId des Blueprints. Muss mit dem appid / azp Claim Ihres Tokens übereinstimmen.
• api-version=1 - erforderlich.

Kodierung des Anfragetexts

Der Body hat die Standardstruktur von OTLP/HTTP+JSON: eine ExportTraceServiceRequest mit resourceSpans → scopeSpans → spans. Beachten Sie die folgenden Details:

• traceId (16 Byte) und spanId (8 Byte) werden als hexadezimale Zeichenfolgen in Kleinbuchstaben gesendet.
• startTimeUnixNano / endTimeUnixNano sind Zeichenfolgen , die Unix-Epochen-Nanosekunden enthalten.
• kind ist der ganzzahlige OTLP-Enumerationswert (z. B. 1 für INTERNAL); status.code ist die ganzzahlige Enumeration (z. B. 1 für OK, 2 für ERROR).
• Alle Attributwerte werden als stringValuegesendet.

Antwortform

Ein erfolgreicher Aufruf gibt folgendes zurück 200 OK:

{ "partialSuccess": null }

Wenn einige Textspannen durch den Filter pro Textspanne abgelehnt wurden:

{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "Dropped 2 non-A365 span(s) ..."
  }
}

Feldnamen werden bei der Übertragung in camelCase geschrieben. Immer überprüfen partialSuccess: Eine 200 mit allen abgelehnten Spannen ist ein echtes Ergebnis, das Sie anzeigen müssen. Grenzen und Bedingungen für das Verwerfen listet die Fälle stillen Verwerfens auf, in denen 200 mit partialSuccess: null zurückgegeben wird, obwohl nachgelagert keine Daten erscheinen.

Kleinste mögliche Anforderung

Der einfachste End-to-End-Test sendet eine einzelne invoke_agent Spanne. Diese Spanne ist der kleinste Körper, der in Microsoft Defender landet.

Schritt 1. Rufen Sie ein Bearer-Token ab. Verwenden Sie für S2S Clientanmeldeinformationen mit Bereich 9b975845-388f-4429-889e-eab1ef63949c/.default (siehe Authentifizierungsrezepte für das vollständige Rezept).

Schritt 2. Eine einzelne Spanne per POST senden:

TOKEN="$(./get-token.sh)"
TENANT_ID="<customer-tenant-guid>"
AGENT_ID="<your-agent-app-id>"

curl -i -X POST \
  "https://agent365.svc.cloud.microsoft/observabilityService/tenants/${TENANT_ID}/otlp/agents/${AGENT_ID}/traces?api-version=1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "resourceSpans": [{
    "scopeSpans": [{
      "scope": { "name": "my-instrumentation", "version": "1.0.0" },
      "spans": [{
        "traceId": "0102030405060708090a0b0c0d0e0f10",
        "spanId":  "1111111111111111",
        "parentSpanId": "",
        "name": "invoke_agent",
        "kind": 1,
        "startTimeUnixNano": "1736175600000000000",
        "endTimeUnixNano":   "1736175601500000000",
        "status": { "code": 1 },
        "attributes": [
          { "key": "gen_ai.operation.name", "value": { "stringValue": "invoke_agent" } },
          { "key": "gen_ai.agent.id",       "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.agent.name",     "value": { "stringValue": "MyAgent" } },
          { "key": "microsoft.a365.agent.blueprint.id", "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.conversation.id","value": { "stringValue": "conv-001" } },
          { "key": "microsoft.channel.name","value": { "stringValue": "web" } },
          { "key": "user.id",               "value": { "stringValue": "<entra-user-objectid>" } },
          { "key": "client.address",        "value": { "stringValue": "10.1.2.80" } },
          { "key": "server.address",        "value": { "stringValue": "myagent.example.com" } },
          { "key": "server.port",           "value": { "stringValue": "443" } },
          { "key": "gen_ai.input.messages", "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"hi\"}]" } },
          { "key": "gen_ai.output.messages","value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"hello\"}]" } }
        ]
      }]
    }]
  }]
}
EOF

Schritt 3: Mit diesem Textkörper erwarten 200 OK :

{ "partialSuccess": null }

Schritt 4. Bestätigen Sie, dass die Daten tatsächlich gelandet sind. Ein 200 OK ist kein Nachweis für die Erfassung; Erfassung verifizieren erläutert den Verifizierungsablauf. Um stattdessen eine gespeicherte Body-Datei zu POSTEN, ersetzen Sie --data @- <<EOF ... EOF durch --data @./otlp-request.json.

Beispiel für einen Agentenlauf

Ein Benutzer auf Microsoft Teams fragt "Was ist das Wetter in Seattle?". Ihr Agent ruft eine GetWeather Funktion auf, bittet ein LLM, die Antwort zu formatieren, und antwortet. Dieser einzelne Lauf umfasst vier Abschnitte:

graph TD
    A["<b>invoke_agent</b> · spanId=A · parentSpanId=∅<br/><i>root - the run itself</i>"]
    B["<b>chat</b> · spanId=B · parentSpanId=A<br/><i>LLM picks the tool / formats reply</i>"]
    C["<b>execute_tool</b> · spanId=C · parentSpanId=A<br/><i>the GetWeather call</i>"]
    D["<b>output_messages</b> · spanId=D · parentSpanId=A<br/><i>final reply emitted to the user</i>"]
    A --> B
    A --> C
    A --> D

Laufweite Attribute, die für jede every Textspanne festgelegt sind:

Span A: invoke_agent (Wurzel)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "1111111111111111",
  "parentSpanId": "",
  "name": "invoke_agent",
  "kind": 1,
  "startTimeUnixNano": "1736175600000000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",   "value": { "stringValue": "invoke_agent" } },
    { "key": "gen_ai.execution.type",   "value": { "stringValue": "HumanToAgent" } },
    { "key": "gen_ai.input.messages",   "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"What's the weather in Seattle?\"}]" } },
    { "key": "gen_ai.output.messages",  "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } },
    { "key": "user.email",              "value": { "stringValue": "alice@contoso.com" } }
    /* plus all the run-wide attributes listed above */
  ]
}

Span B: chat (LLM-Aufruf)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "2222222222222222",
  "parentSpanId": "1111111111111111",
  "name": "chat",
  "kind": 1,
  "startTimeUnixNano": "1736175600200000000",
  "endTimeUnixNano":   "1736175600900000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "chat" } },
    { "key": "gen_ai.request.model",       "value": { "stringValue": "gpt-4o" } },
    { "key": "gen_ai.provider.name",       "value": { "stringValue": "openai" } },
    { "key": "gen_ai.usage.input_tokens",  "value": { "stringValue": "42" } },
    { "key": "gen_ai.usage.output_tokens", "value": { "stringValue": "23" } }
    /* plus all the run-wide attributes */
  ]
}

Span C: execute_tool

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "3333333333333333",
  "parentSpanId": "1111111111111111",
  "name": "execute_tool",
  "kind": 1,
  "startTimeUnixNano": "1736175600950000000",
  "endTimeUnixNano":   "1736175601200000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "execute_tool" } },
    { "key": "gen_ai.tool.name",           "value": { "stringValue": "GetWeather" } },
    { "key": "gen_ai.tool.type",           "value": { "stringValue": "function" } },
    { "key": "gen_ai.tool.call.id",        "value": { "stringValue": "call-001" } },
    { "key": "gen_ai.tool.call.arguments", "value": { "stringValue": "{\"location\":\"Seattle\"}" } },
    { "key": "gen_ai.tool.call.result",    "value": { "stringValue": "{\"tempF\":65,\"condition\":\"partly cloudy\"}" } }
    /* plus all the run-wide attributes */
  ]
}

Span D: output_messages

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "4444444444444444",
  "parentSpanId": "1111111111111111",
  "name": "output_messages",
  "kind": 1,
  "startTimeUnixNano": "1736175601400000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",  "value": { "stringValue": "output_messages" } },
    { "key": "gen_ai.output.messages", "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } }
    /* plus all the run-wide attributes */
  ]
}

Senden von Telemetrie

Verwenden eines OTel-SDK

Die meisten Partner senden Traces über ein OTel-SDK statt über selbst implementiertes HTTP. Das SDK übernimmt für Sie die Stapelverarbeitung, Wiederholungsversuche und die OTLP/HTTP+JSON-Kodierung. Legen Sie den Exporter-Endpunkt fest und fügen Sie den Authorization-Header ein.

Der Exporterendpunkt ist die Routen-URL selbst, einschließlich der Abfragezeichenfolge:

https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1

(Verwenden Sie /observability/... anstelle von /observabilityService/... für die delegierte Route.)

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
    headers={"Authorization": f"Bearer {token}"},
)

Paket: opentelemetry-exporter-otlp-proto-http.

Node.js / TypeScript

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const exporter = new OTLPTraceExporter({
  url: "https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
  headers: { Authorization: `Bearer ${token}` },
});

Paket: @opentelemetry/exporter-trace-otlp-http.

.NET

using OpenTelemetry.Exporter;

services.AddOpenTelemetry().WithTracing(b => b
    .AddOtlpExporter(o =>
    {
        o.Endpoint = new Uri("https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1");
        o.Headers = $"Authorization=Bearer {token}";
        o.Protocol = OtlpExportProtocol.HttpJson;
    }));

Paket: OpenTelemetry.Exporter.OpenTelemetryProtocol.

HTTP manuell

Wenn Sie kein OTel-SDK verwenden können oder möchten, erstellen Sie die OTLP/HTTP+JSON-Anfrage selbst und senden Sie sie per POST. Die Struktur des Nachrichtentexts wird durch die OpenTelemetry-OTLP/HTTP+JSON-Spezifikation definiert:

{
  "resourceSpans": [{
    "resource":  { "attributes": [ ... ] },          // optional
    "scopeSpans": [{
      "scope":  { "name": "<your-instrumentation>", "version": "1.0.0" },
      "spans":  [ <span>, <span>, ... ]
    }]
  }]
}

Jedes <span> Objekt ist ein Objekt, dessen erforderliche Felder sind traceId, , spanId, name, kind, startTimeUnixNano, endTimeUnixNano, , und attributes(für Nicht-Stamm-Spans) parentSpanId. Siehe Endpunkte und Kodierung des Anforderungstexts für die Kodierungsregeln (als Zeichenfolge kodierte Zeitangaben, Hex traceId / spanId, Ganzzahlen kind / status.code, alle Attributwerte als stringValue).

Der Satz von Attributen, die für jeden Bereich festgelegt werden sollen, wird in Nachrichtenverträgen definiert. Siehe Attributreferenz für die vollständige Attributliste. Verweisen Sie auf das Agent-Ausführungsbeispiel für ein End-to-End-Arbeitsbeispiel mit dem Bearer-Token in der Kopfzeile und dem Textkörper inline.

Sie können alle Spannen einer Ausführung in einem einzelnen POST-Textkörper (bevorzugt – eine Anforderung, eine Ablaufverfolgung) oder über mehrere POSTs senden. Der Server rekonstruiert den Ablauf anhand von traceId + parentSpanId + gen_ai.conversation.id, sodass jeder Span genügend Informationen enthält, um in beide Richtungen korreliert werden zu können.

Nachrichtenverträge

In diesem Abschnitt wird definiert, welche Spans Sie erzeugen können und welche Attribute jeweils zu ihnen gehören. Die vollständige Attribut-nach-Attribut-Spezifikation finden Sie in der Attributreferenz.

Vorgangstypen

Jede von Ihnen gesendete Zeitspanne muss einen dieser vier Werte aufweisen gen_ai.operation.name (Groß-/Kleinschreibung wird nicht beachtet). Alle Spannweiten mit einem fehlenden oder unbekannten Wert werden im Hintergrund gelöscht und in partialSuccess.rejectedSpansgezählt.

Span-Hierarchie und Run-Gruppierung

Agent 365 rekonstruiert einen Lauf aus dem Standard-OTLP-Span-Graphen (traceId, spanId, parentSpanId) sowie den für den Lauf geltenden Attributen aus der Attributreferenz.

Sechs Regeln:

1. Immer festlegen parentSpanId auf jeder Nicht-Stammspanne. Ohne sie kann die Baumstruktur des Laufs nicht rekonstruiert werden.
2. Dasselbe traceId über alle Spans in einem Durchlauf hinweg wiederverwenden.
3. Legen Sie gen_ai.conversation.id für jeden Bereich mit demselben Wert fest. Dies ist der primäre Verknüpfungsschlüssel für "alle Spans in dieser Ausführung". Sie wird nicht automatisch weitergegeben.
4. Legen Sie microsoft.channel.name für jeden Bereich mit demselben Wert fest. Tool-Spans, denen der Kanal bzw. die Konversation fehlen, können diese von ihrem übergeordneten Element invoke_agentnur dann erben, wenn sich das übergeordnete Element in derselben OTLP-Anfrage befindet. Legen Sie sie daher für jeden Span selbst fest.
5. Legen Sie microsoft.session.id für jede Spanne fest , wenn Sie eine logische Sitzung haben.
6. Verwenden Sie für Agent-zu-Agent-Aufrufe, bei denen sich der untergeordnete Agent in einer separaten Anfrage befindet, dasselbe gen_ai.conversation.id wieder und verwenden Sie die Attribute microsoft.a365.caller.agent.* (siehe Attributreferenz), um den Kontext des aufrufenden Agenten zu erfassen.

Die vierspannige Struktur im Beispiel für die Agent-Ausführung ist die kanonische Form.

Allgemeine Formen

Checkliste für die Einarbeitung

Führen Sie diese Checkliste durch, bevor Sie zur Produktion wechseln.

Nächste Schritte

• Attributreferenz – Spezifikation je Attribut und Leitfaden zur Wertauswahl.
• Problembehandlung : Überprüfen der Aufnahme, allgemeiner Fallstricke und Fehlerantworten.