Integrujte pozorovatelnost agentů pomocí přímého OTel

Tento průvodce vás provede kompletním procesem odesílání telemetrie agenta do Agent 365 přímo prostřednictvím OpenTelemetry (OTLP/HTTP+JSON). Před zahájením, přečtěte si koncepty pozorovatelnosti Agent 365, abyste pochopili model, autentizační toky a cílové oblasti, kam vaše data směřují.

Důležité

Přímá cesta OTel představuje výjimku, nikoli výchozí možnost. Použijte ji pouze v případě, že již máte OpenTelemetry pipeline, váš framework není kompatibilní se SDK Agent 365, nebo váš agent je v jazyce, který SDK zatím nepodporuje (například Java). Pro všechny ostatní je doporučenou cestou Microsoft OpenTelemetry Distro, která poskytuje jednotné SDK pozorovatelnosti napříč Agent 365, Microsoft Foundry, Azure Monitor a dalšími. Dřívější Observability SDK stále funguje bez nekompatibilních změn, ale již není doporučována pro nové integrace; migrační pokyny pro stávající uživatele SDK budou brzy k dispozici.

Předpoklady

Ujistěte se, že následující konfigurace jsou dokončeny před zahájením přenosu telemetrie.

Kdo	Co
Správce klienta	Zaregistrujte se do Agent 365 a udělte souhlas pro vaši agentní aplikaci. Viz Začlenění do Agent 365. Bez licencovaného klientu je příjem tiše zrušen – požadavek vrátí `200 OK` s `partialSuccess: null`, ale data se nikdy neobjeví v downstream systému.
Správce klienta	Přiřaďte licenci Microsoft 365 E7 nebo Microsoft Agent 365 alespoň jednomu uživateli v klientu. Přítomnost SKU nestačí. Přiřazení licence uživateli spouští backendový pracovní postup Defenderu, který umožňuje příjem dat. Bez přiřazené licence požadavky vrací `200 OK` s `partialSuccess: null` a data jsou tiše zahozena.
Správce klienta	Udělte souhlas klientovi. Viz Udělení přístupu agentům ke zdrojům Microsoft 365. Bez něj jsou tokeny vydávány bez role/rozsahu a požadavky vracejí `403`.
Váš vývojářský tým	Zaregistrujte svou aplikaci (standardní Microsoft Entra aplikaci nebo blueprint). Viz Začínáme s vývojem pro Agent 365.
Váš vývojářský tým	Přidejte `Agent365.Observability.OtelWrite` pod API oprávnění (role aplikace pro S2S, rozsah pro delegované). Pro blueprinty viz Konfigurace dědičných oprávnění. Spolupracujte s onboardingovým týmem Agent 365 za účelem povolení oprávnění.

Postupy autentizace

Všechny čtyři autentizační postupy používají standardní tokenový endpoint Microsoft Entra:

Pole	Hodnota
Koncový bod tokenu	`https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token`
Zdroj (`aud` ve vráceném tokenu)	`9b975845-388f-4429-889e-eab1ef63949c` (lze použít také `api://9b975845-388f-4429-889e-eab1ef63949c`)
Rozsah S2S	`9b975845-388f-4429-889e-eab1ef63949c/.default`
Rozsah OBO	`9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite`

Níže uvedené příklady ukazují surový HTTP pro přehlednost. V produkčním prostředí upřednostněte Microsoft.Identity.Web nebo jinou knihovnu MSAL, která zajišťuje obnovu tokenů a ukládání do mezipaměti.

Jaký recept potřebuji?

Můj model aplikace	Můj tok OAuth	Přejít na
Standardní registrace aplikace Microsoft Entra	S2S (přihlašovací údaje klienta)	S2S, standardní aplikace Microsoft Entra
Standardní registrace aplikace Microsoft Entra	OBO (delegované)	OBO, standardní aplikace Microsoft Entra
Identita agenta odvozená z Blueprintu	S2S (přihlašovací údaje klienta)	S2S, identita agenta odvozená z Blueprintu
Identita agenta odvozená z Blueprintu	OBO / AI spoluhráč	OBO, identita agenta odvozená z Blueprintu

