Integreer agentwaarneembaarheid door direct gebruik van OTel

Deze handleiding begeleidt u stap voor stap bij het direct verzenden van agenttelemetrie naar Agent 365 via OpenTelemetry (OTLP/HTTP+JSON). Lees voordat u begint Agent 365 waarneembaarheid-concepten om het model, de verificatiestromen en de oppervlakken waarop uw data terechtkomt te begrijpen.

Vereisten

Zorg ervoor dat de volgende configuraties correct zijn ingesteld voordat er telemetrie wordt doorgestuurd.

Verificatierecepten

Alle vier de recepten gebruiken het standaard Microsoft Entra-tokeneindpunt:

De onderstaande recepten tonen ruwe HTTP ter verduidelijking. In productie wordt Microsoft.Identity.Web of een andere MSAL-bibliotheek aanbevolen, die tokenvernieuwing en opslaan in cache regelt.

Welk recept heb ik nodig?

S2S, Standaard Microsoft Entra-app

Eén POST naar het token-eindpunt van de tenant met grant_type=client_credentials. Authenticeer de app met een clientgeheim, een certificaat (ondertekende JWT-assertie), een beheerde identiteit of een federatieve referentie.

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

Het teruggegeven token heeft appid/azp = {your-app-id}, roles die Agent365.Observability.OtelWrite bevat, en aud = 9b975845-.... Gebruik het op de route /observabilityService/.../traces.

Voor verificatie op basis van het certificaat vervangt u client_secret={secret} door client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, van blauwdruk afgeleide agentidentiteit

Agentidentiteiten hebben geen eigen referenties. De blauwdruk voor agentidentiteit bevat de referenties (beheerde identiteits-FIC, certificaat of clientgeheim) en tokengeneratie namens de onderliggende agentidentiteiten via een tweestapsuitwisseling. Zie voor meer informatie OAuth-stroom voor autonome apps.

1. De blauwdruk verifieert en ontvangt een federatief token voor identiteitsuitwisseling T1:

   • {blueprint-credential} is het MSI-token van de blauwdruk, een met een certificaat ondertekend JWT, of een geheime assertie van een exchange-token, per blauwdrukconfiguratie.

   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. De agentidentiteit wisselt T1 in voor het resource-token van Agent 365-waarneembaarheid:

   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
   

   • Het teruggegeven token heeft appid/azp = {agent-identity-app-id}, roles die Agent365.Observability.OtelWrite bevat en aud = 9b975845-....
   • Gebruik dit token op de route /observabilityService/.../traces.
   • De URL {agentId} is de agent identity appId, niet de blauwdruk-appId.

OBO, Standaard Microsoft Entra-app

Ontvang het inkomende token Tc van uw upstream-beller (Bearer of PFAT) en wissel het vervolgens uit:

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

Voor certificaatverificatie vervangt u client_secret={secret} door hetzelfde paar client_assertion_type + client_assertion als in S2S.

Het teruggegeven token heeft appid/azp = {your-app-id}, scp die Agent365.Observability.OtelWrite bevat en aud = 9b975845-.... Gebruik het op de route /observability/.../traces. Er wordt een vernieuwingstoken meegeleverd, sla deze op en hergebruik deze, in plaats van de uitwisseling bij elke oproep opnieuw uit te voeren.

OBO, van een blauwdruk afgeleide agentidentiteit (inclusief AI-teamgenoot)

Er zijn drie belangrijkste stappen in de on-behalf-of-stroom. Ga voor meer informatie naar OAuth-stromen van agent: on-behalf-of-stroom.

1. Ontvang het gebruikerstoken Tc. Voor een AI-teamgenoot vertegenwoordigt dit token het eigen gebruikersaccount van de agent; anders vertegenwoordigt het de menselijke gebruiker.

2. De blauwdruk voert verificatie uit en verkrijgt T1, hetzelfde als de van de S2S-blauwdruk afgeleide agentidentiteitsstroom.

3. De agentidentiteit wisselt T1 en Tc in voor een gedelegeerd resourcetoken:

   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
   

