Agen debug dengan Agent Inspector di Microsoft Foundry Toolkit

Agent Inspector di Microsoft Foundry Toolkit untuk Visual Studio Code memungkinkan Anda mengirim permintaan ke agen lokal, memeriksa aktivitas model dan alat, dan men-debug kode Anda. Gunakan untuk menyelidiki respons tak terduga sebelum Anda menyebarkan perubahan.

Alur kerja ini berguna untuk agen yang dihosting, yang menjalankan kode kustom Anda di Foundry Agent Service. Inspeksi lokal membantu Anda men-debug kode tersebut. Sebelum penggunaan produksi, uji juga agen yang disebarkan dengan identitas runtime, konfigurasi, dan akses jaringannya.

Dalam artikel ini, Anda akan terhubung ke agen lokal, menyelidiki permintaan, dan menyimpan peristiwa diagnostik. Jalur utama menggunakan protokol Responses. Tampilan yang tersedia bergantung pada protokol dan diagnostik yang disediakan server agen Anda.

Prerequisites

Visual Studio Code dengan ekstensi Foundry Toolkit publik yang saat ini tersedia. Lihat Menginstal Foundry Toolkit.
Proyek agen lokal dengan dependensi, konfigurasi model, dan kredensialnya disiapkan. Untuk memulai dari sampel, ikuti panduan mulai cepat hosted-agent melalui pengujian lokal.
Debugger yang diperlukan oleh proyek Anda. Sampel Python menggunakan ekstensi Python dan debugpy. Bahasa lain dan sampel memiliki persyaratan yang berbeda.

Untuk proyek yang ada, alat Foundry Toolkit Copilot dapat membantu menyiapkan konfigurasi. Tinjau file yang dihasilkan dan ikuti README.md proyek. Jangan ganti file peluncurannya dengan konfigurasi generik.

Important

Agen lokal dapat memanggil model cloud dan alat waktu nyata. Gunakan input pengujian yang tidak sensitif, periksa izin alat, dan perhitungkan biaya dari layanan yang dikonfigurasi. Inspector tidak mengganti alat dengan mock.

Hubungkan dan men-debug

Mulai server agen sebelum Anda terhubung ke Inspector. Gunakan konfigurasi peluncuran yang dihasilkan proyek Anda untuk menyelaraskan server, direktori kerja, interpreter, dan debugger.

Mulai agen dengan konfigurasi debug yang didokumenkan. Untuk sampel Python agen yang dihosting, pilih Debug Server HTTP Agen Lokal dan tekan F5.
Jika Inspector tidak terbuka, pilih Foundry Toolkit di Bilah Aktivitas, lalu Alat Pengembang>Build>Inspector Agen.
Periksa endpoint di header Inspector. Perancah Python saat ini menggunakan http://localhost:8088. Untuk port server yang berbeda, pilih tombol pensil di samping endpoint, masukkan port, dan pilih Sambungkan.
Pastikan bahwa tajuk memperlihatkan Tersambung. Inspector secara otomatis mendeteksi protokol Responses atau Invocations saat titik akhir dapat dijangkau.
Atur titik henti dalam kode agen Anda dan kirim pesan di Playground. Periksa variabel saat eksekusi dijeda, lalu lanjutkan dan tinjau respons.

Membuka Inspektur saja tidak meluncurkan server atau melampirkan debugger. Konfigurasi Python yang dihasilkan menggunakan port 5679 untuk debugger dan port 8088 untuk permintaan HTTP agen. Port ini terpisah dari port pelacakan OTLP.

Menyambungkan ke endpoint Responses generik

Inspector dapat terhubung ke endpoint Responses generik lokal tanpa antarmuka diagnostik pengembangan lengkap. Anda dapat memeriksa peristiwa Respons yang dikirim server, tetapi grafik alur kerja dan tampilan input dan outputnya tidak tersedia.

Koneksi yang berhasil tidak berarti bahwa server menyediakan lokasi sumber, penggunaan token, atau penalaran.

Kirim permintaan HTTP

Gunakan pemanggilan HTTP saat agen Anda menerima isi permintaan kustom daripada pesan percakapan. Format permintaan dan protokol respons milik server menentukan cara Inspector mengirim dan menampilkan hasilnya.