S2S, standardní aplikace Microsoft Entra

Jeden POST na token endpoint klienta s grant_type=client_credentials. Ověřte aplikaci pomocí klientského tajemství, certifikátu (podepsané JWT assertion), spravované identity nebo federovaného přihlašovacího údaje.

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

Vrácený token má appid/azp = {your-app-id}, roles, který obsahuje Agent365.Observability.OtelWrite a aud = 9b975845-.... Použijte jej na /observabilityService/.../traces cestě.

Pro ověřování založené na certifikátech nahraďte client_secret={secret} za client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, identita agenta odvozená z Blueprintu

Agentní identity nemají vlastní přihlašovací údaje. Plán identity agenta uchovává přihlašovací údaje (spravovaná identita FIC, certifikát nebo klientský tajný klíč) a vydává tokeny jménem svých podřízených agentních identit prostřednictvím dvoukrokové výměny. Další informace najdete v části OAuth proces autonomní aplikace.

Blueprint se ověří a získá federovaný token pro výměnu identity T1:

{blueprint-credential} je MSI token blueprintu, certifikátem podepsaný JWT nebo assertion výměnného tokenu na základě tajného klíče – podle konfigurace blueprintu.

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

Identita agenta vymění T1 za token zdroje Agent 365 Observability:

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

Vrácený token má appid/azp = {agent-identity-app-id}, roles, který obsahuje Agent365.Observability.OtelWrite a aud = 9b975845-....
Použijte tento token na trase /observabilityService/.../traces.
Adresa URL {agentId} je appId identity agenta, ne appId blueprintu.

OBO, standardní aplikace Microsoft Entra

Přijměte příchozí token uživatele Tc od vašeho nadřazeného volajícího (Bearer nebo PFAT) a poté jej vyměňte:

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

Pro autentizaci pomocí certifikátu, nahraďte client_secret={secret} stejnou sadou client_assertion_type + client_assertion jako v S2S.

Vrácený token má appid/azp = {your-app-id}, scp, který obsahuje Agent365.Observability.OtelWrite a aud = 9b975845-.... Použijte jej na /observability/.../traces cestě. Obnovovací token je vrácen zároveň; uložte jej do vyrovnávací paměti a znovu použijte místo opakování výměny při každém volání.

OBO, identita agenta odvozená z Blueprintu (včetně AI kolegy)

Existují tři hlavní kroky k toku On-Behalf-Of. Pro více informací viz Toky Agent OAuth: tok On-Behalf-Of.

Přijmout uživatelský token Tc. U AI kolegy tento token představuje vlastní uživatelský účet agenta; jinak představuje lidského volajícího.
Blueprint ověří svou identitu a získá T1, stejně jako v toku identity agenta odvozeném ze S2S blueprintu.

Identita agenta vymění T1 a Tc za delegovaný token zdroje:

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

Vrácený token má appid/azp = {agent-identity-app-id}, scp, který obsahuje Agent365.Observability.OtelWrite a reprezentuje uživatele agenta. Použijte jej na /observability/.../traces cestě. Adresa URL {agentId} je appId identity agenta, ne appId blueprintu. Obnovovací token je vrácen spolu s tím; uložte jej a znovu použijte.

Požadované nároky na vrácený token

S2S trasa (/observabilityService/...) - token pouze pro aplikaci:

Deklarace identity	Požadovaná hodnota
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (nebo `api://9b975845-...`)
`roles`	Musí obsahovat `Agent365.Observability.OtelWrite`
`appid` (v1) nebo `azp` (v2)	Musí odpovídat URL `{agentId}`
`scp`	Musí být vynechán

Delegovaná trasa (/observability/...) - uživatelem delegovaný token (Bearer nebo PFAT):

