Integrera agentöverskådlighet via direkt OTel

Denna guide visar steg för steg hur du skickar agenttelemetri till Agent 365 direkt via OpenTelemetry (OTLP/HTTP+JSON). Innan du börjar, läs Agent 365:s överskådlighetskoncept för att förstå modellen, autentiseringsflödena och ytorna där dina data landar.

Krav

Säkerställ att följande konfigurationer är på plats innan någon telemetri skickas.

Autentiseringsrecept

Alla fyra recept använder den standardiserade Microsoft Entra-token-endpointen:

Recepten nedan visar rå HTTP för tydlighet. I produktion föredrar man Microsoft.Identity.Web eller ett annat MSAL-bibliotek, som hanterar tokenuppdatering och caching.

Vilket recept behöver jag?

S2S, standard Microsoft Entra-app

Ett POST-anrop till klientorganisationens token-endpunkt med grant_type=client_credentials. Autentisera appen genom att använda en klienthemlighet, ett certifikat (signerad JWT-assertion) eller en hanterad identitet eller federerad legitimation.

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

Den returnerade token har appid/azp = {your-app-id}, roles innehållande Agent365.Observability.OtelWrite och aud = 9b975845-.... Använd denna på rutten /observabilityService/.../traces.

Vid autentisering med certifikat, ersätt client_secret={secret} med client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, Blueprint-härledd agentidentitet

Agentidentiteter har inga egna autentiseringsuppgifter. AgentidentitetsBlueprinten innehåller autentiseringsuppgifterna (managed identity FIC, certifikat eller klienthemlighet) och utfärdar tokens åt sina underordnade agentidentiteter via ett tvåstegsutbyte. För mer information, se OAuth-flöde för autonoma appar.

1. Blueprinten autentiserar och får en federerad identitetsbytestoken T1:

   • {blueprint-credential} är blueprintens MSI-token, certifikatsignerad JWT eller secret exchange-token assertion – enligt 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. Agentidentiteten byter T1 mot Agent 365 Observability-resurstoken:

   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
   

   • Den returnerade token har appid/azp = {agent-identity-app-id}, roles innehållande Agent365.Observability.OtelWrite och aud = 9b975845-....
   • Använd denna token på rutten /observabilityService/.../traces.
   • URL: {agentId} är agentidentitetens appId, inte Blueprint-appId.

OBO, standard Microsoft Entra-app

Ta emot användarens inkommande token Tc från din uppströmsanropare (Bearer eller PFAT), och växla den:

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

Vid autentisering med certifikat, ersätt client_secret={secret} med samma client_assertion_type + client_assertion-par som i S2S.

Den returnerade token har appid/azp = {your-app-id}, scp innehållande Agent365.Observability.OtelWrite och aud = 9b975845-.... Använd denna på rutten /observability/.../traces. En uppdateringstoken returneras bredvid; cacha och återanvänd den istället för att köra Exchange på varje samtal.

OBO, Blueprint-härledd agentidentitet (inklusive AI-teammedlem)

Det finns tre huvudsakliga steg i On-Behalf-Of-flödet. För mer information, se Agent OAuth-flöden: On-behalf-of-flödet.

1. Ta emot användartoken Tc. För en AI-lagkamrat representerar denna token agentens eget användarkonto; annars representerar den den mänskliga användaren.

2. Blueprinten autentiserar sig och får T1, samma som S2S-flödet för blueprint-baserad agentidentitet.

3. Agentidentiteten utbyter T1 och Tc mot en delegerad resurstoken:

   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
   

Den returnerade token har appid/azp = {agent-identity-app-id}, scp som innehåller Agent365.Observability.OtelWrite och representerar agnetens användare. Använd denna på rutten /observability/.../traces. URL: {agentId} är agentidentitetens appId, inte Blueprint-appId. En uppdateringstoken returneras bredvid; cache och återanvänd den.

Obligatoriska krav på den returnerade token

S2S-rutt (/observabilityService/...) - app-endast token:

Delegerad rutt (/observability/...) - användardelegerad token (bärare eller PFAT):

Den delegerade rutten accepterar både Bearer och MSAuth1.0 PFAT tokens. Direktuppringare bör använda Bearer. Om du inte vet vilken du har, använd Bearer.

Slutpunkter

Två rutter; välj utifrån hur din tjänst autentiserar, inte utifrån vad användaren gör:

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

Sidhuvuden

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

URL-parametrar

• {tenantId} - GUID för kundklientorganisation. Servern betraktar detta som auktoritativt; om dina spans sätter microsoft.tenant.id och det inte stämmer överens, avslås begäran.
• {agentId} - den anropande applikationens appId (även OAuth client_id). För Blueprint-baserade identiteter är detta agentidentitetens appId, inte Blueprint-appId. Måste vara lika med appid / azp-anspråket i din token.
• api-version=1 – obligatoriskt.

Kodning av begärandetext

Kroppen följer standardformatet OTLP/HTTP+JSON: en ExportTraceServiceRequest med resourceSpans → scopeSpans → spans. Tänk på följande detaljer:

• traceId (16 byte) och spanId (8 byte) skickas som hexsträngar med små bokstäver.
• startTimeUnixNano / endTimeUnixNano är strängar som innehåller nanosekunder enligt Unix-epoken.
• kind är heltalsvärdet för OTLP-uppräkning (till exempel 1 för INTERNAL); status.code är heltals-uppräkning (till exempel 1 för OK, 2 för ERROR).
• Alla attributvärden skickas som stringValue.

