Integrer agentobserverbarhet ved hjelp av direkte OTel

Denne veiledningen tar deg steg for steg gjennom hvordan du sender agenttelemetri til Agent 365 direkte over OpenTelemetry (OTLP/HTTP+JSON). Før du starter, må du lese konseptene for observabilitet i Agent 365 for å forstå modellen, autentiseringsflytene og systemene hvor dataene dine lander.

Viktig!

Den direkte OTel-veien er unntaket, ikke standardløsningen. Bruk denne bare hvis du allerede har en OpenTelemetry-kanal, rammeverket ditt ikke kan bruke Agent 365 SDK, eller agenten din er skrevet i et språk som SDK-en ennå ikke støtter (som Java). For alle andre er den anbefalte veien Microsoft OpenTelemetry Distro, som gir en samlet observerbarhets-SDK på tvers av Agent 365, Microsoft Foundry, Azure Monitor med mer. Den tidligere observerbarhets-SDK-en fungerer fortsatt uten endringer som bryter kompatibiliteten, men anbefales ikke lenger for nye integrasjoner. Overføringsveiledning for eksisterende SDK-brukere kommer snart.

Forutsetning

Sørg for at følgende konfigurasjoner er på plass før noen telemetri sendes.

Hvem Hva
Leieradministrator Registrer deg for Agent 365 og gi samtykke til agentappen. Se Ta i bruk Agent 365. Uten en lisensiert leietaker blir inntaket stille ignorert – forespørselen returnerer 200 OK med partialSuccess: null, men data vises aldri nedstrøms.
Leieradministrator Tildel en Microsoft 365 E7- eller Microsoft Agent 365-lisens til minst én bruker i leietakeren. SKU-en alene er ikke nok. Tildeling til en bruker starter Defender-serverdelarbeidsflyten som muliggjør inntak. Uten en tildelt lisens returnerer forespørsler 200 OK med partialSuccess: null, og data blir fjernet uten varsel.
Leieradministrator Gi samtykke på vegne av leietaker. Se Gi agenter tilgang til Microsoft 365-ressurser. Uten det utstedes tokens uten rolle eller omfang, og forespørsler får 403 som svar.
Utviklerteamet ditt Registrer appen (standard Microsoft Entra-app eller -blåkopi). Se Kom i gang med Agent 365-utvikling.
Utviklerteamet ditt Legg til Agent365.Observability.OtelWrite under API-tillatelser (approlle for S2S, omfang for delegert). For blåkopier kan du se Konfigurer arvelige tillatelser. Koordiner med Agent 365-pålastingsteamet for å aktivere tillatelsen.

Autentiseringsoppskrifter

Alle de fire autentiseringsmetodene bruker standard Microsoft Entra-tokenendepunkt:

