Integrasikan observabilitas agen menggunakan OTel secara langsung

Panduan ini membimbing Anda langkah demi langkah untuk mengirimkan telemetri agen langsung ke Agent 365 melalui OpenTelemetry (OTLP/HTTP+JSON). Sebelum memulai, baca konsep observabilitas Agent 365 untuk memahami model, alur autentikasi, dan permukaan tempat data Anda mendarat.

Penting

Jalur OTel langsung adalah pengecualian, bukan default. Gunakan jalur ini hanya jika Anda sudah memiliki alur OpenTelemetry, kerangka kerja Anda tidak dapat menggunakan Agent 365 SDK, atau agen Anda ditulis dalam bahasa yang belum didukung oleh SDK (seperti Java). Untuk yang lainnya, jalur yang direkomendasikan adalah Microsoft OpenTelemetry Distro, yang menyediakan SDK observabilitas terpadu di seluruh Agent 365, Microsoft Foundry, Azure Monitor, dan banyak lagi. Observability SDK versi sebelumnya tetap berfungsi tanpa perubahan yang merusak, namun tidak lagi direkomendasikan untuk integrasi baru; panduan migrasi bagi pengguna SDK yang sudah ada akan segera tersedia.

Prasyarat

Pastikan konfigurasi berikut sudah diterapkan sebelum pengiriman telemetri dimulai.

Siapa	Apa
Admin penyewa	Daftar ke Agent 365 dan berikan persetujuan untuk aplikasi agen Anda. Lihat Onboard ke Agent 365. Tanpa penyewa berlisensi, penyerapan diabaikan tanpa pemberitahuan—permintaan menghasilkan `200 OK` dengan `partialSuccess: null`, tetapi data tidak pernah muncul di proses selanjutnya.
Admin penyewa	Tetapkan lisensi Microsoft 365 E7 atau Microsoft Agent 365 untuk sekurangnya satu pengguna di penyewa. Adanya SKU saja tidak cukup. Penetapan ke pengguna memulai alur kerja backend Defender yang memungkinkan penyerapan. Tanpa lisensi yang ditetapkan, permintaan akan mengembalikan `200 OK` dengan `partialSuccess: null` dan data dibuang tanpa pemberitahuan.
Admin penyewa	Berikan persetujuan penyewa. Lihat Memberikan akses agen ke sumber daya Microsoft 365. Tanpa itu, token diterbitkan tanpa peran/cakupan dan permintaan mengembalikan `403`.
Tim pengembang Anda	Daftarkan aplikasi Anda (aplikasi Microsoft Entra standar atau blueprint). Lihat Memulai pengembangan Agent 365.
Tim pengembang Anda	Tambahkan `Agent365.Observability.OtelWrite` di bawah izin API (peran aplikasi untuk S2S, cakupan untuk didelegasikan). Untuk blueprint, lihat Mengonfigurasi izin yang dapat diwariskan. Berkoordinasi dengan tim onboarding Agent 365 untuk mengaktifkan izin tersebut.

Resep autentikasi

Keempat metode menggunakan titik akhir token Microsoft Entra standar:

Bidang	Nilai
Titik Akhir Token	`https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token`
Sumber daya (`aud` dalam token yang dikembalikan)	`9b975845-388f-4429-889e-eab1ef63949c` (juga menerima `api://9b975845-388f-4429-889e-eab1ef63949c`)
Cakupan S2S	`9b975845-388f-4429-889e-eab1ef63949c/.default`
Cakupan OBO	`9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite`

Resep di bawah ini menampilkan HTTP mentah untuk kejelasan. Dalam produksi, sebaiknya menggunakan Microsoft.Identity.Web atau pustaka MSAL lainnya, yang menangani refresh dan penyimpanan token.

Resep apa yang saya butuhkan?

Model aplikasi saya	Alur OAuth saya	Buka
Pendaftaran aplikasi Microsoft Entra standar	S2S (kredensial klien)	S2S, aplikasi Microsoft Entra standar
Pendaftaran aplikasi Microsoft Entra standar	OBO (didelegasikan)	OBO, aplikasi Microsoft Entra standar
Identitas agen turunan Blueprint	S2S (kredensial klien)	S2S, identitas agen turunan Blueprint
Identitas agen turunan Blueprint	Rekan setim AI/OBO	OBO, identitas agen turunan Blueprint

