Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Ini adalah spesifikasi atribut demi atribut kanonis yang digunakan oleh alur penyerapan Agen 365. Setiap rentang yang diserap oleh Agen 365 - baik yang dipancarkan oleh Microsoft OpenTelemetry Distro, Agent 365 SDK, atau dikirim melalui direct OTel - harus sesuai dengannya. Setiap entri mencantumkan jenis operasi yang berlaku untuk atribut, apakah itu wajib, nama bidang yang dimasukkan ke dalam nilai Anda untuk kueri perburuan lanjutan (jika ada), dan dampaknya jika Anda melewatinya.
Jika Anda menggunakan SDK atau Distro, SDK memancarkan atribut ini untuk Anda dan bagian Memilih nilai hanya berlaku jika Anda perlu mengganti default. Jika Anda berada di jalur OTel langsung, Anda memancarkan setiap atribut secara manual; untuk cara merakitnya menjadi permintaan, lihat Panduan integrasi.
Attribute table
Semua nilai dikirim sebagai stringValue - jumlah token harus ( "42" bukan 42); port harus ( "443" bukan 443).
Legenda operasi.IA, = invoke_agentET, = execute_toolCH, OM = chat, = output_messagesSemua = berlaku untuk setiap operasi.
Required legend.
- M: mandatory.
- M*1: wajib hanya untuk agen yang diwujudkan (agen memiliki akun pengguna ID Agen Entra sendiri).
- M*2: wajib hanya untuk panggilan agen-ke-agen.
-
M*3: wajib hanya untuk rentang non-root. Akarnya
invoke_agenttidak memiliki induk. - O*4: opsional, hanya berarti jika status rentang adalah Kesalahan.
- O: optional.
- N/A: jangan memancarkan. Agen 365 mengisi otomatis.
Kolom "Bidang RawEventData" memberi nama kunci JSON di dalam CloudAppEvents.RawEventData kueri perburuan lanjutan kanonis dalam Memverifikasi penguraian penyerapan . Sel kosong berarti atribut not diekspos dalam CloudAppEvents hari ini--Anda masih harus memancarkannya (sesuai kolom Wajib) karena Agen 365 menggunakannya untuk penyerapan, resolusi induk, dan tampilan aktivitas agen Microsoft Defender, tetapi tidak dapat dikueri secara langsung dari perburuan lanjutan Microsoft Defender hari ini.
Note
Agen 365 secara otomatis mengisi bidang rekaman statis (Id, RecordType, , WorkloadUserType, Version) dan ID permintaan/respons yang dihasilkan.
| Attribute | Applies to | Required | RawEventData field | Catatan / dampak jika hilang |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
Salah satu dari invoke_agent, execute_tool, chat, output_messages. Rentang turun jika hilang atau tidak dikenali. |
microsoft.tenant.id |
All | M | OrganizationId |
URL {tenantId} bersifat otoritatif. Jika Anda mengatur ini dan tidak setuju, permintaan ditolak (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, juga tingkat AgentIdatas); AgentId (ET, CH) |
AppID aplikasi yang memanggil. Harus cocok dengan URL {agentId} dan aplikasi yang diautentikasi. Ketidakcocokan mengembalikan 403. |
gen_ai.agent.name |
All | M |
TargetAgentName (IA); AgentName (ET, CH) |
Defender / admin center menampilkan GUID mentah alih-alih nama jika hilang. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
AppId cetak biru. Untuk aplikasi Entra standar tanpa cetak biru, gunakan kembali appId agen. Roll-up cetak biru di pusat admin merusak sebaliknya. |
gen_ai.agent.description |
All | O | -- | Tampilan detail di pusat admin kosong untuk agen. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
Label untuk sistem identitas Anda, dipasangkan dengan microsoft.a365.agent.platform.id saat agen tidak memiliki registrasi Entra. Teks bentuk bebas; Pilih nilai yang mengidentifikasi sistem identitas Anda secara unik. Hilangkan saat agen memiliki pendaftaran Entra--Agen 365 mengklasifikasikan otomatis. Jangan gunakan nilai yang dicadangkan Microsoft (lihat Memilih nilai). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, juga tingkat AlternateIdatas); PlatformAgentId (ET, CH) |
ID unik agen di sistem identitas non-Entra Anda. Free-form text. Atur bersama dengan gen_ai.agent.type. Hilangkan saat agen memiliki registrasi Entra. Lihat Memilih nilai. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
Kunci gabungan utama untuk lari. Tanpa itu, eksekusi tidak muncul di tampilan aktivitas agen Defender atau pusat admin. |
microsoft.channel.name |
All | M |
ChannelName (IA, ET) |
Permukaan agen berlari. Gunakan token huruf kecil pendek; Nilai kanonis yang digunakan oleh filter Defender / Pusat Admin saat ini adalah msteams dan outlook. String kustom (misalnya web, <your-product-name>) diterima tetapi tidak akan berputar di filter saluran bawaan. Nilai yang sama pada setiap rentang. Lihat Memilih nilai. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
Pivot sesi kosong jika hilang. |
microsoft.session.description |
All | O | -- | Session description. |
microsoft.conversation.item.link |
All | O | -- | Tautan dalam ke pesan. |
correlation.id |
All | O | -- | Cross-service tracing. Tidak muncul dalam perburuan tingkat lanjut hari ini. |
operation.source |
All | O |
InvokeSource (IA) |
Pengidentifikasi untuk SDK / layanan yang memancarkan telemetri. Mungkin merupakan atribut Resource. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. Investigasi berbasis IP diblokir jika kosong. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
Titik akhir yang dipanggil layanan Anda. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
Dikodekan string (misalnya "443"). |
user.id |
IA | M | UserKey |
ID objek Microsoft Entra dari pemanggil manusia. "Siapa yang menjalankan agen ini" kosong tanpanya. |
user.email |
IA | O | UserId |
UPN penelepon. |
user.name |
IA | O | -- | Tampilkan nama penelepon. |
gen_ai.input.messages |
IA, CH | M | -- | Payload permintaan (string JSON). Ditangkap untuk analisis hilir tetapi belum muncul dalam perburuan lanjutan. |
gen_ai.output.messages |
IA, CH, OM | M | -- | Payload respons (string JSON). |
gen_ai.execution.type |
IA | O | -- | Salah satu dari HumanToAgent, Agent2Agent, . EventToAgent |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | Penalaran / rantai pemikiran teks bebas. |
gen_ai.author.app.id |
OM | O | -- | ID aplikasi Microsoft Entra dari aplikasi yang menulis/membuat agen. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. Tampilan penggunaan alat Defender kosong jika tidak ada. |
gen_ai.tool.type |
ET | M | ToolType |
Salah satu dari function, Power Platform Connector, , , MCP ServerAPIKnowledge Sourcebing_groundingcode_interpreterfile_search |
gen_ai.tool.call.id |
ET | M | ToolId |
Pengidentifikasi untuk panggilan alat ini. |
gen_ai.tool.call.arguments |
ET | M | -- | Argumen alat (string JSON). Ditangkap tetapi belum muncul dalam perburuan tingkat lanjut. |
gen_ai.tool.call.result |
ET | M | -- | Hasil alat (string JSON). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | Nama host server alat. Atur atribut ini untuk alat MCP. |
gen_ai.request.model |
CH | M | -- | Nama model (misalnya, gpt-4o). Ditangkap tetapi belum muncul dalam perburuan tingkat lanjut. |
gen_ai.provider.name |
CH | M | -- | Nama penyedia (misalnya, openai). |
gen_ai.usage.input_tokens |
CH | O | -- | Jumlah token input, dikodekan string. |
gen_ai.usage.output_tokens |
CH | O | -- | Jumlah token output, dikodekan string. |
gen_ai.response.finish_reasons |
CH | O | -- | Finish reason(s). |
microsoft.a365.caller.agent.id |
IA | M*2 | -- | Memanggil agen appId. Diperlukan untuk agen-ke-agen. |
microsoft.a365.caller.agent.name |
IA | M*2 | -- | Nama tampilan agen panggilan. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*2 | AgentBlueprintId |
Memanggil appId cetak biru agen. Diperlukan untuk A2A yang diwujudkan. |
microsoft.a365.caller.agent.user.id |
IA | M*2 | -- | ID pengguna agen panggilan. |
microsoft.a365.caller.agent.user.email |
IA | M*2 | -- | Menghubungi agen UPN. |
microsoft.a365.caller.agent.platform.id |
IA | N/A | -- | Dicadangkan untuk ID alternatif non-Entra. |
gen_ai.caller.agent.type |
IA | N/A | -- | Agen 365 mengklasifikasikan otomatis. |
microsoft.agent.user.id |
IA, ET, CH | M*1 |
TargetAgentUserKey (IA); UserKey (ET, CH) |
ID objek Microsoft Entra dari akun pengguna agen itu sendiri. Diperlukan untuk rekan tim AI / agen yang diwujudkan. |
microsoft.agent.user.email |
IA, ET, CH | O*1 |
UserId (ET, CH) |
UPN akun pengguna agen. |
span.SpanId |
All | M | OpId |
OTel SDK memancarkan ini. |
span.ParentSpanId |
All | M*3 | ParentId |
Diperlukan hanya untuk rentang non-root; Akarnya invoke_agent tidak ada. |
span.StartTimeUnixNano |
All | M | tingkat TimeGenerated atas (juga CreationTime di RawEventData) |
Unix epoch nanos sebagai string. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
Durasi tidak dapat dihitung jika hilang. |
span.Status.Message |
All | O*4 |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
Akar penyebab eksekusi gagal kosong jika hilang. |
span.Status.Code |
All | O*4 |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
Kategori kesalahan kosong jika hilang. |
Note
Beberapa atribut yang Anda pancarkan (seperti argumen/hasil alat, parameter model, dan tautan dalam saluran) diterima oleh Agen 365 dan digunakan oleh tampilan Microsoft Defender hilir, tetapi belum diekspos sebagai kunci JSON CloudAppEvents.RawEventData. Tetapkan per kolom Diperlukan - mereka mungkin ditambahkan ke payload berburu dalam rilis mendatang.
Memilih nilai saat Anda tidak memiliki nilai alami
Beberapa atribut yang diperlukan menjelaskan konsep yang mungkin tidak ada dalam arsitektur agen Anda. Jika nilai alami tidak ada, inilah yang harus ditetapkan. Jangan biarkan bidang wajib kosong - bahkan GUID semua nol akan menyembunyikan eksekusi Anda dari beberapa pengalaman yang dihadapi pelanggan.
| Pertanyaan / skenario | Field(s) | Apa yang harus diatur |
|---|---|---|
| Agen saya adalah pendaftaran aplikasi Entra standar (tidak dibuat dari cetak biru ID Agen Entra). | gen_ai.agent.id |
AppId aplikasi Entra. |
| ↑ skenario yang sama | microsoft.a365.agent.blueprint.id |
Gunakan kembali nilai yang sama dengan gen_ai.agent.id (appId agen). Skema membutuhkan nilai yang tidak kosong; menggunakan kembali appId agen adalah default yang aman saat tidak ada cetak biru. |
| Agen saya dibangun dari cetak biru ID Agen Entra - satu atau beberapa identitas agen yang dicetak dari cetak biru yang sama. | gen_ai.agent.id |
AppId identitas agen (instans appId, bukan cetak biru). |
| ↑ skenario yang sama | microsoft.a365.agent.blueprint.id |
AppId cetak biru. Semua instance yang dicetak dari cetak biru yang sama berbagi nilai ini. |
| Penelepon adalah pengguna manusia, bukan agen lain. | Semua microsoft.a365.caller.agent.* dan gen_ai.caller.agent.* atribut |
Omit. Mereka hanya wajib dalam skenario agen-ke-agen. |
| Dalam agen-ke-agen: agen yang memanggil adalah aplikasi Entra standar (tanpa cetak biru). | microsoft.a365.caller.agent.blueprint.id |
Gunakan kembali appId agen panggilan. |
| Agen saya bukan rekan tim AI - tidak memiliki akun penggunanya sendiri di penyewa. | Semua microsoft.agent.user.* atribut |
Omit. Mereka hanya wajib jika agen memiliki akun pengguna ID Agen Entra sendiri. |
| Agen saya tidak memiliki konsep sesi di luar satu lari. | microsoft.session.id |
Opsional - hilangkan. Jika Anda ingin setiap eksekusi menjadi sesinya sendiri, atur ke GUID per eksekusi. |
| Agen saya tidak memiliki konsep percakapan (one-shot, stateless). | gen_ai.conversation.id |
Hasilkan GUID baru per eksekusi. Bidang ini wajib; melewatkannya akan menghapus eksekusi dari tampilan aktivitas agen Defender dan pusat admin Microsoft 365. |
| Pemanggil tidak memiliki IP (misalnya, pemicu terjadwal otonom). | client.address |
Gunakan placeholder stabil yang Anda kontrol (misalnya, "0.0.0.0"). Bidang ini wajib; nilai kosong menghapus eksekusi dari pivot investigasi berbasis IP. |
| Agen berjalan dalam proses; tidak ada "server" terpisah yang dipanggil. | server.address / server.port |
Gunakan nama host komputer yang menjalankan agen (misalnya, myagent.example.com) dan port tempat titik akhir Anda mendengarkan. Diperlukan bahkan ketika tidak ada layanan hilir terpisah. |
Rentang saya chat tidak memiliki penggunaan token model. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Opsional - hilangkan. Jika Anda memiliki perkiraan hitungan, kirimkan sebagai stringValue. |
| Rentang saya tidak memiliki kesalahan untuk dilaporkan. |
span.Status.Message, span.Status.Code |
Atur status OTel ke OK (kode numerik 1) dan hilangkan pesan. Alur hanya berkonsultasi dengan bidang ini ketika status adalah Error. |
| Agen saya menggunakan sistem identitas non-Entra (agen tidak memiliki registrasi Entra). |
microsoft.a365.agent.platform.id dan gen_ai.agent.type |
Atur keduanya, pada setiap bentang.
platform.id adalah ID unik agen dalam sistem identitas Anda ; agent.type adalah label pendek yang mengidentifikasi sistem identitas mana itu. Keduanya adalah teks bentuk bebas - pilih apa pun yang masuk akal untuk sistem Anda.
Jangan gunakan nilai tipe Microsoft-cadangan: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (nilai-nilai ini dicadangkan untuk permukaan Microsoft internal). Aplikasi panggilan yang Anda autentikasi masih memerlukan pendaftaran Entra untuk menggunakan rute ini - pasangan id alternatif menggambarkan agen target , bukan penelepon. |
Nilai apa yang harus saya berikan microsoft.channel.name? |
microsoft.channel.name |
Permukaan agen berlari. Defender dan filter pusat admin keluar dari string literal, jadi gunakan token huruf kecil yang pendek, stabil, dan stabil. Saat ini nilai-nilai kanonik adalah msteams dan outlook; permukaan umum yang menghadap pelanggan juga menggunakan web, office, sharepoint, atau <your-product-name>. Pilih satu nilai dan patuhi itu - tooling tidak dapat merekonsiliasi msteams dan Microsoft Teams sebagai saluran yang sama. |
Haruskah saya mengatur gen_ai.agent.type? |
gen_ai.agent.type |
Hanya jika Anda juga mengatur microsoft.a365.agent.platform.id (misalnya, agen Anda tidak memiliki registrasi Entra). Pasangan ini memberi tahu Agen 365 dari sistem identitas mana agen itu berasal. Pilih label pendek yang mengidentifikasi sistem identitas Anda secara unik.
Jangan gunakan CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, atau Custom - nilai-nilai tersebut dicadangkan untuk penggunaan Microsoft internal. Untuk agen yang terdaftar di Entra, hilangkan bidang; Agen 365 mengisinya kembali. |
OTLP kind apa yang harus saya atur pada rentang saya? |
span.kind |
Gunakan nilai enum bilangan bulat, bukan string enum proto - (), (),1INTERNAL (), (2SERVER), (3CLIENT4). PRODUCER5CONSUMER Agen 365 menerima salah satu dari ini dan tidak memperoleh perilaku yang terlihat pelanggan dari kind, jadi 1 (INTERNAL) adalah default yang aman untuk setiap rentang. Jika Anda ingin jenis mencerminkan bentuk panggilan, INTERNAL untukinvoke_agent / output_messagesdan CLIENT untuk chat / execute_tool masuk akal. |