Integrer agentobserverbarhed ved hjælp af direkte OTel

Denne guide fører dig trin for trin gennem processen med at sende agenttelemetri direkte til Agent 365 via OpenTelemetry (OTLP/HTTP+JSON). Inden du går i gang, læs Agent 365 observabilitetsprincipper for at forstå modellen, autentificeringsflowene og de overflader, hvor dine data placeres.

Vigtigt

Den direkte OTel-sti er undtagelsen, ikke standarden. Brug kun denne fremgangsmåde, hvis du allerede har en OpenTelemetry-pipeline, dit framework ikke kan bruge Agent 365 SDK, eller din agent er skrevet i et sprog, som SDK'en endnu ikke understøtter (f.eks. Java). For alle andre er den anbefalede vej Microsoft OpenTelemetry Distro, som tilbyder en samlet observabilitets-SDK på tværs af Agent 365, Microsoft Foundry, Azure Monitor m.fl. Den tidligere Observerbarheds SDK fungerer fortsat uden at medføre ændringer, der bryder kompatibiliteten, men anbefales ikke længere til nye integrationer. Migreringsvejledning for eksisterende SDK-brugere er på vej.

Forudsætninger

Sørg for, at følgende konfigurationer er på plads, før der sendes nogen telemetri.

Hvem	Hvad
Lejeradministrator	Tilmeld dig Agent 365 og giv samtykke til din agentapp. Se Kom i gang med Agent 365. Uden en licenseret lejer bliver indtagelsen stille droppet – anmodningen returneres `200 OK` med `partialSuccess: null` , men data vises aldrig længere nedstrøms.
Lejeradministrator	Tildel en Microsoft 365 E7- eller Microsoft Agent 365-licens til mindst én bruger i lejeren. SKU'en alene er ikke tilstrækkelig. Tildeling til en bruger starter Defender-backend-arbejdsprocessen, som muliggør dataindtagelse. Uden en tildelt licens returnerer anmodninger `200 OK` med `partialSuccess: null`, og data droppes uden varsel.
Lejeradministrator	Giv lejersamtykke. Se Giv adgang til Microsoft 365-ressourcer for agenter. Uden den udstedes tokens uden rollen/omfanget, og anmodninger returnerer `403`.
Dit udviklingsteam	Registrer din app (standard Microsoft Entra-app eller blueprint). Se Kom i gang med Agent 365-udvikling.
Dit udviklingsteam	Tilføj `Agent365.Observability.OtelWrite` under API-tilladelser (approlle for S2S, omfang for delegeret). For blueprints, se Konfigurer arvelige tilladelser. Koordiner med Agent 365 onboardingteamet for at aktivere tilladelsen.

Godkendelsesopskrifter

Alle fire opskrifter bruger det Microsoft Entra-token-standardslutpunkt:

Felt	Værdi
Tokenslutpunkt	`https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token`
Ressource (`aud` i returneret token)	`9b975845-388f-4429-889e-eab1ef63949c` (accepterer også `api://9b975845-388f-4429-889e-eab1ef63949c`)
S2S-omfang	`9b975845-388f-4429-889e-eab1ef63949c/.default`
OBO-omfang	`9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite`

Opskrifterne nedenfor viser rå HTTP for tydelighedens skyld. I produktion anbefales det at bruge Microsoft.Identity.Web eller et andet MSAL-bibliotek, som håndterer tokenfornyelse og cachelagring.

Hvilken opskrift skal jeg bruge?

Min app-model	Mit OAuth-flow	Gå til
Standard Microsoft Entra-appregistrering	S2S (klientlegitimationsoplysninger)	S2S, Standard Microsoft Entra-app
Standard Microsoft Entra-appregistrering	OBO (delegeret)	OBO, Standard Microsoft Entra-app
Blueprint-afledt agentidentitet	S2S (klientlegitimationsoplysninger)	S2S, Blueprint-afledt agentidentitet
Blueprint-afledt agentidentitet	OBO / AI-teammedlem	OBO, Blueprint-afledt agentidentitet