Svarstruktur

Ett lyckat anrop returnerar 200 OK:

{ "partialSuccess": null }

Om vissa spann avvisades av per-span-filtret:

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

Fältnamnen är camelCase vid överföring. Kontrollera alltid partialSuccess: en 200 med alla dina spann avvisade är ett verkligt scenario du måste hantera. Gränser och bortfallsförhållanden listar de tysta fallen där en 200 returneras med partialSuccess: null trots att ingen data dyker upp nedströms.

Minsta möjliga begäran

Det enklaste end-to-end-testet skickar ett enda invoke_agent spann. Detta spann är det minsta som hamnar i Microsoft Defender.

Steg 1. Hämta en Bearer-token. För S2S, använd klientuppgifter med omfattning 9b975845-388f-4429-889e-eab1ef63949c/.default (se autentiseringsguider för hela guiden).

Steg 2. POST ett enda span:

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

Steg 3. Förutom 200 OK med denna text:

{ "partialSuccess": null }

Steg 4. Bekräfta att data har mottagits. Ett 200 OK är inte bevis på dataintag; Verifiering av dataintag går igenom verifieringsflödet. För att POST:a en sparad body-fil istället, ersätt --data @- <<EOF ... EOF med --data @./otlp-request.json.

Exempel på agentkörning

En användare på Microsoft Teams frågar "Hur är vädret i Seattle?". Din agent anropar en GetWeather-funktion, ber en LLM att formatera svaret och svarar. Den här körningen består av fyra spann:

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

Körningsomfattande attribut satta på varje span:

Spann A: invoke_agent (rot)

{
  "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-anrop)

{
  "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 */
  ]
}

Sändning av telemetri

Användning av OTel SDK

De flesta partners skickar spår genom ett OTel SDK istället för egenskriven HTTP. SDK:n hanterar batchning, återförsök och OTLP/HTTP+JSON-kodning åt dig. Ställ in exportörens endpunkt och injicera Authorization header.

Exporter-endpointen är ruttens URL, inklusive frågesträngen:

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

(Använd /observability/... istället för /observabilityService/... för den delegerade rutten.)

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.

Manuell HTTP

Om du inte kan eller vill använda ett OTel SDK, bygg OTLP/HTTP+JSON-förfrågan själv och POSTA den. Body-strukturen definieras av OpenTelemetry OTLP/HTTP+JSON-specifikationen:

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

Varje <span> är ett objekt där de obligatoriska fälten är traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes och (för icke-rootspann) parentSpanId. Se Slutpunkter och Kodning av begärandetext för kodningsreglerna (strängkodade tider, hex traceId / spanId, heltal kind / status.code, alla attributvärden som stringValue).

Uppsättningen attribut som ska sättas på varje spann definieras i meddelandekontrakt. En fullständig lista över tabeller finns på Attributreferens. Se exemplet Agent run för ett end-to-end-arbetsprov med Bearer-token i headern och kroppen inline.

Du kan skicka alla spann av en körning i en enda POST-kropp (föredragen – en förfrågan, en spårning) eller över flera POST:ar. Servern återskapar körningen från traceId + parentSpanId + gen_ai.conversation.id, så varje spann innehåller tillräcklig information för att kunna korreleras oavsett metod.

Meddelandekontrakt

Detta avsnitt definierar vilka spann du kan skicka och vilka attribut som ska finnas på varje. För den fullständiga attributspecifikationen, se Attributreferensen.

Åtgärdstyper

Varje span du skickar måste ha gen_ai.operation.name satt till ett av dessa fyra värden (skiftlägesokänsligt). Alla spann med saknat eller icke erkänt värde tas tyst bort och räknas in i partialSuccess.rejectedSpans.

Spannhierarki och gruppering av körningar

Agent 365 återskapar en körning från standard OTLP-spangrafen (traceId, spanId, parentSpanId) plus de körningsövergripande attributen från attributreferensen.

Sex regler:

1. Alltid inställd parentSpanId på varje icke-rotspann. Utan den kan körningens trädstruktur inte rekonstrueras.
2. Återanvänd samma traceId över alla span i en körning.
3. Sätt gen_ai.conversation.id på varje spann med samma värde. Detta är den primära kopplingsnyckeln för "alla spann i denna körning". Den sprids inte automatiskt.
4. Sätt microsoft.channel.name på varje spann med samma värde. Verktygsspann som saknar kanal eller konversation kan ärva dem från sitt överordnade element invoke_agentendast om det överordnade elementet är med i samma OTLP-förfrågan, så sätt dem manuellt på varje spann.
5. Sätt microsoft.session.id på varje span när du har en logisk session.
6. För agent-till-agent-anrop där underordnad agent är i en separat förfrågan, återanvänd samma gen_ai.conversation.id och använd attributen microsoft.a365.caller.agent.* (se Attributreferens) för att fånga anroparagentens kontext.

Det fyrspans-träd som visas i Agent run-exemplet är den kanoniska formen.

Vanliga löpformer

Onboarding-checklista

Gå igenom denna checklista innan du går till produktionen.

Nästa steg

• Attributreferens – Specifikation, krav och vägledning för val av attributvärden per attribut.
• Felsökning – Verifierar intagning, vanliga fallgropar och felsvar.