Hubungkan ke server invokasi HTTP yang sedang berjalan. Inspector mendeteksi protokol secara otomatis.
Masukkan body permintaan yang diperlukan oleh agen Anda. Jika server mengekspos spesifikasi OpenAPI yang kompatibel, Inspector dapat mengisi contoh. Tinjau sebelum mengirim, atau ikuti format permintaan contoh jika tidak ada contoh yang tersedia.
Pilih roda gigi Pengaturan permintaan di samping input untuk mengatur Content-Type dan Accept sesuai kebutuhan server. Misalnya, gunakan application/json untuk isi JSON dan text/event-stream saat server mendukung respons streaming.
Pilih Kirim dan periksa status dan isi respons.
Beralih antara Pratinjau untuk output yang diformat dan Mentah untuk respons dasarnya. Panel detail juga menyertakan I/O dan Panggilan LLM. Detail model, alat, dan token bergantung pada peristiwa server yang dikenali, jadi tidak setiap respons mengisi setiap tab.

Pemeriksa menangani respons HTTP normal, aliran peristiwa yang dikirim server, atau respons asinkron. Untuk respons asinkron 202 Accepted , ia melakukan polling pemanggilan hingga penyelesaian atau kegagalan. Memilih format respons tidak menambahkan streaming atau dukungan asinkron ke server Anda.

Untuk respons streaming, Hentikan akan memutus sambungan aliran klien. Untuk pemanggilan polling, Batal mengirimkan permintaan pembatalan ke server. Tidak ada tindakan yang menjamin bahwa proses agen atau operasi alat eksternal telah berhenti.

Tampilan ini bukan klien WebSocket. Sampel Protokol Aktivitas menggunakan lingkungan uji yang berbeda. Lihat Pilih protokol atau sampel lain untuk jalur pengujian lokal yang sesuai.

Menggunakan Inspektur

Mulailah dengan permintaan yang menguji perilaku yang ingin Anda pahami. Untuk alat cuaca, misalnya, minta informasi yang memerlukan alat itu, daripada jawaban umum yang dapat dihasilkan model tanpa itu.

Kirim permintaan di Playground dan tinjau respons streaming.
Gunakan tab detail untuk menemukan operasi lambat atau gagal.
Periksa peristiwa atau panggilan alat yang relevan, ubah kode atau konfigurasi Anda, dan ulangi permintaan.

Tekan Enter untuk mengirim atau Shift+Enter untuk menambahkan baris baru. Untuk memanggil kembali permintaan sebelumnya, letakkan tanda sisipan di awal input dan tekan Panah Atas. Tekan Panah Bawah di akhir untuk berpindah ke permintaan yang lebih baru dan kembali ke draf Anda yang belum terkirim.

Anda dapat mengedit permintaan yang dipanggil kembali sebelum mengirimkannya. Riwayat input adalah fitur praktis dalam Inspektur, bukan tempat penyimpanan prompt tersimpan yang permanen.

View	Gunakan untuk
Overview	Ikuti diagram waterfall latensi dan linimasa eksekusi yang berurutan. Pilih semua eksekusi atau satu eksekusi untuk membedakan model dan aktivitas alat dari selang waktu antar eksekusi.
Token	Tinjau penggunaan token input dan output yang dilaporkan. Tidak adanya data penggunaan bukan hasil token nol.
Peristiwa	Periksa peristiwa Responses yang diurai, termasuk kesalahan, panggilan fungsi, dan hasil. Cari menurut jenis peristiwa atau konten JSON dan filter menurut kategori.
Alat	Periksa panggilan alat yang dikelompokkan menurut eksekusi respons, termasuk status, ID panggilan, argumen, dan hasil.

Footer respons menunjukkan model, durasi, penggunaan token, dan informasi tanda waktu saat disediakan. Teks penalaran dan ringkasan penalaran muncul di bagian terpisah yang dapat diciutkan saat agen memancarkannya. Inspector tidak menghasilkan penalaran yang hilang atau mengekspos informasi yang tidak dikembalikan penyedia model.

Periksa alat dan izin

Gunakan Tools untuk memeriksa apakah agen memanggil tool yang diharapkan dengan argumen yang diharapkan dan menerima hasil. Respons model yang berhasil tidak membuktikan bahwa alat berjalan. Jika kode Anda menggunakan mock, hasil yang ditampilkan masih merupakan hasil mock.