S2S, aplikasi Microsoft Entra standar

Satu POST ke titik akhir token penyewa dengan grant_type=client_credentials. Autentikasi aplikasi menggunakan rahasia klien, sertifikat (pernyataan JWT yang ditandatangani), atau identitas terkelola atau kredensial gabungan.

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

Token yang dikembalikan memiliki appid/azp = {your-app-id}, roles berisi Agent365.Observability.OtelWrite, dan aud = 9b975845-.... Gunakan pada rute /observabilityService/.../traces.

Untuk autentikasi berbasis sertifikat, ganti client_secret={secret} dengan client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, identitas agen turunan Blueprint

Identitas agen tidak memiliki kredensial sendiri. Blueprint identitas agen memegang kredensial (FIC identitas terkelola, sertifikat, atau rahasia klien) dan menghasilkan token atas nama identitas agen turunannya melalui pertukaran dua langkah. Untuk informasi selengkapnya, lihat alur OAuth aplikasi otonom.

Blueprint melakukan autentikasi dan mendapatkan token pertukaran identitas federasi T1:

{blueprint-credential} adalah token MSI blueprint, JWT yang ditandatangani sertifikat, atau pernyataan token pertukaran rahasia - sesuai konfigurasi blueprint.

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

Identitas agen menukar T1 untuk token sumber daya Observabilitas Agent 365:

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

Token yang dikembalikan memiliki appid/azp = {agent-identity-app-id}, roles berisi Agent365.Observability.OtelWrite, dan aud = 9b975845-....
Gunakan token ini pada rute /observabilityService/.../traces.
URL {agentId} adalah appId identitas agen, bukan appId blueprint.

OBO, aplikasi Microsoft Entra standar

Terima token pengguna yang masuk Tc dari pemanggil upstream Anda (Bearer atau PFAT), lalu tukarkan:

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

Untuk autentikasi sertifikat, ganti client_secret={secret} dengan pasangan client_assertion_type + client_assertion yang sama seperti pada S2S.

Token yang dikembalikan memiliki appid/azp = {your-app-id}, scp berisi Agent365.Observability.OtelWrite, dan aud = 9b975845-.... Gunakan pada rute /observability/.../traces. Token refresh dikembalikan bersamaan; cache dan gunakan kembali alih-alih menjalankan kembali pertukaran pada setiap panggilan.

OBO, identitas agen yang berasal dari blueprint (termasuk rekan tim AI)

Ada tiga langkah utama untuk alur atas nama. Untuk informasi lebih lanjut, lihat Alur OAuth Agen: Alur atas nama.

Terima token pengguna Tc . Untuk rekan tim AI, token ini mewakili akun pengguna milik agen; jika tidak, token ini mewakili pemanggil manusia.
Blueprint melakukan proses autentikasi dan memperoleh T1, sama dengan alur identitas agen turunan blueprint S2S.

Identitas agen menukarkan T1 dan Tc dengan token sumber daya yang didelegasikan:

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

Token yang dikembalikan memiliki appid/azp = {agent-identity-app-id}, scp berisi Agent365.Observability.OtelWrite, dan mewakili pengguna agen. Gunakan pada rute /observability/.../traces. URL {agentId} adalah appId identitas agen, bukan appId blueprint. Refresh token akan dikembalikan bersamaan; simpan dalam cache dan gunakan kembali.

Klaim yang diperlukan pada token yang dikembalikan

Rute S2S (/observabilityService/...) - token khusus aplikasi:

Klaim	Nilai yang diperlukan
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (atau `api://9b975845-...`)
`roles`	Harus berisi `Agent365.Observability.OtelWrite`
`appid` (v1) atau `azp` (v2)	Harus sama dengan URL `{agentId}`
`scp`	Harus ada

Rute yang didelegasikan (/observability/...) - token yang didelegasikan pengguna (Bearer atau PFAT):

Klaim	Nilai yang diperlukan
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (atau `api://9b975845-...`)
`scp`	Harus berisi `Agent365.Observability.OtelWrite`
`appid` / `azp`	Harus sama dengan URL `{agentId}`

Rute yang didelegasikan menerima kedua token Bearer dan MSAuth1.0 PFAT. Pemanggil langsung harus menggunakan Bearer. Jika Anda tidak tahu mana yang Anda miliki, gunakan Bearer.