Het geretourneerde token heeft appid/azp = {agent-identity-app-id}, scp met daarin Agent365.Observability.OtelWrite en vertegenwoordigt de agent-gebruiker. Gebruik het op de route /observability/.../traces. De URL {agentId} is de agent identity appId, niet de blauwdruk-appId. Een vernieuwingstoken wordt meegeleverd. Cache het en hergebruik het.

Vereiste claims op het teruggegeven token

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

Gedelegeerde route (/observability/...) - door de gebruiker gedelegeerde token (Bearer of PFAT):

De gedelegeerde route accepteert zowel de tokens Bearer als MSAuth1.0 PFAT. Directe bellers moeten Bearer gebruiken. Als u niet weet welke u hebt, gebruik dan Bearer.

Eindpunten

Er zijn twee routes. Kies op basis van hoe uw service verifieert, niet op basis van de activiteit van de gebruiker.

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

Kopteksten:

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

URL-parameters

• {tenantId}: de GUID van de klanttenant De server beschouwt dit als gezaghebbend, als uw spans microsoft.tenant.id instelt en deze niet overeenkomen, wordt de aanvraag afgewezen.
• {agentId}: de appId van de aanroepende applicatie (ook de OAuth client_id). Voor van blauwdrukken afgeleide identiteiten is dit de appId voor agentidentiteit, niet de blauwdruk-appId. Moet gelijk zijn aan de appid / azp-claim van uw token.
• api-version=1: vereist.

Codering van aanvraagbody

De body heeft de standaard OTLP/HTTP+JSON-vorm: een ExportTraceServiceRequest met resourceSpans → scopeSpans → spans. Houd rekening met de volgende details:

• traceId (16 bytes) en spanId (8 bytes) worden verzonden als hexadecimale tekenreeksen in kleine letters.
• startTimeUnixNano / endTimeUnixNano zijn tekenreeksen die nanoseconden van het Unix-tijdvak bevatten.
• kind is de opsommingswaarde van de gehele OTLP (bijvoorbeeld 1 voor INTERNAL); status.code is de opsommingswaarde in een geheel getal (bijvoorbeeld 1 voor OK, 2 voor ERROR).
• Alle kenmerkwaarden worden verzonden als stringValue.

Responsstructuur

Een succesvolle aanroep retourneert 200 OK:

{ "partialSuccess": null }

Indien sommige spans door de per-span-filter zijn afgewezen:

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

Veldnamen worden als camelCase verzonden. Controleer altijd het volgende partialSuccess: een 200-status waarbij al uw spans zijn afgewezen is een werkelijk resultaat dat u moet melden. Limieten en voorwaarden voor verwijdering somt de stille verwijdergevallen op waarbij een 200 wordt geretourneerd met partialSuccess: null, ondanks dat er downstream geen gegevens worden doorgegeven.

De kleinst mogelijke aanvraag

De eenvoudigste end-to-end test verzendt een enkele invoke_agent-span. Deze span is het kleinste object dat terechtkomt in Microsoft Defender.

Stap 1. Haal een Bearer-token op. Voor S2S gebruikt u clientreferenties met bereik 9b975845-388f-4429-889e-eab1ef63949c/.default (zie Verificatierecepten voor het volledige recept).

Stap 2. POST een enkele 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

Stap 3. Verwacht 200 OK met deze body:

{ "partialSuccess": null }

Stap 4. Bevestig dat de gegevens daadwerkelijk zijn aangekomen. Een OK van 200 is geen bewijs van inname; Opname verifiëren loopt door de verificatiestroom. Als u in plaats daarvan een opgeslagen body-bestand wilt POSTEN, vervangt u --data @- <<EOF ... EOF door --data @./otlp-request.json.

Voorbeeld van een agentuitvoering

Een gebruiker op Microsoft Teams vraagt: 'Wat is het weer in Seattle?' Uw agent roept een GetWeather-functie aan, vraagt een LLM om het antwoord te formatteren en antwoordt. Die enkele uitvoering bestaat uit vier spans:

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

Uitvoeringsbrede kenmerken die op elke span worden ingesteld:

Span A: invoke_agent (hoofdmap)

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

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

Telemetrie verzenden

Een OTel SDK gebruiken