Saat respons dijeda untuk persetujuan Protokol Konteks Model (MCP) atau persetujuan OAuth, permintaan yang tertunda muncul di atas input pesan. Berikan hanya akses yang ingin Anda izinkan.

Untuk panggilan alat MCP, pilih Tampilkan argumen, tinjau input, lalu pilih Setujui atau Tolak. Setujui semua dan Tolak semua berlaku untuk permintaan yang tertunda, bukan kebijakan persetujuan alat permanen.

Untuk persetujuan OAuth, selesaikan otorisasi browser dan konfirmasi Inspector:

Pilih Open consent untuk permintaan yang tertunda.
Selesaikan otorisasi di browser, kembali ke Inspektur, dan pilih Persetujuan selesai. Untuk menolak otorisasi, pilih Batalkan sebagai gantinya.
Atasi permintaan persetujuan yang tersisa. Gunakan Semua selesai, jika tersedia, hanya setelah menyelesaikan otorisasi untuk semua permintaan yang dibuka.

Membuka halaman persetujuan saja tidak melanjutkan permintaan. Inspektur menunggu keputusan pada setiap persetujuan yang tertunda sebelum memeriksa server lagi. Permintaan dapat muncul kembali jika server masih memerlukan otorisasi.

Periksa hasil alat berikutnya, tidak hanya persetujuan, untuk mengonfirmasi penyelesaian. Untuk penyiapan koneksi dan autentikasi, lihat Katalog Alat. Jangan ubah kredensial atau izin alat hanya untuk membuat kesalahan diagnostik hilang.

Memeriksa alur kerja dan kode sumber

Untuk alur kerja Microsoft Agent Framework yang didukung, server pengembangan dapat menyediakan diagnostik alur kerja dan lokasi sumber. Inspektur menggunakan informasi ini untuk menampilkan grafik eksekusi dan membantu Anda menavigasi ke kode Anda.

Pilih simpul alur kerja untuk memeriksa input dan output yang tersedia.
Klik dua kali simpul untuk membuka lokasi sumbernya.
Atur titik henti dan ulangi permintaan untuk memeriksa operasi di debugger.

Anda dapat menguji alur kerja LangGraph di playground, tetapi visualisasi alur kerja tidak didukung untuk alur kerja tersebut. Server tanpa metadata alur kerja masih dapat mengembalikan peristiwa respons yang berguna.

Menyelidiki kegagalan dengan Copilot

Gunakan tindakan kesalahan dalam Peristiwa untuk menyiapkan permintaan terfokus untuk GitHub Copilot alih-alih menyalin seluruh percakapan.

Temukan peristiwa yang gagal dan tinjau detailnya untuk konten sensitif sebelum membagikannya.
Pilih Perbaiki di samping peristiwa yang gagal untuk menyiapkan permintaan untuk kegagalan tersebut. Untuk beberapa kegagalan, persempit daftar dengan filter pencarian dan kategori, lalu pilih Selesaikan dengan Copilot. Tindakan ini mencakup kegagalan yang terlihat.
Tinjau perintah yang disiapkan di GitHub Copilot Chat sebelum mengirimkannya. Tinjau perubahan yang diusulkan, lalu jalankan ulang permintaan agen asli untuk mengonfirmasi hasilnya.

Tindakan ini tidak memerlukan pengumpul OTLP. Menyiapkan permintaan diagnostik tidak memperbaiki agen atau mencoba menjalankan kembali operasi yang gagal.

Simpan peristiwa diagnostik

Simpan snapshot event untuk membandingkan kegagalan dengan eksekusi berikutnya atau bagikan reproduksi terfokus.

Di Peristiwa, persempit daftar dengan bidang pencarian dan filter kategori.
Pilih Salin peristiwa yang terlihat untuk menyalin peristiwa yang difilter sebagai JSONL. Atau, pilih Unduh peristiwa yang terlihat untuk membuka ekspor di Visual Studio Code.
Untuk ekspor yang dibuka, gunakan Simpan File>Sebagai untuk menyimpan salinan di lokasi yang Anda kontrol sebelum menutup dokumen. Ekspor yang dibuka adalah file sementara, bukan unduhan permanen.

Cuplikan berisi peristiwa yang terlihat saat Anda memilih tindakan, bukan peristiwa mendatang dari agen yang sedang berjalan. Ini tidak menyimpan versi agen, men-deploy kode, atau membuat riwayat jejak cloud.