Endpoint

Dua rute; pilih sesuai dengan bagaimana layanan Anda diautentikasi, bukan berdasarkan apa yang dilakukan pengguna:

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

Header:

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

Parameter URL

{tenantId} - GUID penyewa pelanggan. Server menganggap ini sebagai otoritatif; jika nilai microsoft.tenant.id yang Anda tetapkan di span tidak sesuai, permintaan akan ditolak.
{agentId} - appId milik aplikasi pemanggil (juga OAuth client_id). Untuk identitas hasil blueprint, ini adalah appId identitas agen, bukan appId blueprint. Harus sama dengan klaim appid / azp pada token Anda.
api-version=1 - wajib.

Meminta pengodean bodi

Bodi permintaan adalah bentuk OTLP/HTTP+JSON standar: sebuah ExportTraceServiceRequest dengan resourceSpans → scopeSpans → spans. Ingatlah detail berikut:

traceId (16 byte) dan spanId (8 byte) dikirim sebagai string hex huruf kecil.
startTimeUnixNano / endTimeUnixNano adalah string yang memegang nanodetik Unix epoch.
kind adalah nilai enum OTLP bilangan bulat (misalnya 1 untuk INTERNAL); status.code adalah enum bilangan bulat (misalnya 1 untuk OK, 2 untuk ERROR).
Semua nilai atribut dikirim sebagai stringValue.

Bentuk respons

Panggilan yang berhasil menghasilkan 200 OK:

{ "partialSuccess": null }

Jika beberapa span ditolak oleh filter per span:

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

Nama bidang adalah camelCase saat dikirim. Selalu periksa partialSuccess: 200 dengan semua span Anda ditolak adalah hasil nyata yang harus Anda tampilkan. Batas dan kondisi penurunan mencantumkan kasus penurunan senyap di mana 200 kembali meskipun partialSuccess: null tidak ada data yang muncul di hilir.

Permintaan terkecil

Pengujian end-to-end paling sederhana mengirimkan satu rentang invoke_agent. Rentang ini adalah bodi terkecil yang diterima di Microsoft Defender.

Langkah 1. Dapatkan token Pembawa. Untuk S2S, gunakan kredensial klien dengan cakupan 9b975845-388f-4429-889e-eab1ef63949c/.default (lihat panduan Autentikasi untuk panduan lengkap).

Langkah 2. POST satu rentang:

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

Langkah 3. Harapkan 200 OK dengan bodi berikut:

{ "partialSuccess": null }

Langkah 4. Konfirmasikan data benar-benar telah diterima. OK 200 bukanlah bukti penyerapan; Memverifikasi penyerapan berjalan melalui alur verifikasi. Untuk melakukan POST file bodi yang telah disimpan, ganti --data @- <<EOF ... EOF dengan --data @./otlp-request.json.

Eksekusi agen misalnya

Seorang pengguna di Microsoft Teams bertanya "Bagaimana cuaca di Seattle?". Agen Anda memanggil fungsi GetWeather, meminta LLM untuk memformat jawaban, dan membalas. Satu eksekusi tersebut terdiri dari empat rentang:

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

Atribut run-wide yang ditetapkan pada setiap rentang:

Atribut	Contoh Nilai
`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`

Penting

Atribut run-wide ini tidak diteruskan secara otomatis. Anda harus menetapkan gen_ai.conversation.id, microsoft.channel.name, dan microsoft.session.id pada setiap rentang secara manual.

Rentang A: `invoke_agent` (akar)

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

Rentang B: `chat` (panggilan LLM)

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

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

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

Mengirim telemetri

Penggunaan OTel SDK

Sebagian besar mitra mengirim jejak melalui OTel SDK daripada HTTP manual. SDK mengelola batching, percobaan ulang, dan pengodean OTLP/HTTP+JSON untuk Anda. Tetapkan titik akhir eksportir dan sisipkan header Authorization.

Titik akhir eksportir adalah URL rute itu sendiri, termasuk string kueri.

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

(Gunakan /observability/... alih-alih /observabilityService/... untuk rute yang didelegasikan.)

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
    headers={"Authorization": f"Bearer {token}"},
)

Paket: opentelemetry-exporter-otlp-proto-http.