S2S, Standard Microsoft Entra-app

En POST til lejerens tokenslutpunkt med grant_type=client_credentials. Godkend appen ved at bruge en klienthemmelighed, et certifikat (signeret JWT-assertion) eller en administreret identitet eller legitimationsoplysning i organisationsnetværket.

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

Det returnerede token har appid/azp = {your-app-id}, roles der indeholder Agent365.Observability.OtelWrite, og aud = 9b975845-.... Brug det på /observabilityService/.../traces-ruten.

For certifikatbaseret godkendelse erstattes client_secret={secret} med client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, Blueprint-afledt agentidentitet

Agentidentiteter har ikke deres egne legitimationsoplysninger. Blueprintet for agentidentitet indeholder legitimationsoplysningerne (administreret id FIC, certifikat eller klienthemmelighed) og udsteder tokens på vegne af sine underordnede agentidentiteter gennem en totrinsudveksling. For yderligere information, se autonomt app OAuth-flow.

Blueprinten godkender sig og modtager en identitetsudvekslingstoken i organisationsnetværk T1:

{blueprint-credential} er blueprintets MSI-token, certifikatsigneret JWT eller hemmelig exchange-token-assertion – pr. 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

Agentidentiteten udveksler T1 for Agent 365-observerbarheds ressourcetoken:

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

Det returnerede token har appid/azp = {agent-identity-app-id}, roles der indeholder Agent365.Observability.OtelWrite, og aud = 9b975845-....
Brug dette token på ruten /observabilityService/.../traces.
URL'en {agentId} er agentidentitetens appId, ikke blueprint appId.

OBO, Standard Microsoft Entra-app

Modtag brugerens indkommende token Tc fra din upstream-opkalder (Bearer eller PFAT), og udveksl det derefter:

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

For certifikatgodkendelse, erstat client_secret={secret} med det samme client_assertion_type + client_assertion-par som i S2S.

Det returnerede token har appid/azp = {your-app-id}, scp der indeholder Agent365.Observability.OtelWrite, og aud = 9b975845-.... Brug det på /observability/.../traces-ruten. Et opdateringstoken returneres ved siden af. Cache og genbrug den i stedet for at køre udveksling igen ved hvert opkald.

OBO, Blueprint-afledt agentidentitet (inklusive AI-teammedlem)

Der er tre hovedtrin i On-Behalf-Of-flowet. For yderligere information, se Agent OAuth flows: On behalf of-flow.

Modtag brugertokenet Tc. For en AI-holdkammerat repræsenterer dette token agentens egen brugerkonto. Ellers repræsenterer det den menneskelige opkalder.
Blueprintet godkendes og får T1, på samme måde som blueprint-afledte agentidentitets-flowet for S2S.

Agentidentiteten veksler T1 og Tc til et delegeret ressourcetoken:

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

Det returnerede token har appid/azp = {agent-identity-app-id}, scp, der indeholder Agent365.Observability.OtelWrite, og repræsenterer agentens bruger. Brug det på /observability/.../traces-ruten. URL'en {agentId} er agentidentitetens appId, ikke blueprint appId. Et opdateringstoken returneres ved siden af. Du skal cachelagre og genbruge det.

Nødvendige krav på det returnerede token

S2S-rute (/observabilityService/...) - app-only-token:

Krav	Påkrævet værdi
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (eller `api://9b975845-...`)
`roles`	Skal indeholde `Agent365.Observability.OtelWrite`
`appid` (v1) eller `azp` (v2)	Skal være lig med URL `{agentId}`
`scp`	Skal være fraværende

Delegeret rute (/observability/...) - brugerdelegeret token (Bearer eller PFAT):

Krav	Påkrævet værdi
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (eller `api://9b975845-...`)
`scp`	Skal indeholde `Agent365.Observability.OtelWrite`
`appid` / `azp`	Skal være lig med URL `{agentId}`

