Konsep observabilitas Agent 365

Artikel ini menjelaskan model data di balik observabilitas Agent 365—apa yang dikeluarkan oleh agen telemetri, siapa yang dapat mengeluarkannya, di mana telemetri tersebut diterima, dan batas-batas yang berlaku. Konsep ini berlaku untuk setiap jalur integrasi: Microsoft OpenTelemetry Distro, Agent 365 SDK, dan OTel langsung.

Catatan

Detail tingkat wire - rute URL di Autentikasi, kode error HTTP di Batas dan kondisi drop, serta batas ukuran dan kecepatan per permintaan - berlaku secara khusus untuk jalur OTel langsung. SDK dan Distro menyederhanakan hal-hal ini untuk Anda. Bagian artikel berikutnya (glosarium, alur data, model identitas, cakupan, kondisi drop, lokasi data muncul) berlaku untuk setiap jalur.

Pilih jalur integrasi Anda

Tiga jalur mengirimkan model data span yang sama ke Agent 365. Pilih salah satu:

  • Microsoft OpenTelemetry Distro - direkomendasikan untuk integrasi baru. SDK observabilitas terpadu di seluruh Agent 365, Microsoft Foundry, Azure Monitor, dan banyak lagi.
  • Agent 365 SDK (Observability SDK) - SDK sebelumnya. Tetap kompatibel tanpa perubahan yang merusak, namun tidak lagi menjadi jalur yang direkomendasikan untuk integrasi baru; panduan migrasi untuk pengguna SDK yang sudah ada akan segera tersedia.
  • Direct OTel - jalur OTLP/HTTP mentah. Hanya gunakan ini jika Anda sudah memiliki pipeline OpenTelemetry, framework agen Anda tidak dapat menggunakan Agent 365 SDK, atau agen Anda menggunakan bahasa yang belum didukung oleh SDK (seperti Java).

Jalur mana pun yang Anda pilih, model data, model identitas, cakupan, batas, dan permukaan hilir yang dijelaskan di bawah ini semuanya berlaku.

Glosarium

  • ID aplikasi (appId): Pengidentifikasi aplikasi yang dikeluarkan saat aplikasi Microsoft Entra atau identitas agen ID Agen Microsoft Entra terdaftar.
    • Sama dengan OAuth client_id, bukan ID objek Microsoft Entra.
    • Di seluruh dokumen ini, "id agen" dan "id blueprint" keduanya berarti appId.
  • Percakapan: Utas logis interaksi agen, seperti utas obrolan Teams.
    • Diidentifikasi oleh gen_ai.conversation.id.
    • Kunci gabungan utama untuk sebuah run.
  • Saluran: Lingkungan tempat agen berjalan: msteams, outlook, web, dan seterusnya.
  • Run: Satu pesan pengguna masuk, satu balasan agen keluar. Dimodelkan sebagai pohon span OTel yang berbagi traceId.

Cara kerjanya

Untuk gambaran umum tentang Agent 365 dan ke mana data telemetri dikirimkan, lihat Ikhtisar Microsoft Agent 365.

Anda mengirim telemetri sebagai data trace OpenTelemetry.

  • Sebuah pohon span yang mendeskripsikan satu run (satu pesan pengguna masuk, satu balasan agen keluar).
  • Setiap span mendeskripsikan satu tahapan—pemanggilan agen utama, panggilan LLM, panggilan alat, atau balasan akhir.

Alur data

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

Model-model identitas

Untuk penjelasan lengkap tentang model identitas agen (pendaftaran aplikasi Microsoft Entra standar vs. blueprint identitas ID Agen Microsoft Entra, termasuk rekan tim AI), lihat Panduan Memulai Pengembangan Agent 365. Pilihan model identitas Anda menentukan alur autentikasi dan titik akhir yang Anda gunakan.

Jika agen Anda tidak memiliki pendaftaran Microsoft Entra, agen tersebut tidak dapat menggunakan rute ini secara langsung. Identifikasi agen melalui atribut ID alternatif (lihat Referensi Atribut) dan hubungi tim Agent 365 mengenai jalur masuk yang sesuai.

Autentikasi

