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

Agent-Identitäten besitzen keine eigenen Anmeldeinformationen. Der Blueprint für die Agent-Identität enthält die Anmeldeinformationen (FIC für verwaltete Identitäten, Zertifikat oder geheimen Clientschlüssel) und stellt Token im Auftrag der untergeordneten Agent-Identitä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 Agent-Identitä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, standardmäßige 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-Flusses. 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} – Kundenmandanten-GUID. Der Server behandelt dies als maßgeblich; wenn Ihre Spans die microsoft.tenant.id festlegen und keine Übereinstimmung vorliegt, 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 Textkörper 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 Spans ist ein echtes Ergebnis, das Sie anzeigen müssen. Grenzen und Bedingungen für das Verwerfen listet die Fälle stillschweigenden 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. Dieser Span ist der kleinste Textkörper, der in Microsoft Defender landet.

Schritt 1. Rufen Sie ein Bearer-Token ab. Verwenden Sie für S2S Clientanmeldeinformationen mit dem 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 wir 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.

Agent-Ausführungsbeispiel

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

Ausführungsweite Attribute, die für jeden Span 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 Ablaufverfolgungen ü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. Unter Agent-Ausführungsbeispiel finden Sie ein End-to-End-Arbeitsbeispiel mit dem Bearertoken in der Kopfzeile und dem Textkörper inline.

Sie können alle Spans 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

Für jeden von Ihnen gesendeten Span muss gen_ai.operation.name einen dieser vier Werte aufweisen (Groß-/Kleinschreibung wird nicht beachtet). Alle Spans mit einem fehlenden oder nicht erkannten Wert werden im Hintergrund gelöscht und bei partialSuccess.rejectedSpans mitgezä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 für jeden Span, der kein Stammelement ist. Ohne sie kann die Baumstruktur des Laufs nicht rekonstruiert werden.
2. Verwenden Sie dieselbe traceId über alle Spans in einer Ausführung hinweg.
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, in denen der Kanal bzw. die Unterhaltung fehlen, können diese von ihrem übergeordneten invoke_agentnur dann erben, wenn sich das übergeordnete Element in derselben OTLP-Anforderung befindet. Legen Sie sie daher für jeden Span selbst fest.
5. Legen Sie microsoft.session.id für jeden Span 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 Anforderung befindet, dieselbe gen_ai.conversation.id wieder, und verwenden Sie die microsoft.a365.caller.agent.*-Attribute (siehe Attributreferenz), um den Kontext des aufrufenden Agents zu erfassen.

Die Struktur aus vier Spans im Agent-Ausführungsbeispiel ist die kanonische Form.

Allgemeine Ausführungsformen

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.