Den delegerede rute accepterer både Bearer- og MSAuth1.0 PFAT-tokens. Direkte opkaldere bør bruge Bearer. Hvis du ikke ved, hvilken du har, brug Bearer.

Slutpunkter

To ruter. Vælg ud fra, hvordan din tjeneste autentificerer, ikke ud fra hvad brugeren 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

Overskrifter:

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

URL-parametre

{tenantId} - kundelejerens GUID. Serveren betragter dette som autoritativt. Hvis dine spænd angiver microsoft.tenant.id, og det ikke stemmer overens, afvises anmodningen.
{agentId} - det kaldende programs appId (også OAuth client_id). For blueprint-afledte identiteter er dette agentidentitet appId, ikke blueprint appId. Skal svare til kravet appid / azp i din token.
api-version=1 - påkrævet.

Anmod om kodning af brødtekst

Brødteksten er på standard OTLP/HTTP+JSON-form: en ExportTraceServiceRequest med resourceSpans → scopeSpans → spans. Vær opmærksom på følgende detaljer:

traceId (16 byte) og spanId (8 byte) sendes som hex-strenge med små bogstaver.
startTimeUnixNano / endTimeUnixNano er strenge som indeholder Unix-epokens nanosekunder.
kind er heltallets OTLP enum-værdi (for eksempel 1 for INTERNAL); status.code er heltallets enum-værdi (for eksempel 1 for OK, 2 for ERROR).
Alle attributværdier sendes som stringValue.

Svarstruktur

Et vellykket opkald returnerer 200 OK:

{ "partialSuccess": null }

Hvis nogle spænd blev afvist af per-spænd-filteret:

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

Feltnavne er camelCase i tråden. Tjek altid partialSuccess: en 200 med alle dine spænd afvist er et reelt resultat, du skal håndtere. Grænser og betingelser for bortfald viser de stille bortfaldstilfælde, hvor en 200 returnerer med partialSuccess: null, selvom der ikke vises data nedstrøms.

Mindst mulige anmodning

Den simpleste totaltest sender et enkelt invoke_agent spænd. Dette spænd er den mindste brødtekst, der lander i Microsoft Defender.

Trin 1. Hent et ihændehavertoken. For S2S skal du bruge klientlegitimationsoplysninger med omfanget 9b975845-388f-4429-889e-eab1ef63949c/.default (se Godkendelsesopskrifter for den fulde opskrift).

Trin 2. POST et enkelt spænd:

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

Trin 3. Forvent 200 OK med denne brødtekst:

{ "partialSuccess": null }

Trin 4. Bekræft, at dataene faktisk blev indlæst. En 200 OK er ikke bevis for indtagelse. Verificering af indtagelse gennemgår verificeringsflowet. For POST af en gemt brødtekst-fil i stedet, erstat --data @- <<EOF ... EOF med --data @./otlp-request.json.

Agentkørselseksempel

En bruger på Microsoft Teams spørger: "Hvordan er vejret i Seattle?" Din agent kalder en GetWeather-funktion, beder en LLM om at formatere svaret og svarer. Den ene kørsel er fire spænd:

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ørselsdækkende attributter angivet på hvert spænd:

Attribut	Eksempelværdi
`traceId`	`0102030405060708090a0b0c0d0e0f10`
`gen_ai.conversation.id`	`19:abc@thread.tacv2`
`microsoft.session.id`	`session-1234`
`microsoft.channel.name`	`msteams`
`gen_ai.agent.id`	`<AGENT_APP_ID>`
`gen_ai.agent.name`	`WeatherBot`
`microsoft.a365.agent.blueprint.id`	`<BLUEPRINT_APP_ID>`
`user.id`	`<entra-user-objectid>`
`client.address`	`10.1.2.80`
`server.address`	`weatherbot.example.com`
`server.port`	`443`

Vigtigt

Disse kørselsdækkende attributter overføres ikke automatisk. Du skal selv angive gen_ai.conversation.id, microsoft.channel.name og microsoft.session.id på hvert spænd.

Spænd A: `invoke_agent` (rod)

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

