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.
Artikel ini adalah spesifikasi kanonik atribut demi atribut yang digunakan oleh pipeline ingestion Agent 365. Setiap rentang yang dimasukkan oleh Agen 365 - baik yang dipancarkan oleh Microsoft OpenTelemetry Distro, Agent 365 Observability SDK yang sudah tidak digunakan, maupun dikirim melalui OTel langsung - harus sesuai dengan itu. 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 akan mengeluarkan atribut ini untuk Anda. Bagian Memilih nilai hanya berlaku saat Anda perlu menimpa default. Jika Anda menggunakan jalur OTel langsung, Anda mengeluarkan 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 tidak terekspos di CloudAppEvents hari ini. Anda tetap harus memancarkannya (sesuai kolom Required) karena Agent 365 menggunakannya untuk ingestion, parent-resolution, dan tampilan aktivitas agen Microsoft Defender. Namun, Anda tidak bisa langsung mengincar dari Microsoft Defender advanced hunting saat ini.
Note
Agen 365 secara otomatis mengisi field rekaman statis (Id, RecordType, Workload, UserType, Version) dan ID permintaan serta 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 menetapkan nilai ini dan tidak setuju, permintaan ditolak (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA); 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 dan admin center menampilkan GUID mentah, bukan nama jika tidak ada. |
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 registrasi 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 kecil pendek. Nilai kanonik yang digunakan oleh filter Defender dan pusat admin saat ini adalah msteams dan outlook. String kustom (misalnya web, <your-product-name>) diterima tetapi tidak berpivot pada filter saluran bawaan. Gunakan nilai yang sama di setiap rentang waktu. 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 atau layanan yang memancarkan telemetri. Mungkin itu 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 atau rantai pemikiran teks bebas. |
gen_ai.author.app.id |
OM | O | -- | ID aplikasi Microsoft Entra dari aplikasi yang membuat atau 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 reasons. |
microsoft.a365.caller.agent.id |
IA | M*2 |
AgentId (IA) |
Memanggil agen appId. Diperlukan untuk agen-ke-agen. |
microsoft.a365.caller.agent.name |
IA | M*2 |
AgentName (IA) |
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 dan agen yang berwujud. |
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
Agen 365 menerima beberapa atribut yang Anda keluarkan, seperti argumen dan hasil alat, parameter model, dan tautan dalam saluran. Tampilan Microsoft Defender di hilir menggunakan atribut ini, tetapi Agent 365 belum mengeksposnya sebagai CloudAppEvents.RawEventData kunci JSON. Atur sesuai dengan kolom Wajib. Mereka mungkin akan ditambahkan ke payload berburu di rilis mendatang.
Important
Pada catatan AgentId(IA), bidang , AgentName, dan AgentBlueprintId menggambarkan invoke_agent agen yang menelepon, bukan agen yang dipanggil. Agen 365 mengisinya dari microsoft.a365.caller.agent.* atribut. Ketika seorang manusia memanggil agen Anda, hilangkan atribut tersebut, sehingga AgentIdAgentBlueprintId muncul sebagai GUID00000000-0000-0000-0000-000000000000 nol () dan AgentName kosong di catatan audit dan Microsoft Purview. Nilai nol sepenuhnya diharapkan untuk run yang diinisiasi manusia. Untuk mengidentifikasi agen yang dipanggil, gunakan TargetAgentId, TargetAgentName, dan TargetAgentBlueprintID.
Memilih nilai saat Anda tidak memiliki nilai alami
Beberapa atribut yang diperlukan menggambarkan konsep yang mungkin tidak ada dalam arsitektur agen Anda. Jika nilai alami tidak tersedia, atur nilai-nilai berikut sebagai gantinya.
Jangan biarkan kolom wajib kosong. Bahkan GUID nol sepenuhnya menyembunyikan perjalanan Anda dari beberapa pengalaman yang berhadapan langsung dengan pelanggan. Aturan ini hanya berlaku untuk atribut wajib. Ini tidak berlaku untuk atribut pemanggil-agen pada run yang diinisiasi manusia, di mana AgentId semua nol pada invoke_agent catatan diharapkan.
| 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. Pada catatan, pemanggil akan invoke_agent menampung dan AgentIdAgentBlueprintId menampilkan GUID semua-nol. Gunakan TargetAgentId untuk mengidentifikasi agen Anda. |
| 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 singkat yang mengidentifikasi sistem identitas mana yang ada. 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. |