Node.js / TypeScript

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const exporter = new OTLPTraceExporter({
  url: "https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
  headers: { Authorization: `Bearer ${token}` },
});

Paket: @opentelemetry/exporter-trace-otlp-http.

.NET

using OpenTelemetry.Exporter;

services.AddOpenTelemetry().WithTracing(b => b
    .AddOtlpExporter(o =>
    {
        o.Endpoint = new Uri("https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1");
        o.Headers = $"Authorization=Bearer {token}";
        o.Protocol = OtlpExportProtocol.HttpJson;
    }));

Paket: OpenTelemetry.Exporter.OpenTelemetryProtocol.

HTTP Manual

Jika Anda tidak dapat atau tidak ingin menggunakan OTel SDK, buat sendiri permintaan OTLP/HTTP+JSON dan lakukan POST. Struktur bodi ditentukan oleh spesifikasi OTLP/HTTP+JSON OpenTelemetry:

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

Setiap <span> adalah objek yang bidang wajibnya adalah traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes, dan (untuk rentang non-root) parentSpanId. Lihat Titik Akhir dan Minta pengodean bodi untuk aturan pengodean (waktu yang dikodekan sebagai string, hex traceId / spanId, integer kind / status.code, semua nilai atribut sebagai stringValue).

Kumpulan atribut yang harus diatur pada setiap rentang ditentukan dalam Kontrak pesan. Lihat Referensi atribut untuk daftar atribut lengkap. Lihat contoh eksekusi Agen untuk sampel kerja end-to-end dengan token Pembawa di header dan bodi secara inline.

Anda dapat mengirim semua rentang dalam satu eksekusi melalui satu bodi POST (disarankan—satu permintaan, satu pelacakan) atau di beberapa POST. Server merekonstruksi eksekusi dari traceId + parentSpanId + gen_ai.conversation.id, sehingga setiap rentang membawa cukup informasi untuk dapat dikorelasikan dengan kedua cara.

Kontrak pesan

Bagian ini menjelaskan rentang apa yang dapat dikirimkan dan atribut apa yang harus disertakan pada masing-masingnya. Untuk spesifikasi lengkap atribut demi atribut, lihat Referensi atribut.

Jenis operasi

Setiap rentang yang Anda kirim harus memiliki gen_ai.operation.name yang diatur ke salah satu dari empat nilai ini (tidak peka huruf besar/kecil). Setiap rentang dengan nilai yang hilang atau tidak dikenali akan dibuang tanpa pemberitahuan dan dihitung dalam partialSuccess.rejectedSpans.

`gen_ai.operation.name`	Makna	Gotcha yang paling banyak di-google
`invoke_agent`	Pemanggilan sebuah agen. "Akar" dari eksekusi agen.	Diperlukan agar eksekusi muncul di tampilan aktivitas agen Microsoft Defender atau pusat admin Microsoft 365. Tanpanya, telemetri hanya masuk ke perburuan tingkat lanjut Microsoft Defender (`CloudAppEvents`).
`execute_tool`	Pemanggilan alat atau fungsi yang dilakukan oleh agen.	--
`chat`	Panggilan inferensi LLM.	Gunakan literal `chat`, BUKAN `inference`.
`output_messages`	Pesan keluaran akhir yang dihasilkan.	--

Hierarki rentang dan pengelompokan eksekusi

Agent 365 merekonstruksi eksekusi dari grafik rentang OTLP standar (traceId, spanId, ) parentSpanIdditambah atribut run-wide dari Referensi Atribut .

Enam aturan:

Selalu atur parentSpanId pada setiap rentang non-root. Tanpanya, struktur pohon eksekusi tidak dapat direkonstruksi.
Gunakan kembali traceId yang sama di setiap rentang dalam satu eksekusi.
Atur gen_ai.conversation.id pada setiap rentang dengan nilai yang sama. Ini adalah kunci gabungan utama untuk "semua rentang dalam eksekusi ini". Ini tidak disebarkan secara otomatis.
Atur microsoft.channel.name pada setiap rentang dengan nilai yang sama. Rentang alat yang tidak memiliki saluran/percakapan dapat mewarisinya dari induknya invoke_agenthanya jika induk berada dalam permintaan OTLP yang sama, jadi Anda harus menetapkannya secara manual pada setiap rentang.
Atur microsoft.session.id pada setiap rentang ketika Anda memiliki sesi logis.
Untuk panggilan antar-agen di mana agen turunan berada dalam permintaan terpisah, gunakan kembali gen_ai.conversation.id yang sama dan gunakan atribut microsoft.a365.caller.agent.* (lihat Referensi atribut) untuk menangkap konteks agen pemanggil.