Spænd B: `chat` (LLM-kald)

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

Spænd 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 */
  ]
}

Spænd 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 */
  ]
}

Telemetri-udsendelse

Brug af OTel SDK

De fleste partnere sender spor via OTel SDK i stedet for manuel HTTP. SDK'en håndterer batchkørsel, nye forsøg og OTLP/HTTP+JSON-kodning for dig. Angiv eksportørens slutpunkt, og indtag Authorization header.

Eksportørens slutpunkt er selve rute-URL'en, inklusive forespørgselsstrengen:

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

(Brug /observability/... i stedet for /observabilityService/... den delegerede rute.)

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}"},
)

Pakke: 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}` },
});

Pakke: @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;
    }));

Pakke: OpenTelemetry.Exporter.OpenTelemetryProtocol.

Manuel HTTP

Hvis du ikke kan eller ikke vil bruge et OTel SDK, så lav selv OTLP/HTTP+JSON-anmodningen og POST den. Brødtekstformen defineres af OpenTelemetry OTLP/HTTP+JSON-specifikationen:

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

Hvert <span> er et objekt, hvis påkrævede felter er traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes og (for ikke-rodspænd) parentSpanId. Se Slutpunkter og Anmod om kodning af brødtekst for kodningsreglerne (strengkodede tider, heksadecimal traceId / spanId, heltals kind / status.code, alle attributværdier som stringValue).

De attributter, der skal sættes på hvert spænd, er defineret i Meddelelseskontrakter. Du kan se hele attributlisten i Attributreference. Se Agentkørselseksempel for et fuldt eksempel med Bearer-tokenet i headeren og brødteksten indbygget.

Du kan sende alle spænd fra en kørsel i én POST-brødtekst (foretrukket – én anmodning, ét spor) eller fordelt på flere POST'er. Serveren rekonstruerer kørselen ud fra traceId + parentSpanId + gen_ai.conversation.id, så hvert spænd indeholder nok information til at kunne korreleres uanset metode.

Meddelelseskontrakter

Dette afsnit definerer, hvilke spænd du kan udsende, og hvilke attributter der skal bruges til hver. For den fulde attribut-for-attribut-specifikation, se Attributreference.

Handlingstyper

Hvert spænd, du sender, skal have gen_ai.operation.name sat til en af disse fire værdier (ingen forskel på store og små bogstaver). Ethvert spænd med en manglende eller ikke-genkendt værdi droppes uovervåget og tælles med i partialSuccess.rejectedSpans.

`gen_ai.operation.name`	Betydning	Den mest googlede gotcha
`invoke_agent`	En påkaldelse af en agent. "Roden" af en agentkørsel.	Påkrævet for at kørslen kan vises i Microsoft Defender agentaktivitetsvisninger eller Microsoft 365 Administration. Uden dette placeres telemetrien kun i Microsoft Defender avanceret jagt (`CloudAppEvents`).
`execute_tool`	Et værktøjs-/funktionskald udført af en agent.	--
`chat`	Et LLM-inferenskald.	Brug den bogstavelige `chat`, IKKE `inference`.
`output_messages`	En endelig udsendt outputbesked.	--

Spændhierarki og kørselsgruppering

Agent 365 rekonstruerer en kørsel ud fra den standard OTLP-spænd-graf (traceId, spanId, parentSpanId) samt de kørselsdækkende attributter fra attributreferencen.

Seks regler:

Sæt altid parentSpanId på alle ikke-rod spænd. Uden den kan kørselens træstruktur ikke rekonstrueres.
Genbrug det samme traceId på tværs af alle spænd i en kørsel.
Sæt gen_ai.conversation.id på hvert spænd med samme værdi. Dette er den primære joinforbindesnøgle for "alle spænd i denne kørsel". Det overføres ikke automatisk.
Sæt microsoft.channel.name på hvert spænd med samme værdi. Værktøjsspænd, der mangler kanalen/samtalen, kan arve dem fra deres overordnede, men invoke_agentkun hvis overordnet er i samme OTLP-anmodning, så sørg for selv at sætte dem på hvert spænd.
Sæt microsoft.session.id på hvert spænd når du har en logisk session.
Ved agent-til-agent-kald, hvor den underordnede agent er i en separat anmodning, skal du genbruge den samme gen_ai.conversation.id og bruge microsoft.a365.caller.agent.* attributterne (se Attributreference) for at optage opkaldsagentens kontekst.

Firespænds-træet i Agentkørselseksemplet er den kanoniske form.

Almindelige kørselsformer

Figur	Spænd, der skal udsendes	Bemærkninger
Enkeltagent-chatrobot (ingen værktøjer, intet LLM-spænd)	Kun én `invoke_agent`	Sæt kørselsdækkende attributter plus `gen_ai.input.messages` og `gen_ai.output.messages`. Identisk med den mindste mulige anmodning.
Agent med værktøjer (mest almindeligt)	`invoke_agent` rod + `chat`, `execute_tool`, `output_messages` underordnede	Alle underordnede deler rodens `traceId` og sætter `parentSpanId = root.spanId`. Alle har de samme kørselsdækkende attributter. Se Agentkørselseksemplet for et komplet eksempel.
Agent-til-agent	Hver agent udsender sin egen `invoke_agent`	Genbrug det samme `gen_ai.conversation.id` på tværs af begge agenter. På målets `invoke_agent`, sæt `gen_ai.execution.type = "Agent2Agent"` og attributterne `microsoft.a365.caller.agent.*` (kaldende agents `appId`, navn, blueprint `appId`, bruger-id og e-mail). Hvis den kaldende agent ikke har Entra-registrering, brug `microsoft.a365.caller.agent.platform.id` og `gen_ai.caller.agent.type` i stedet.

Onboarding tjekliste

Gennemgå denne tjekliste, inden du går i produktion.

Kategori	Check
Godkendelse	Din Entra-app (eller blueprint) er registreret, og du kan udstede tokens for den.
Godkendelse	Din app har fået tildelt `Agent365.Observability.OtelWrite` (app-rolle til S2S, omfang til delegeret).
Godkendelse	Hver agent har sin egen Entra appId som `{agentId}` i URL'en. For blueprintafledtr id'er er det agentidentitetens appId, ikke blueprintets appId. Hvis agenten ikke er registreret i Entra, se Valg af værdier.
Godkendelse	En lejeradministrator har givet samtykke til `Agent365.Observability.OtelWrite`. Uden samtykke udstedes tokens uden rollen/omfanget, og anmodninger afvises med `403`.
Licensering	Mindst én bruger i kundelejeren har en Microsoft 365 E7- eller Microsoft Agent 365-licens tildelt (tildeling, ikke kun SKU-tilstedeværelse i lejeren). Uden en tildelt licens bliver indtagelsen afvist uovervåget. Se Forudsætninger.
Spænd	Hvert spænd sætter det kørselsdækkende essentielle (Spændhierarki og kørselsgruppering).
Spænd	`invoke_agent` spænd sætter `gen_ai.input.messages` og `gen_ai.output.messages`.
Spænd	`execute_tool` spænd sætter `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`.
Spænd	`chat` spænd sætter `gen_ai.request.model` og `gen_ai.provider.name` (og ideelt `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` – strengkodet).
Spænd	Alle ikke-rodspænd sætter `parentSpanId`. Alle spænd i et run deler det samme `traceId`.
Nyttedata	Anmodningens brødtekst er ≤ 1 MB.
Bekræftelse	Du fortolker `partialSuccess` på hvert svar og logger afvisninger.
Bekræftelse	Du kørte verificeringsflowet i Bekræftelse af indtagelse mod dine første kørsler.

Næste trin

Attributreference - Specifikation pr. attribut og vejledning til værdiudvælgelse.
Fejlfinding - Bekræftelse af indtagelse, almindelige faldgruber og fejlrespons.

Feedback

Var denne side nyttig?

Last updated on 2026-07-30