De meeste partners verzenden traceringen via een OTel SDK in plaats van via zelfgeschreven HTTP-verzoeken. De SDK regelt batchverwerking, opnieuw proberen en de OTLP/HTTP+JSON-codering voor u. Stel het exporter-eindpunt in en injecteer de Authorization-header.

Het exporter-eindpunt is de route-URL zelf, inclusief de query-tekenreeks:

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

(Gebruik /observability/... in plaats van /observabilityService/... voor de gedelegeerde 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}"},
)

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

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

Pakket: OpenTelemetry.Exporter.OpenTelemetryProtocol.

Handgeschreven HTTP

Als u geen OTel SDK kunt of wilt gebruiken, bouw dan zelf de OTLP/HTTP+JSON-aanvraag en POST deze. De structuur van de body wordt gedefinieerd door de OTLP/HTTP+JSON-specificatie van OpenTelemetry:

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

Elk <span> is een object met als verplichte velden traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes en (voor niet-root spans) parentSpanId. Zie Eindpunten en Codering van aanvraagbody voor de regels voor codering (met tekenreeks gecodeerde tijden, hexadecimaal traceId / spanId, geheel getal kind / status.code, alle attribuutwaarden als stringValue).

De reeks kenmerken die op elke span moet worden ingesteld, is gedefinieerd in Message-contracten. Zie Kenmerkverwijzing voor een volledige lijst met kenmerken. Zie het Voorbeeld van een agentuitvoering voor een end-to-end sample met het Bearer-token in de header en de body inline.

U kunt alle spans van een uitvoering in één POST-body verzenden (voorkeur - één verzoek, één tracering) of over meerdere POST's. De server reconstrueert de uitvoering vanaf traceId + parentSpanId + gen_ai.conversation.id, zodat elke span genoeg draagt om in beide richtingen gecorreleerd te worden.

Message-contracten

Deze sectie definieert welke spans u kunt verzenden en welke attributen bij elke span horen. Voor de volledige kenmerk-voor-kenmerk specificatie, gaat u naar de Kenmerkreferentie.

Bewerkingstypen

Elke span die u verzendt moet gen_ai.operation.name ingesteld hebben op een van deze vier waarden (niet-hoofdlettergevoelig). Elke span met een ontbrekende of niet-herkende waarde wordt stilzwijgend verwijderd en in partialSuccess.rejectedSpans geteld.

Spanhiërarchie en uitvoeringsgroepering

Agent 365 reconstrueert een uitvoering uit de standaard OTLP-spangrafiek (traceId, spanId, parentSpanId) plus de uitvoeringsbrede kenmerken uit de Kenmerkreferentie.

Zes regels:

1. Stel altijd parentSpanId in op elke niet-root span. Als dit niet gebeurt, kan deze de boomstructuur van de uitvoering niet reconstrueren.
2. Hergebruik dezelfde traceId bij iedere span in een uitvoering.
3. Stel gen_ai.conversation.id in op elke span met dezelfde waarde. Dit is de primaire joinsleutel voor "alle spans in deze uitvoering". Het wordt niet automatisch doorgegeven.
4. Stel microsoft.channel.name in op elke span met dezelfde waarde. Toolspans die het kanaal / gesprek missen, kunnen deze alleen van hun bovenliggende invoke_agent erven, alleen als de bovenliggende agent in hetzelfde OTLP-verzoek zit, dus stel ze zelf op elke span in.
5. Stel microsoft.session.id in op elke span wanneer u een logische sessie hebt.
6. Voor aanroepen van agent-naar-agent waarbij de onderliggende agent zich in een afzonderlijke aanvraag bevindt, hergebruikt u dezelfde gen_ai.conversation.id en gebruikt u de kenmerken microsoft.a365.caller.agent.* (zie Kenmerkreferentie) om de context van de bellende agent vast te leggen.

De spanstructuur met vier spans in het Voorbeeld van de agentuitvoering is de canonieke structuur.

Veelvoorkomende uitvoeringsvormen

Checklist voor onboarding

Doorloop deze checklist voordat u naar productie gaat.

Volgende stappen

• Kenmerkreferentie: specificaties per kenmerk en richtlijnen voor waardekeuze.
• Probleemoplossing: opname verifiëren, veelvoorkomende valkuilen en foutreacties.