Struktur empat rentang dalam contoh Eksekusi agen adalah bentuk kanonis.

Pola eksekusi yang umum

Bentuk	Rentang untuk memancarkan	Catatan
Chatbot agen tunggal (tanpa alat, tanpa rentang LLM)	Satu `invoke_agent` saja	Setel atribut untuk seluruh eksekusi serta `gen_ai.input.messages` dan `gen_ai.output.messages`. Identik dengan Permintaan terkecil.
Agen dengan alat (paling umum)	`invoke_agent` akar + `chat`, `execute_tool`, `output_messages` turunan	Semua anak berbagi `traceId` akar dan atur `parentSpanId = root.spanId`. Semua memiliki atribut run-wide yang sama. Lihat Contoh eksekusi agen untuk contoh lengkapnya.
Agen-ke-agen	Setiap agen menghasilkan `invoke_agent` miliknya sendiri	Gunakan ulang `gen_ai.conversation.id` yang sama pada kedua agen. Pada `invoke_agent` target, atur `gen_ai.execution.type = "Agent2Agent"` dan atribut `microsoft.a365.caller.agent.*` (memanggil `appId` agen, nama, blueprint `appId`, id pengguna, dan email). Jika agen pemanggil tidak memiliki pendaftaran Entra, gunakan `microsoft.a365.caller.agent.platform.id` dan `gen_ai.caller.agent.type` sebagai gantinya.

Daftar periksa onboarding

Jalankan daftar periksa ini sebelum masuk ke produksi.

Kategori	Periksa
Auth	Aplikasi Entra Anda (atau blueprint) telah terdaftar dan Anda dapat menghasilkan token untuk aplikasi tersebut.
Auth	Aplikasi Anda telah diberikan `Agent365.Observability.OtelWrite` (peran aplikasi untuk S2S, cakupan untuk delegasi).
Auth	Setiap agen memiliki appId Entra sendiri seperti `{agentId}` di URL. Untuk identitas yang berasal dari blueprint, appId tersebut adalah appId identitas agen, bukan appId blueprint. Jika agen tidak memiliki pendaftaran di Entra, lihat Memilih nilai.
Auth	Admin penyewa telah memberikan persetujuan untuk `Agent365.Observability.OtelWrite`. Tanpa persetujuan, token dikeluarkan tanpa peran/ruang lingkup dan permintaan ditolak dengan `403`.
Lisensi	Setidaknya satu pengguna di penyewa pelanggan memiliki lisensi Microsoft 365 E7 atau Microsoft Agent 365 yang sudah ditetapkan (penetapan, bukan hanya kehadiran SKU di penyewa). Tanpa lisensi yang ditetapkan, penyerapan data akan diabaikan. Lihat Prasyarat.
Rentang	Setiap rentang menetapkan atribut penting untuk seluruh eksekusi (hierarki rentang dan pengelompokan eksekusi).
Rentang	`invoke_agent` bentang diatur `gen_ai.input.messages` dan `gen_ai.output.messages`.
Rentang	`execute_tool` rentang diatur `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`.
Rentang	`chat` rentang diatur `gen_ai.request.model` dan `gen_ai.provider.name` (dan idealnya `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` - dikodekan string).
Rentang	Semua rentang non-root menetapkan `parentSpanId`; semua rentang dalam satu eksekusi berbagi yang sama `traceId`.
Payload	Isi permintaan harus ≤ 1 MB.
Verifikasi	Anda mengurai `partialSuccess` pada setiap respons dan mencatat penolakan.
Verifikasi	Anda menjalankan alur verifikasi di Memverifikasi penyerapan terhadap eksekusi pertama Anda.

Langkah berikutnya

Referensi atribut - Spesifikasi per-atribut dan panduan yang mengambil nilai.
Pemecahan masalah - Memverifikasi penyerapan, jebakan umum, dan respons kesalahan.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-31