Proses autentikasi bergantung pada apakah layanan Anda mengautentikasi dirinya sendiri atau atas nama pengguna. Cabang ini menentukan alur OAuth, klaim token yang membawa izin, dan rute URL.

  • Layanan mengautentikasi dirinya sendiri: Tanpa pengguna yang masuk - otonom, terjadwal, atau berbasis peristiwa.

    • Alur OAuth: Kredensial klien layanan-ke-layanan (S2S).
    • Klaim token: roles.
    • Rute URL: /observabilityService/....

  • Layanan mengautentikasi atas nama seorang pengguna: Untuk rekan tim AI, atau untuk akun pengguna milik agen itu sendiri.

    • Alur OAuth: On-behalf-of (OBO).
    • Klaim token: scp.
    • Rute URL: /observability/....

Aplikasi agen yang sama dapat berpartisipasi dalam kedua alur, seperti rekan tim AI yang juga menjalankan proses ringkasan otonom setiap malam. Untuk informasi selengkapnya, lihat alur OAuth aplikasi otonom dan alur On-behalf-of.

Untuk konfigurasi token lengkap untuk setiap kombinasi model dan alur identitas, lihat Panduan Autentikasi dalam Panduan Integrasi.

Identitas agen terikat ke URL

{agentId} di URL harus sama persis dengan appId milik aplikasi yang memanggil (klaim appid atau azp di token Anda). Ketidakcocokan mengembalikan 403 Forbidden. Untuk identitas yang berasal dari blueprint, {agentId} adalah appId identitas agen, bukan appId blueprint.

Selain itu, setiap span yang Anda kirim harus menetapkan gen_ai.agent.id ke appId yang sama; server memverifikasi identitas agen dalam payload terhadap agen yang diautentikasi dan menolak jika tidak cocok. Langkah ini berfungsi untuk mendeteksi tercampurnya span secara tidak sengaja dari beberapa agen ke dalam satu permintaan.

Cakupan (didelegasikan) atau peran aplikasi (aplikasi) adalah izin bernama yang ditanamkan Microsoft Entra ke dalam token akses. Untuk telemetri Agent 365, izin Agent365.Observability.OtelWrite terdapat pada sumber daya Observabilitas Agent 365 (audiens 9b975845-388f-4429-889e-eab1ef63949c).

Nama izin yang sama terdaftar sebagai kedua jenis tersebut:

  • Peran aplikasi untuk alur otonom (S2S / kredensial klien). Masuk ke dalam klaim roles. Dipilih oleh <resource>/.default.
  • Cakupan yang didelegasikan untuk alur OBO. Masuk ke dalam klaim scp. Dipilih oleh <resource>/Agent365.Observability.OtelWrite (atau <resource>/.default).

Agent 365 juga mengekspos izin sisi baca, Agent365.Observability.OtelRead, yang digunakan oleh operator yang melakukan kueri telemetri Agent 365. Sebagian besar mitra tidak membutuhkannya - dokumen ini hanya membahas penyerapan.

Menambahkan izin ke aplikasi Anda

  • Untuk pendaftaran aplikasi Microsoft Entra standar: di portal Azure, tambahkan Agent365.Observability.OtelWrite (peran aplikasi untuk S2S, cakupan untuk didelegasikan) di bagian Izin API pada pendaftaran aplikasi agen.
  • Untuk blueprint: agen yang ditanamkan dari blueprint identitas agen ID Agen Microsoft Entra mewarisi izin OAuth yang ditentukan pada blueprint sehingga admin penyewa menyediakan izin terlebih dahulu sekali. Setiap instans agen yang dibuat dari blueprint tersebut menerimanya secara otomatis. Lihat Mengonfigurasi izin yang dapat diwariskan untuk blueprint identitas agen.

Sebelum token membawa peran/cakupan, admin penyewa di penyewa pelanggan harus memberikan persetujuan. Lihat Memberikan akses agen ke sumber daya Microsoft 365.

Tanpa persetujuan, akuisisi token gagal dengan AADSTS65001 ("pengguna atau administrator belum memberikan persetujuan") atau token diterbitkan tanpa klaim roles / scp dan titik akhir penerimaan menolak permintaan dengan 403.

Persetujuan diberikan satu kali per penyewa, dan berlaku untuk setiap instans yang dibuat dari blueprint setelahnya. Persetujuan ulang hanya diperlukan ketika izin baru ditambahkan ke blueprint.

Batas dan kondisi drop