Felt Verdi
Tokenendepunkt https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Ressurs (aud i returnert token) 9b975845-388f-4429-889e-eab1ef63949c (godtar 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

Oppskriftene nedenfor viser rå HTTP for tydelighetens skyld. I produksjon bør du foretrekke Microsoft.Identity.Web eller et annet MSAL-bibliotek, som håndterer fornyelse av token og bufring.

Hvilken oppskrift trenger jeg?

Min appmodell Min OAuth-flyt Gå til
Standard Microsoft Entra-appregistrering S2S (klientlegitimasjon) S2S, standard Microsoft Entra-app
Standard Microsoft Entra-appregistrering OBO (delegert) OBO, standard Microsoft Entra-app
Blåkopiavledet agentidentitet S2S (klientlegitimasjon) S2S, blåkopiavledet agentidentitet
Blåkopiavledet agentidentitet OBO/KI-teammedlem OBO, blåkopiavledet agentidentitet

S2S, standard Microsoft Entra-app

En POST til leietakerens tokenendepunkt med grant_type=client_credentials. Autentiser appen ved å bruke en klienthemmelighet, et sertifikat (signert JWT-deklarasjon), eller en administrert identitet eller føderert legitimasjon.

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 returnerte tokenet har appid/azp = {your-app-id}, roles som inneholder Agent365.Observability.OtelWrite og aud = 9b975845-.... Bruk det på /observabilityService/.../traces-ruten.

For sertifikatbasert autentisering erstatter du client_secret={secret} med client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, blåkopiavledet agentidentitet

Agentidentiteter har ikke egne autentiseringsopplysninger. Agentidentitetsmalen holder legitimasjon (administrert identitet (FIC), sertifikat eller klienthemmelighet) og utsteder tokens på vegne av sine underordnede agentidentiteter gjennom en totrinns utveksling. For mer informasjon kan du se autonom OAuth-appflyt.

  1. Blåkopien autentiserer seg og får et føderert identitetsutvekslingstoken T1:

    • {blueprint-credential} er enten blåkopiens MSI-token, sertifikatsignert JWT eller en exchange-token-deklarasjon, avhengig av blåkopiens konfigurasjon.
    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 byttes T1 mot Agent 365-observerbarhetsressurstokenet:

    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 returnerte tokenet har appid/azp = {agent-identity-app-id}, roles som inneholder Agent365.Observability.OtelWrite og aud = 9b975845-....
    • Bruk tokenen på /observabilityService/.../traces-ruten.
    • Nettadressen {agentId} er agentidentitetens appId, ikke blåkopiens appId.

OBO, standard Microsoft Entra-app

Motta brukerens innkommet token Tc fra oppstrøms kalleren (Bearer eller PFAT), og bytt den inn:

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

Ved sertifikatautentisering bytter du ut client_secret={secret} med det samme client_assertion_type + client_assertion-paret som i S2S.

Det returnerte tokenet har appid/azp = {your-app-id}, scp som inneholder Agent365.Observability.OtelWrite og aud = 9b975845-.... Bruk det på /observability/.../traces-ruten. En oppdateringstoken returneres ved siden av, buffer og gjenbruk det i stedet for å kjøre exchange på nytt ved hvert kall.

OBO, blåkopiavledet agentidentitet (inkludert KI-assistent)

Det er tre hovedtrinn i på-vegne-av-flyt. For mer informasjon kan du se OAuth-agentflyter: På-vegne-av-flyt.

  1. Motta brukertokenet Tc. For en KI-lagkamerat representerer dette tokenet agentens egen brukerkonto, ellers representerer den den menneskelige oppkalleren.

  2. Blåkopien autentiserer og mottar T1, på samme måte som S2S-blåkopiavledet agentidentitetsflyt.

  3. Agentidentiteten utveksler T1 og Tc mot et delegert ressurstoken:

    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 returnerte tokenet har appid/azp = , {agent-identity-app-id}, scp som inneholder Agent365.Observability.OtelWrite, og representerer agentens bruker. Bruk det på /observability/.../traces-ruten. Nettadressen {agentId} er agentidentitetens appId, ikke blåkopiens appId. En oppdateringstoken returneres ved siden av, bufre og gjenbruk den.

Påkrevde krav i det returnerte tokenet

S2S-rute (/observabilityService/...) – bare apptoken:

Krav Obligatorisk verdi
aud 9b975845-388f-4429-889e-eab1ef63949c (eller api://9b975845-...)
roles Må inneholde Agent365.Observability.OtelWrite
appid (v1) eller azp (v2) Må være lik nettadresse {agentId}
scp Må være fraværende

Delegert rute (/observability/...) – brukerdelegert token (bærer eller PFAT):

Krav Obligatorisk verdi
aud 9b975845-388f-4429-889e-eab1ef63949c (eller api://9b975845-...)
scp Må inneholde Agent365.Observability.OtelWrite
appid / azp Må være lik nettadresse {agentId}

Den delegerte ruten aksepterer både Bearer- og MSAuth1.0 PFAT-tokener. Direkte oppkallere bør bruke Bearer. Hvis du ikke vet hvilken du har, bruker du Bearer.

Endepunkter

To ruter. Velg basert på hvordan din tjeneste autentiserer, ikke basert på hva brukeren gjø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

Topptekster:

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

URL-parametere

  • {tenantId} – kundeleier-GUID. Serveren anser dette som bestemmende. Hvis strekkene setter microsoft.tenant.id og det ikke samsvarer, blir forespørselen avvist.
  • {agentId} – den kallende appens appId (også brukt som OAuth client_id). For identiteter avledet fra blåkopien er dette agentidentitetens appId, ikke blåkopiens appId. Må tilsvare kravet appid / azp på tokenet ditt.
  • api-version=1 – obligatorisk.

Be om tekstkoding

Teksten har standard OTLP/HTTP+JSON-format: en ExportTraceServiceRequest med resourceSpans → scopeSpans → spans. Husk følgende detaljer:

  • traceId (16 byte) og spanId (8 byte) sendes som heksadesimalstrenger med små bokstaver.
  • startTimeUnixNano / endTimeUnixNano er strenger som inneholder antall nanosekunder siden Unix-epoken.
  • kind er opplisting som et heltall (f.eks. 1 for INTERNAL). status.code er opplisting som et heltall (f.eks. 1 for OK, 2 for ERROR).
  • Alle attributtverdier sendes som stringValue.

Responsstruktur

Et vellykket anrop returnerer 200 OK:

{ "partialSuccess": null }

Hvis noen strekk ble avvist av per-strekk-filteret:

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

Feltnavnene er camelCase i overføringen. Sjekk alltid partialSuccess: en 200 hvor alle strekk er avvist er et reelt utfall du må håndtere. Begrens og fjern betingelser lister opp dropp-situasjonene i bakgrunnen hvor en 200 returnerer med partialSuccess: null til tross for at ingen data dukker opp nedstrøms.

Den minste forespørselen

Den enkleste ende-til-ende-testen sender ett enkelt invoke_agent-strekk. Dette spennet er det minste som havner i Microsoft Defender.

Trinn 1. Hent en bærertoken. For S2S bruker du klientlegitimasjon med omfang 9b975845-388f-4429-889e-eab1ef63949c/.default (se autentiseringsveiledning for fullstendig veiledning).

Trinn 2. POST ett enkelt strekk:

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

Trinn 3. Forvent 200 OK med denne teksten:

{ "partialSuccess": null }

Trinn 4. Bekreft at dataene faktisk er mottatt. En 200 OK er ikke bevis på inntak. Verifisering av inntak går gjennom verifiseringsflyten. For POST en lagret tekstfil i stedet erstatter du --data @- <<EOF ... EOF med --data @./otlp-request.json.

Eksempel på agentkjøring

En bruker på Microsoft Teams spør: «Hvordan er været i Seattle?». Agenten kaller en GetWeather-funksjon, ber LLM om å formatere svaret og gir svar. Den ene kjøringen er fire strekk:

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

Kjøringsomfattende attributter satt på hvert strekk:

Attributt Eksempelverdi
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

Viktig!

Disse kjøringsomfattende attributtene blir ikke fylt ut automatisk. Du må selv sette gen_ai.conversation.id, microsoft.channel.name og microsoft.session.id på hvert strekk.

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

Strekk B: chat (LLM-kall)

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

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

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

Send telemetri

Bruk av en OTel SDK

De fleste partnere sender spor gjennom en OTel SDK i stedet for håndlaget HTTP. SDK-en håndterer satsvis kjøring, nye forsøk og OTLP/HTTP+JSON-koding for deg. Sett eksportørendepunktet og injiser Authorization-hodet.

Eksportørens endepunkt er selve rutenettadressen, inkludert spørringsstrengen:

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

(Bruk /observability/... i stedet for /observabilityService/... for den delegerte ruten.)

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.

Manuell HTTP

Hvis du ikke kan eller ikke vil bruke en OTel SDK, bygg OTLP/HTTP+JSON-forespørselen selv og POST den. Tekstformen defineres av OpenTelemetry OTLP/HTTP+JSON-spesifikasjonen:

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

Hver <span> er et objekt som må inneholde følgende obligatoriske felter: traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes, og (for ikke-rotstrekk) parentSpanId. Se Endepunkter og Forespørselskroppens koding for regler om koding (tider kodet som strenger, hex traceId / spanId, heltall kind / status.code, alle attributtverdier som stringValue).

Attributtene som skal settes på hver strekk, er definert i Meldingskontrakter. Se Attributtreferanse for en fullstendig attributtliste. Se Agentkjøringseksempelet for et gjennomgående eksempel med bærertokenet i hodet og forespørselsteksten innebygd.

Du kan sende alle strekk fra en kjøring i én POST-tekst (foretrukket – én forespørsel, ett spor) eller fordelt på flere POST-er. Serveren rekonstruerer kjøringen fra traceId + parentSpanId + gen_ai.conversation.id, slik at hvert spenn bærer nok til å korreleres begge veier.

Meldingskontrakter

Denne delen beskriver hvilke strekk du kan sende og hvilke attributter som tilknyttes hver. Se attributtreferansen for komplett attributtspesifikasjon.

Operasjonstyper

Hvert strekk du sender, må ha gen_ai.operation.name satt til en av disse fire verdiene (skiller mellom store og små bokstaver). Ethvert strekk med en manglende eller ukjent verdi blir droppet uten varsel og telt i partialSuccess.rejectedSpans.

gen_ai.operation.name Betydning Vanligste fallgruve
invoke_agent En aktivering av en agent. Roten til en agentkjøring. Kjøringen må være til stede for at den skal vises i agentaktivitetsvisningene i Microsoft Defender eller i administrasjonssenteret for Microsoft 365. Uten den havner telemetrien bare i Microsoft Defender-avansert jakt (CloudAppEvents).
execute_tool Et verktøy-/funksjonskall utført av en agent. --
chat Et LLM-interferenskall. Bruk litteralen chat, IKKE inference.
output_messages En endelig utsendt utdatamelding. --

Strekkhierarki og kjøringsgruppering

Agent 365 rekonstruerer en kjøring fra standard OTLP-strekkgraf (traceId, spanId, parentSpanId) pluss kjøringsomfattende attributter fra Attributtreferanse.

Seks regler:

  1. Alltid satt parentSpanId på alle ikke-rotstrekk. Uten den kan ikke kjøringens trestruktur rekonstrueres.
  2. Bruk samme traceId på alle strekk i en kjøring.
  3. Angi gen_ai.conversation.id på hvert strekk med den samme verdien. Dette er den primære sammenføyingsnøkkelen for «alle strekk i denne kjøringen». Den fylles ikke ut automatisk.
  4. Angi microsoft.channel.name på hvert strekk med den samme verdien. Verktøystrekk som mangler kanal/samtale kan arve dem fra overordnet invoke_agentbare hvis overordnet er i samme OTLP-forespørsel, så må du sette dem på hvert strekk selv.
  5. Sett microsoft.session.id på hvert strekk når du har en logisk økt.
  6. For agent-til-agent-kall der underordnet agent er i en separat forespørsel, gjenbruk den samme gen_ai.conversation.id og bruk microsoft.a365.caller.agent.*-attributtene (se Attributtreferanse) for å fange opp kaller-agent-konteksten.

Treet med fire strekk i agentkjøringseksempelet er den kanoniske formen.

Vanlige kjøringsformer

Figur Strekk som skal sendes Merknader
Chatrobot med én agent (ingen verktøy, ingen LLM-strekk) Bare én invoke_agent Sett kjøringsomfattende attributter pluss gen_ai.input.messages og gen_ai.output.messages. Identisk med Minste mulige forespørsel.
Agent med verktøy (mest vanlig) invoke_agent-rot + underordnede chat, execute_tool, output_messages Alle underordnet deler rotens traceId og setter parentSpanId = root.spanId. Alle har de samme kjøringsomfattende attributtene. Se Agentkjøringseksempel for et komplett eksempel.
Agent-til-agent Hver agent sender sin egen invoke_agent Gjenbruk det samme gen_ai.conversation.id for begge agentene. På målets invoke_agent skal du sette gen_ai.execution.type = "Agent2Agent" og microsoft.a365.caller.agent.*-attributtene (den kallende agentens appId, navn, blåkopi appId, bruker-ID og e-post). Hvis den kallende agenten ikke har Entra-registrering, bruker du microsoft.a365.caller.agent.platform.id og gen_ai.caller.agent.type i stedet.

Pålastingssjekkliste

Gå gjennom denne sjekklisten før du går i produksjon.

Kategori Kontroll
Godkjenning Entra-appen din (eller blåkopi) er registrert, og du kan generere tokener for den.
Godkjenning Appen din har blitt tildelt Agent365.Observability.OtelWrite (approlle for S2S, omfang for delegert).
Godkjenning Hver agent har sin egen Entra appId som {agentId} i nettadressen. For blåkopiavledede identiteter er den appId-en agentidentitetens appId, ikke blåkopiens appId. Hvis agenten ikke har Entra-registrering, kan du se Plukk verdier.
Godkjenning En leieradministrator har gitt samtykke for Agent365.Observability.OtelWrite. Uten samtykke utstedes tilgangstoken uten rolle/omfang, og forespørsler avvises med 403.
Lisensiering Minst én bruker i kundeleietakeren har en Microsoft 365 E7- eller Microsoft Agent 365-lisens tildelt (tildeling, ikke bare SKU-tilstedeværelse i leietakeren). Uten tildelt lisens blir inntaket fjernet uten varsel. Se Forutsetninger.
Strekk Hvert strekk angir det kjøringsomfattende grunnleggende (Strekkhierarki og kjøringsgruppering).
Strekk invoke_agent strekk angitt gen_ai.input.messages og gen_ai.output.messages.
Strekk execute_tool strekk angitt gen_ai.tool.name, gen_ai.tool.type, gen_ai.tool.call.id, gen_ai.tool.call.arguments, gen_ai.tool.call.result.
Strekk chat strekk angitt gen_ai.request.model og gen_ai.provider.name (og ideelt gen_ai.usage.input_tokens / gen_ai.usage.output_tokens – strengkodet).
Strekk Alle ikke-rotstrekk angir parentSpanId. Alle strekk i en kjøring deler samme traceId.
Nyttelast Forespørselskroppen er ≤ 1 MB.
Verifisering Du analyserer partialSuccess på hvert svar og logger avvisninger.
Verifisering Du kjørte verifiseringsflyten i Verifisering av inntak mot de første kjøringene.

Neste trinn

  • Attributtreferanse – Spesifikasjon og veiledning for valg av verdier per attributt.
  • Feilsøking – Verifisering av inntak, vanlige fallgruver og feilsvar.
  • Last updated on