Deklarace identity	Požadovaná hodnota
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (nebo `api://9b975845-...`)
`scp`	Musí obsahovat `Agent365.Observability.OtelWrite`
`appid` / `azp`	Musí odpovídat URL `{agentId}`

Delegovaná trasa přijímá tokeny typu Bearer i MSAuth1.0 PFAT. Přímí volající by měli používat Bearer. Pokud nevíte, který máte, použijte Bearer.

Koncové body

Dvě trasy; Vyberte podle toho, jak se vaše služba autentizuje, ne podle toho, co uživatel dělá:

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

Hlavičky:

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

parametry adresy URL

{tenantId} - GUID klienta zákazníka. Server to považuje za směrodatné; pokud vaše spany nastaví microsoft.tenant.id a nesouhlasí, žádost bude odmítnuta.
{agentId} - volající appId aplikace (také OAuth client_id). U identit odvozených z blueprintu je to appId agentní identity, nikoli blueprint appId Musí se rovnat hodnotě appid / azp v tokenu.
api-version=1 - povinné.

Kódování textu požadavku

Tělo má standardní strukturu OTLP/HTTP+JSON: ExportTraceServiceRequest s resourceSpans → scopeSpans → spans. Mějte na paměti následující podrobnosti:

traceId (16 bajtů) a spanId (8 bajtů) jsou odesílány jako hexadecimální řetězce malými písmeny.
startTimeUnixNano / endTimeUnixNano jsou řetězce obsahující nanosekundy epochy Unix.
kind je celočíselná hodnota výčtového typu OTLP (například 1 pro INTERNAL); status.code je celočíselná hodnota výčtového typu (například 1 pro OK, 2 pro ERROR).
Všechny hodnoty atributů jsou odeslány jako stringValue.

Struktura odezvy

Úspěšné volání vrací 200 OK:

{ "partialSuccess": null }

Pokud byly některé spany odmítnuty filtrem na jednotlivé spany:

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

Názvy polí jsou při přenosu ve formátu camelCase. Vždy kontrolujtepartialSuccess: stav 200 se všemi odmítnutými spany je skutečný výsledek, který musíte správně zpracovat. Limity a podmínky odhození uvádějí případy tichého odhození, kdy je vrácena odpověď 200 s partialSuccess: null, přestože se žádná data neobjeví dále po proudu.

Nejmenší možný požadavek

Nejjednodušší end-to-end test odešle jeden span invoke_agent. Tento span je nejmenší objekt, který se objeví v Microsoft Defenderu.

Krok 1. Získejte Bearer token. Pro S2S použijte klientské přihlašovací údaje s rozsahem 9b975845-388f-4429-889e-eab1ef63949c/.default (viz Příklady ověřování pro celý návod).

Krok 2. ODESLAT jeden 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

Krok 3. Očekávejte 200 OK s tímto textem:

{ "partialSuccess": null }

Krok 4. Potvrďte, že data skutečně přišla. 200 OK není důkazem přijetí; Ověření přijetí popisuje ověřovací postup. Chcete-li místo toho ODESLAT uložený soubor s textem, nahraďte --data @- <<EOF ... EOF hodnotou --data @./otlp-request.json

Příklad běhu agenta

Uživatel v Microsoft Teams se ptá: „Jaké je počasí v Seattlu?“ Váš agent zavolá funkci GetWeather, požádá LLM, aby naformátoval odpověď, a odpoví. Tento jeden běh obsahuje čtyři spany:

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

Běhové atributy nastavené na každém úseku:

Atribut	Ukázková hodnota
`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`

Důležité

Tyto atributy platné pro celý běh nejsou automaticky propagovány. Musíte nastavit gen_ai.conversation.id, microsoft.channel.name a microsoft.session.id na každém spanu.

Span A: `invoke_agent` (kořen)