Mengetahui batasan ini di awal mencegah kejutan selama integrasi—sebagian besar diam (API menerima permintaan tetapi data tidak pernah muncul di hilir).

Batas wire-level:

  • api-version=1 diperlukan pada setiap permintaan.
  • Ukuran maksimum isi permintaan adalah 1 MB. Permintaan yang lebih besar akan mendapatkan 413 Payload Too Large.
  • Kedua rute memiliki batas laju yang terpisah. Pada 429, patuhi Retry-After (diatur ke 1 detik) dan lakukan penundaan dengan jitter.

Respons kesalahan:

  • 403 Forbidden--token tanpa peran aplikasi/cakupan yang diperlukan, atau {agentId} di URL tidak sesuai dengan appid / azp pada token Anda.
  • 413 Payload Too Large--isi permintaan melebihi 1 MB.
  • 429 Too Many Requests--batas permintaan tercapai; patuhi Retry-After: 1 dan lakukan penundaan dengan jitter.

Kondisi drop (permintaan diterima oleh HTTP tetapi data tidak muncul di hilir):

# Kondisi Perilaku
1 Span gen_ai.operation.name hilang atau tidak termasuk dalam {invoke_agent, execute_tool, chat, output_messages} Penghapusan per span. Ditampilkan di partialSuccess.rejectedSpans + errorMessage.
2 Tidak ada pengguna dalam penyewa pelanggan yang memiliki lisensi Microsoft 365 E7 atau Microsoft Agent 365 yang ditetapkan. Setidaknya satu pengguna di penyewa harus memiliki lisensi yang ditetapkan (SKU yang ada di penyewa tidak cukup - penetapan memulai alur kerja backend Defender). Pengguna berlisensi tidak harus menjadi orang yang menjalankan agen secara langsung. Seluruh permintaan diam-diam dibuang. Mengembalikan 200 { "partialSuccess": null }.

200 OK bukan bukti penyerapan. Gunakan alur verifikasi untuk memverifikasi bahwa data telah masuk.

Tempat data Anda muncul

Setelah diterima, span Anda akan muncul di tiga antarmuka yang berhadapan dengan pelanggan. Ketiganya bergantung pada span invoke_agent yang valid di akar run. Run dengan hanya span chat / execute_tool / output_messages dapat dikueri di advanced hunting Defender (tabel CloudAppEvents) tetapi tidak terlihat oleh setiap permukaan lain di bawahnya.

Microsoft Defender. Aktivitas agen (invoke_agent, execute_tool, chat) muncul dalam tampilan aktivitas agen. Administrator penyewa dan analis keamanan dapat menelusuri run, alat, dan panggilan inferensi individual. Tampilan aktivitas agen di-key off dari span invoke_agent; tanpanya, run tidak muncul di sana meskipun span turunan masih dapat dikueri melalui advanced hunting. Tampilan advanced-hunting - CloudAppEvents - menerima setiap operasi: ActionType merepresentasikan operasi (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) dan bidang per-span berada di dalam RawEventData. Nama bidang yang dapat dilihat pelanggan dipetakan langsung ke atribut span yang Anda kirim: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, dan seterusnya. Lihat Referensi Atribut untuk pemetaan lengkap.

Pusat admin Microsoft 365. Aktivitas agen juga muncul di tampilan inventaris agen dan keamanan yang digunakan oleh administrator penyewa untuk mengelola agen di penyewa mereka. Pusat admin hanya menyerap baris invoke_agent: agen tanpa telemetri invoke_agent tidak muncul di inventaris, dan run yang hanya mengeluarkan chat / execute_tool / output_messages tidak terlihat di sini. Atribut yang dibaca oleh pusat admin (id agen, nama agen, id blueprint, identitas pemanggil, id percakapan, kanal, status error) semuanya berasal dari span invoke_agent.

Microsoft Purview. Aktivitas agen juga ditampilkan kepada administrator kepatuhan di Microsoft Purview, di mana mereka dapat mengatur aturan penanganan data dan kebijakan atas run agen (pencegahan kehilangan data, retensi, kepatuhan komunikasi, dan lain sebagainya). Atribut yang di-key off oleh kebijakan Purview (id agen/id blueprint, identitas pemanggil, percakapan/saluran, pesan permintaan dan respons) semuanya berasal dari span invoke_agent dan keturunannya.

Langkah berikutnya

  • Last updated on