Perhatian

Peristiwa dapat mencakup prompt, respons, argumen alat, hasil, dan detail kesalahan. Tinjau dan samarkan konten sensitif sebelum menyimpan atau berbagi ekspor.

Mulai percakapan baru

Pilih Hapus Obrolan untuk memulai percakapan baru dan menghapus status obrolan, Peristiwa, dan Detail. Ekspor peristiwa diagnostik apa pun yang Anda butuhkan terlebih dahulu. Menyegarkan agen yang terhubung yang sama mempertahankan status inspeksinya, sementara mengubah agen menghapus status kedaluarsa.

Untuk Respons, Clear Chat dinonaktifkan saat respons aktif melakukan streaming. Ini tetap tersedia ketika tahap dijeda untuk persetujuan atau izin. Ini bukanlah perintah umum untuk menghentikan agen Anda.

Jangan mengandalkan status Inspector lokal sebagai arsip percakapan yang tahan lama. Server memiliki persistensi percakapan, yang dapat berbeda antara pengembangan lokal dan agen yang dihosting yang disebarkan. Inspector Pembersihan tidak menghapus trace yang telah dikumpulkan secara lokal atau disimpan di Application Insights.

Perbedaan Inspector dan tracing

Inspector berkomunikasi dengan server lokal Anda melalui HTTP dan mengalirkan peristiwa respons. Server pengembangan yang kompatibel juga menyediakan aliran diagnostik terpisah untuk detail alur kerja dan navigasi sumber. Debugger terhubung ke proses yang Anda jalankan secara independen.

Diagnostik langsung ini tidak memerlukan pengumpul OTLP lokal. Tab Jejak Inspektur membuka penampil pelacakan terpisah. Ini tidak mengubah peristiwa protokol menjadi span OpenTelemetry yang disimpan.

Untuk mengumpulkan span untuk analisis nanti, konfigurasikan pelacakan lokal. Untuk agen yang di-deploy, gunakan trace hosted-agent.

Setelah pengujian lokal, deploy agen yang dihosting. Uji secara terpisah karena identitasnya, lingkungan, dan akses jaringannya berbeda dari proses lokal Anda.

Troubleshooting

Issue	Apa yang harus diperiksa
Inspector tidak dapat terhubung.	Periksa terminal agen untuk kesalahan startup. Konfirmasikan interpreter, dependensi, dan port HTTP, lalu sambungkan kembali ke port yang dilaporkan server. Inspektur yang dibuka tidak memulai proses.
Permintaan berhasil tetapi breakpoint tidak terpicu.	Konfirmasikan debugger dilampirkan ke proses yang melayani permintaan dan menggunakan direktori sumber yang benar. Untuk Python, lihat pemecahan masalah debugging.
Navigasi grafik atau navigasi sumber hilang.	Konfirmasikan bahwa server dan alur kerja menyediakan diagnostik pengembangan dan lokasi sumber. inspeksi Generic Responses tidak menyediakan fitur ini. Alur kerja LangGraph berfungsi di playground tanpa visualisasi alur kerja.
Hasil alat tidak ditemukan.	Periksa Event untuk kegagalan dan persetujuan yang tertunda. Konfirmasikan bahwa permintaan memerlukan alat dan bahwa alat dikonfigurasi dan dapat dijangkau.
Token atau detail penalaran hilang.	Periksa apa yang dikeluarkan model dan server. Pemeriksa hanya dapat menampilkan informasi yang mereka sediakan.
Gambar eksternal diblokir.	Pilih Muat Gambar Jarak Jauh hanya jika Anda ingin Inspector mengambilnya dari host jarak jauh. Izin penayangan ini bukan persetujuan untuk alat. URL atau konten yang tidak didukung masih bisa gagal dimuat. Gambar yang hilang tidak selalu berarti permintaan oleh agen gagal.
Aliran respons terganggu.	Tinjau respons parsial dan detail kegagalan. Sambungkan kembali jika diperlukan dan tinjau persetujuan yang tertunda sebelum mencoba kembali. Percobaan ulang dapat mengulangi aksi alat secara langsung.
Inspector memiliki event tetapi viewer penelusuran kosong.	Peristiwa protokol dan span OTLP berbeda. Konfigurasikan instrumentasi dan mulai kolektor.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-08