{
  "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 volání)

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

Odesílání telemetrie

Použití OTel SDK

Většina partnerů posílá stopy prostřednictvím OTel SDK místo ručně psaného HTTP. SDK za vás zpracovává dávkování, opakovaný pokus a kódování OTLP/HTTP+JSON. Nastavte koncový bod exporteru a vložte hlavičku Authorization.

Exportní endpoint je samotná URL trasy, včetně dotazovacího řetězce:

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

(Pro delegovanou trasu použijte /observability/... místo /observabilityService/....)

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

Balíček: 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}` },
});

Balíček: @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;
    }));

Balíček: OpenTelemetry.Exporter.OpenTelemetryProtocol.

Ruční HTTP

Pokud nemůžete nebo nechcete použít OTel SDK, vytvořte si OTLP/HTTP+JSON požadavek sami a ODEŠLETE jej. Struktura textu je definována specifikací OpenTelemetry OTLP/HTTP+JSON spec:

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

Každý <span> je objekt, jehož povinnými poli jsou traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes a (u nekořenových spanů) parentSpanId. Viz Koncové body a Kódování textu požadavku pro pravidla kódování (časy kódované jako řetězce, hex traceId / spanId, celé číslo kind / status.code, všechny hodnoty atributů jako řetězce stringValue).

Sada atributů, které je třeba nastavit na každém spanu, je definována v Message contracts. Úplný seznam tabulek naleznete v referenčních informacích o atributech. Podívejte se na Příklad spuštění agenta, kde najdete kompletní funkční ukázku s tokenem Bearer v hlavičce a vloženým textem zprávy.

Všechny spany jednoho runu můžete poslat v jednom těle POST požadavku (preferováno – jeden požadavek, jeden trace) nebo v několika POST požadavcích. Server rekonstruuje běh z traceId + parentSpanId + gen_ai.conversation.id, takže každý span nese dostatek informací pro správnou korelaci bez ohledu na způsob odeslání.

Kontrakty zpráv

Tato sekce definuje, jaké spany můžete emitovat a které atributy jsou přiřazeny ke každému z nich. Pro kompletní specifikaci atributů viz Attribute reference.

Typy operace

Každý span, který odešlete, musí mít gen_ai.operation.name nastaven na jednu z těchto čtyř hodnot (nerozlišují se velká a malá písmena). Každý span s chybějící nebo neznámou hodnotou je nepozorovaně vyřazen a započítán do partialSuccess.rejectedSpans.

`gen_ai.operation.name`	Význam	Nejčastěji googlovaná záludnost
`invoke_agent`	Vyvolání agenta. "Kořen" běhu agenta.	Je nezbytné, aby se běh zobrazil v zobrazení aktivity agentů Microsoft Defender nebo v Centru pro správu Microsoft 365. Bez něj se telemetrie objeví pouze v Microsoft Defender advanced hunting (`CloudAppEvents`).
`execute_tool`	Volání nástroje nebo funkce provedené agentem.	--
`chat`	Inferenční volání LLM.	Použijte doslovně `chat`, NE `inference`.
`output_messages`	Závěrečná výstupní zpráva.	--

Hierarchie spanů a seskupování běhů

Agent 365 rekonstruuje běh ze standardního OTLP grafu rozsahu (traceId, spanId, parentSpanId) plus atributy pro celý běh z Reference atributů.

Šest pravidel:

Vždy nastavte parentSpanId na každém ne-kořenovém spanu. Bez něj nelze strukturu stromu běhu rekonstruovat.
Použijte stejné traceId na každém spanu v jednom běhu.
Nastavte gen_ai.conversation.id u každého spanu se stejnou hodnotou. Toto je primární klíč pro „všechny spany v tomto běhu“. Není propagována automaticky.
Nastavte microsoft.channel.name u každého spanu se stejnou hodnotou. Nástrojové spany bez kanálu nebo konverzace mohou tyto atributy zdědit od svého nadřazeného invoke_agentpouze v případě, že nadřazený je ve stejném OTLP požadavku, proto je nastavte na každém spanu sami.
Nastavte microsoft.session.id na každém spanu, když máte logickou relaci.
Při volání mezi agenty, kdy je podřízený agent v samostatném požadavku, použijte stejný gen_ai.conversation.id a atributy microsoft.a365.caller.agent.* (viz reference atributů ) k zachycení kontextu volajícího agenta.

Čtyřspanový strom v příkladu Agent run je kanonická struktura.

Běžné struktury spuštění

Tvar	Spany k emitování	Poznámky
Chatbot s jedním agentem (bez nástrojů, bez LLM span)	Pouze jeden `invoke_agent`	Nastavte atributy pro celý běh plus `gen_ai.input.messages` a `gen_ai.output.messages`. Shodné s nejmenším možným požadavkem.
Agent s nástroji (nejčastější)	`invoke_agent` kořen + `chat`, `execute_tool`, `output_messages` podřízení	Všichni podřízení sdílejí `traceId` kořene a nastavují `parentSpanId = root.spanId`. Všechny mají stejné atributy pro celý běh. Viz příklad spuštění agenta pro úplný příklad.
Agent–agent	Každý agent generuje svůj vlastní `invoke_agent`	Použijte stejný `gen_ai.conversation.id` u obou agentů. Na `invoke_agent` cíle nastavte `gen_ai.execution.type = "Agent2Agent"` a atributy `microsoft.a365.caller.agent.*` (volání agentův `appId`, název, blueprint `appId`, uživatelské ID a e-mail). Pokud volající agent nemá registraci Entra, použijte místo toho `microsoft.a365.caller.agent.platform.id` a `gen_ai.caller.agent.type`.

Kontrolní seznam pro zaškolení

Projděte si tento kontrolní seznam před nasazením do produkce.

Kategorie	Kontrola
Ověření	Vaše aplikace Entra (nebo blueprint) je zaregistrovaná a můžete pro ni generovat tokeny.
Ověření	Vaše aplikace má udělené `Agent365.Observability.OtelWrite` (role aplikace pro S2S, rozsah pro delegované).
Ověření	Každý agent má vlastní Entra appId, uvedený jako `{agentId}` v URL. U identit odvozených z blueprintu je tímto appId myšlena appId identity agenta, nikoli appId blueprintu. Pokud agent nemá registraci Entra, viz Výběr hodnot.
Ověření	Správce klienta udělil souhlas pro `Agent365.Observability.OtelWrite`. Bez souhlasu jsou tokeny vydávány bez role/rozsahu a požadavky jsou zamítány s `403`.
Licencování	Alespoň jeden uživatel v klientu zákazníka má přiřazenou licenci Microsoft 365 E7 nebo Microsoft Agent 365 (přiřazení, nikoli pouze přítomnost SKU v klientu). Bez přidělené licence je příjem tiše ignorován. Viz Požadavky.
Spany	Každý span nastavuje základní hodnoty celého běhu (hierarchie spanů a seskupování běhů).
Spany	`invoke_agent` spany nastavují `gen_ai.input.messages` a `gen_ai.output.messages`.
Spany	`execute_tool` spany nastavují `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`.
Spany	`chat` spany nastavují `gen_ai.request.model` a `gen_ai.provider.name` (a ideálně `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` - kódované jako řetězec).
Spany	Všechny nekořenové spany mají `parentSpanId` nastaven; všechny spany v běhu sdílejí stejné `traceId`.
Datová část	Text žádosti nesmí přesáhnout 1 MB.
Ověření	Parsujete `partialSuccess` v každé odpovědi a zaznamenáváte zamítnutí.
Ověření	Spustili jste ověřovací tok v Ověření přijetí proti prvnímu běhu.

Další kroky

Přehled atributů – Specifikace a pokyny pro výběr hodnot pro jednotlivé atributy.
Řešení problémů – ověřování příjmu dat, časté problémy a reakce na chyby.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-30