Uji agen menggunakan Microsoft Agent 365 SDK

Sebelum penerapan, uji agen Anda secara lokal dengan menggunakan Agents Playground. Panduan ini mencakup penyiapan lingkungan pengembang, konfigurasi autentikasi, dan validasi fungsionalitas agen Anda melalui alat pengujian Agents Playground.

Setelah agen Anda berfungsi secara lokal, ikuti Siklus Pengembangan Agent 365 untuk menguji di aplikasi Microsoft 365 seperti Teams, Word, dan Outlook.

Prasyarat

Sebelum Anda mulai menguji agen Anda, pastikan Anda telah menginstal prasyarat berikut:

Prasyarat umum

Prasyarat khusus berdasarkan bahasa

  • Python 3.11 ke atas: Unduh dari python.org atau Microsoft Store
  • uv package manager: Instal uv dengan menggunakan pip install uv
  • Verifikasi penginstalan: python --version

Mengonfigurasi lingkungan pengujian agen

Bagian ini menjelaskan cara mengatur variabel lingkungan, mengotentikasi lingkungan pengembangan Anda, dan mempersiapkan agen berbasis Agent 365 untuk pengujian.

Siapkan lingkungan pengujian agen Anda dengan mengikuti langkah-langkah berurutan ini:

  1. Konfigurasikan lingkungan Anda - Buat atau perbarui file konfigurasi lingkungan Anda.

  2. Konfigurasi LLM - Dapatkan kunci API dan konfigurasikan pengaturan OpenAI atau Azure OpenAI.

  3. Konfigurasikan autentikasi - Lakukan pengaturan autentikasi agentic.

  4. Referensi variabel lingkungan - Mengonfigurasi variabel lingkungan yang diperlukan:

    1. Variabel autentikasi
    2. Konfigurasi titik akhir MCP
    3. Variabel observabilitas
    4. Konfigurasi server aplikasi agen

Setelah menyelesaikan langkah-langkah ini, Anda sudah siap memulai pengujian agen di Agents Playground.

Langkah 1: Konfigurasikan lingkungan Anda:

Siapkan file konfigurasi Anda:

cp .env.template .env

Catatan

Untuk templat konfigurasi yang menunjukkan bidang yang diperlukan, lihat sampel Microsoft Agent 365 SDK.

Langkah 2: Konfigurasi LLM

Konfigurasikan pengaturan OpenAI atau Azure OpenAI untuk pengujian lokal. Sertakan kunci API dan endpoint layanan dari prasyarat ke file konfigurasi Anda, serta parameter model yang diperlukan.

Menambahkan file .env Anda:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Variabel lingkungan Python LLM

Variabel Deskripsi Wajib Contoh
OPENAI_API_KEY Kunci API untuk layanan OpenAI Untuk OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Kunci API untuk Azure OpenAI Service Untuk Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL titik akhir Azure OpenAI Service Untuk Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nama penyebaran di Azure OpenAI Untuk Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Versi API untuk Azure OpenAI Untuk Azure OpenAI 2024-02-15-preview

Langkah 3: Konfigurasikan autentikasi untuk agen Anda

Pilih salah satu metode autentikasi berikut untuk agen Anda:

  • Autentikasi Agentic- Gunakan untuk skenario produksi saat identitas pengguna Agentic tersedia.
  • (Atas Nama) Autentikasi OBO - Gunakan untuk skenario produksi saat Anda memerlukan izin pengguna yang didelegasikan tanpa identitas pengguna agen.
  • Autentikasi token bearer - Gunakan hanya untuk skenario pengembangan dan pengujian awal sebelum otentikasi produksi dikonfigurasi.

Autentikasi agenik

Buka a365.generated.config.json di direktori kerja Anda untuk mengambil kredensial blueprint agen Anda. Salin nilai berikut:

Nilai Deskripsi
agentBlueprintId ID klien agen Anda
agentBlueprintClientSecret Rahasia klien agen Anda
tenantId ID penyewa Microsoft Entra ID Anda

Gunakan nilai-nilai ini untuk mengonfigurasi autentikasi agentic pada agen Anda:

Tambahkan pengaturan berikut ke file .env Anda, menggantikan nilai placeholder dengan kredensial aktual Anda:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variabel Deskripsi Wajib Contoh
USE_AGENTIC_AUTH Aktifkan mode autentikasi agentic Ya true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID klien cetak biru agen dari a365.generated.config.json Ya 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET ID rahasia klien cetak biru agen dari a365.generated.config.json Ya abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID ID Penyewa Microsoft Entra dari a365.generated.config.json Ya 22223333-cccc-4444-dddd-5555eeee6666

Autentikasi OBO

Dengan menggunakan autentikasi On-Behalf-Of (OBO), agen Anda dapat mengakses tools server MCP dengan menggunakan izin pengguna yang didelegasikan tanpa memerlukan identitas pengguna agen. Dalam alur ini, agen menerima token delegasi dari pengguna dan menukarnya untuk melakukan tindakan atas nama pengguna.

Autentikasi OBO cocok untuk skenario produksi di mana:

  • Agen Anda tidak memiliki identitas pengguna agen.
  • Anda perlu mengakses sumber daya dengan izin yang spesifik untuk pengguna.
  • Anda ingin agen bertindak atas nama pengguna yang diautentikasi.

Untuk rincian mengenai cara kerja alur OBO, lihat Alur autentikasi. Untuk contoh implementasi lengkap, lihat sampel otorisasi OBO di Agen SDK Microsoft 365 .

Autentikasi token pembawa

Untuk skenario pengembangan dan pengujian awal saat autentikasi produksi tidak dikonfigurasi, gunakan autentikasi token pembawa untuk menguji agen Anda. Metode ini menggunakan autentikasi browser interaktif untuk mendapatkan token akses yang didelegasikan. Dengan token ini, agen Anda dapat memanggil alat Server MCP dengan izin pengguna Anda. Pendekatan ini mensimulasikan bagaimana pengguna agen mengakses sumber daya di lingkungan produksi tanpa memerlukan instans agen yang sebenarnya.

Pertama, gunakan a365 develop add-permissions untuk menambahkan izin server MCP yang diperlukan ke aplikasi Anda:

a365 develop add-permissions

Kemudian, gunakan a365 develop get-token untuk mengambil dan mengonfigurasi token pembawa:

a365 develop get-token

Perintah get-token secara otomatis:

  • Membaca ToolingManifest.json untuk menemukan semua server MCP yang telah dikonfigurasi.
  • Mengambil satu token untuk setiap audiens – server MCP per-server menerima token dengan lingkup khusus ke ID aplikasi mereka masing-masing; server ATG bersama menerima token dengan lingkup khusus ke ID aplikasi Agent Tools Gateway bersama (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • Menulis token ke file konfigurasi proyek Anda:
    • Token per server: BEARER_TOKEN_<SERVER_NAME> (misalnya, BEARER_TOKEN_MCP_MAILTOOLS)
    • Token ATG bersama: BEARER_TOKEN

Sebelum menjalankan get-token, tambahkan entri placeholder pada file konfigurasi proyek Anda:

  • .NET: Tambahkan "BEARER_TOKEN": "" dan/atau "BEARER_TOKEN_<SERVER_NAME>": "" ke environmentVariables di setiap profil di Properties/launchSettings.json. Perintah ini hanya memperbarui profil yang sudah memiliki kunci ini yang ditentukan.
  • Python/Node.js: Buat file .env yang berisi BEARER_TOKEN= dan/atau BEARER_TOKEN_<SERVER_NAME>= sebelum menjalankan perintah. Jika file tidak ada, perintah tidak menyimpan dan menampilkan petunjuk.

Catatan

Jika Anda menjalankan a365 develop get-token --app-id <id> tanpa file a365.config.json, token-token tidak akan disimpan secara otomatis. Salin dan tempel secara manual ke Properties/launchSettings.json (untuk .NET) atau ke file .env (untuk Python/Node.js).

Token bearer kedaluwarsa setelah sekitar satu jam. Gunakan a365 develop get-token untuk memperbarui token yang sudah kedaluwarsa.

Langkah 4: Referensi variabel lingkungan

Selesaikan penyiapan lingkungan Anda dengan mengonfigurasi variabel lingkungan yang diperlukan berikut:

Variabel Otentikasi

Konfigurasikan pengaturan handler autentikasi yang diperlukan agar autentikasi agentic berfungsi dengan baik.

Menambahkan file .env Anda:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Variabel Deskripsi Wajib
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Tipe handler autentikasi Ya
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Cakupan autentikasi untuk Microsoft Graph Ya
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nama koneksi blueprint alternatif Ya
CONNECTIONSMAP_0_SERVICEURL Pola URL layanan untuk pemetaan koneksi Ya
CONNECTIONSMAP_0_CONNECTION Nama koneksi untuk pemetaan Ya

Variabel token pembawa (khusus pengembangan lokal)

Variabel Deskripsi Wajib
BEARER_TOKEN Token bearer bersama untuk server MCP ATG bersama. Perintah a365 develop get-token secara otomatis menulis token ini. Untuk pengembang lokal ATG bersama
BEARER_TOKEN_<SERVER_NAME> Token pembawa per server. SDK mengkapitalisasi mcpServerName dari ToolingManifest.json untuk menghasilkan nama (misalnya, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). Perintah a365 develop get-token secara otomatis menulis token ini. Untuk pengembangan lokal per server
SKIP_TOOLING_ON_ERRORS Atur ke true untuk menggunakan LLM dasar jika perangkat MCP gagal dimuat. Hanya berlaku ketika ASPNETCORE_ENVIRONMENT atau ENVIRONMENT adalah Development. Tidak

Penting

Bearer token hanya untuk pengembangan lokal. Jangan pernah mengkonfigurasikan BEARER_TOKEN atau BEARER_TOKEN_<SERVER_NAME> dalam penyebaran produksi.

Konfigurasi titik akhir MCP

Tentukan titik akhir platform Agent 365 yang harus digunakan oleh agen Anda. Saat Anda membuat manifest tooling yang menentukan server tooling untuk agen Anda, tentukan titik akhir platform MCP. Titik akhir ini menentukan lingkungan (preprod, pengujian, atau produksi) tempat server alat MCP terhubung untuk kemampuan integrasi Microsoft 365.

Menambahkan file .env Anda:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variabel Deskripsi Wajib Default Contoh
MCP_PLATFORM_ENDPOINT URL endpoint platform MCP (preprod, test, atau prod) Tidak Titik akhir produksi

Penting: Jika Anda tidak menentukan MCP_PLATFORM_ENDPOINT, aplikasi akan menggunakan endpoint produksi.

Catatan

Jika Anda menggunakan server mock tooling dari CLI, atur endpoint ke http://localhost:<port> dengan nomor port yang Anda gunakan. Port default adalah 5309.

Variabel observabilitas

Konfigurasikan variabel yang diperlukan ini untuk mengaktifkan pencatatan dan pelacakan terdistribusi untuk agen Anda. Untuk daftar lengkap variabel lingkungan, opsi konfigurasi, dan contoh kode, lihat Observabilitas Agen.

Catatan

Konfigurasi observabilitas sama di semua bahasa pemrograman. Lihat Konfigurasi untuk detail.

Variabel Deskripsi Default Contoh
ENABLE_A365_OBSERVABILITY_EXPORTER Ekspor jejak ke layanan observabilitas. Saat false, ekspor berlangsung ke konsol sebagai gantinya. false true
A365_OBSERVABILITY_LOG_LEVEL Tingkat log internal untuk SDK observabilitas. Berguna untuk menelusuri masalah ekspor selama pengujian. none info, warn, error, debug

Konfigurasi server aplikasi agen

Konfigurasikan port tempat server aplikasi agen Anda berjalan. Konfigurasi ini bersifat opsional dan diterapkan pada agen Python dan JavaScript.

Menambahkan file .env Anda:

# Server Configuration
PORT=3978
Variabel Deskripsi Wajib Default Contoh
PORT Nomor port yang digunakan oleh server agen Tidak 3978 3978

Menginstal dependensi dan memulai server aplikasi agen

Setelah mengonfigurasi lingkungan Anda, instal dependensi yang diperlukan dan mulai server aplikasi agen Anda secara lokal untuk pengujian.

Menginstal dependensi

uv pip install -e .

Perintah ini membaca dependensi paket yang didefinisikan di pyproject.toml dan menginstalnya dari PyPI. Saat membuat aplikasi agen dari awal, Buat file pyproject.toml untuk mendefinisikan dependensi Anda. Agen contoh dari repositori sampel sudah memiliki paket ini yang telah didefinisikan. Anda dapat menambahkan atau memperbaruinya sesuai kebutuhan.

Jalankan server aplikasi agen

python <main.py>

Gantikan <main.py> dengan nama file Python utama yang berfungsi sebagai titik masuk aplikasi agen Anda (misalnya, start_with_generic_host.py, app.py, atau main.py).

Atau gunakan uv:

uv run python <main.py>

Server agen Anda kini telah berjalan dan siap menerima permintaan dari Agents Playground maupun aplikasi Microsoft 365.

Uji agen di Agents Playground

Agents Playground merupakan alat pengujian lokal yang mensimulasikan lingkungan Microsoft 365 tanpa memerlukan penyiapan tenant secara penuh. Ini adalah cara tercepat untuk memvalidasi logika agen dan penggunaan alat oleh agen Anda. Untuk informasi selengkapnya, lihat Uji dengan Agents Playground.

Konfigurasikan Agents Playground untuk agentic authentication

Catatan

Konfigurasi ini hanya diperlukan saat menggunakan agentic authentication. Jika Anda menggunakan autentikasi bearer token, Anda dapat melewati bagian ini dan langsung ke Pengujian Dasar.

Saat Anda menggunakan autentikasi agentic, konfigurasikan file YAML Agents Playground dengan detail agen Anda:

  1. Siapkan file konfigurasi: Buat atau perbarui file .m365agentsplayground.yml di folder tempat Anda menjalankan Agents Playground. Untuk instruksi penyiapan terperinci, lihat Kustomisasi konteks Teams.

  2. Perbarui konfigurasi bot: Tambahkan detail bot berikut ke file .m365agentsplayground.yml Anda, menggantikan nilai placeholder dengan kredensial agen Anda yang sebenarnya:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Properti Deskripsi Wajib
    id Alamat email pengguna agen Anda dalam format: agentusername@tenant.onmicrosoft.com Ya
    name Nama tampilan untuk pengguna agen Anda Ya
    role Harus diatur ke agenticUser untuk autentikasi agentic Ya
    agenticUserId ID Objek pengguna agen. Temukan nilai ini di pusat admin Microsoft Entra di halaman profil pengguna agen. Ya
    agenticAppId ID Agen untuk pengguna agen. Temukan nilai ini di pusat admin Microsoft Entra di halaman profil pengguna agen. Ya

Buka terminal baru (PowerShell di Windows) dan mulai Agents Playground:

agentsplayground

Perintah ini membuka browser web dengan antarmuka Agents Playground. Alat ini menampilkan antarmuka obrolan di mana Anda dapat mengirim pesan ke agen Anda.

Tes dasar

Mulailah dengan memastikan bahwa agen Anda sudah dikonfigurasi dengan benar. Kirim pesan ke agen:

What can you do?

Agen membalas dengan instruksi yang telah dikonfigurasikan untuknya, berdasarkan perintah sistem dan kemampuan agen Anda. Balasan ini mengonfirmasi bahwa:

  • Agen Anda berjalan dengan benar.
  • Agen dapat memproses pesan dan merespons.
  • Komunikasi antara Agents Playground dan agen Anda sedang berjalan.

Pengujian pemanggilan alat

Setelah mengonfigurasi server alat MCP Anda di toolingManifest.json (lihat Tooling untuk petunjuk penyiapan), uji pemanggilan alat dengan menggunakan contoh-contoh berikut:

Pertama, verifikasi alat mana yang tersedia:

List all tools I have access to

Kemudian, uji pemanggilan alat tertentu:

Alat email

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Respons yang diharapkan: Agen mengirim email dengan menggunakan server Mail MCP dan mengonfirmasi bahwa pesan telah dikirim.

Alat kalender

List my calendar events for today

Respons yang diharapkan: Agen mengambil dan menampilkan acara kalender Anda untuk hari ini.

Alat SharePoint

List all SharePoint sites I have access to

Respons yang diharapkan: Agen melakukan kueri ke SharePoint dan mengembalikan daftar situs yang dapat Anda akses.

Anda dapat melihat pemanggilan alat di:

  • Jendela obrolan - lihat respons agen dan panggilan alat apa pun.
  • Panel Log - lihat informasi aktivitas terperinci termasuk parameter dan respons alat.

Uji dengan aktivitas notifikasi

Selama pengembangan lokal, uji skenario pemberitahuan dengan menggunakan pemicu pemberitahuan bawaan di Agents Playground.

Cuplikan layar yang menunjukkan antarmuka Agents Playground dengan menu Mock an Activity diperluas, menampilkan opsi pemicu aktivitas pemberitahuan termasuk Kirim email dan Sebutkan di Word.

Sebelum menguji aktivitas notifikasi, pastikan Anda:

Uji pemberitahuan email

Untuk menguji penanganan notifikasi email:

  1. Mulai agen Anda dan Agents Playground.
  2. Di Agents Playground, buka Mock an Activity>Activity Trigger Notification.
  3. Pilih Kirim email.
  4. Dalam dialog payload, perbarui detail email tiruan seperti nama pengirim dan konten isi email sesuai kebutuhan.
  5. Pilih Kirim aktivitas.
  6. Lihat hasilnya di percakapan obrolan dan panel log.

Agen menerima notifikasi email simulasi dan memprosesnya sesuai dengan logika penanganan notifikasi Anda. Untuk detail tentang struktur payload pemberitahuan email, lihat Payload pemberitahuan email.

Uji notifikasi penyebutan di Word

Untuk menguji pemberitahuan penyebutan pada dokumen Word:

  1. Mulai agen Anda dan Agents Playground.
  2. Di Agents Playground, buka Mock an Activity>Activity Trigger Notification.
  3. Pilih Mention in Word.
  4. Dalam dialog payload, perbarui detail komentar tiruan seperti ID dokumen dan teks komentar sesuai kebutuhan.
  5. Pilih Kirim aktivitas.
  6. Lihat hasilnya di percakapan obrolan dan panel log.

Agen menerima notifikasi mention Word yang disimulasikan dan merespons sesuai dengan logika penanganan notifikasi Anda. Untuk detail tentang struktur payload notifikasi komentar Word, lihat Payload notifikasi komentar dokumen.

Uji peristiwa instalasi dan penghapusan instalasi agen

Saat Agents Playground terhubung ke agen Anda, secara otomatis akan mengirimkan aktivitas InstallationUpdate dengan tindakan add. Jika Anda mengimplementasikan pengelola instalasi, pesan sambutan agen Anda akan muncul di chat segera setelah koneksi terjalin.

Untuk memverifikasi penanganan event penginstalan:

  1. Mulai server agen Anda.
  2. Buka Agents Playground. Agents Playground terhubung ke agen Anda dan secara otomatis memicu event penginstalan.
  3. Konfirmasikan bahwa pesan selamat datang muncul di percakapan chat.

Cuplikan layar yang menunjukkan antarmuka Agents Playground dengan pesan sambutan agen 'Terima kasih telah merekrut saya! Saya menantikan untuk membantu Anda dalam perjalanan profesional Anda!' yang ditampilkan di percakapan obrolan dan panel log setelah event instalasi dipicu secara otomatis.

Untuk detail tentang implementasi handler, lihat Penanganan event instalasi dan uninstall agen.

Lihat log observabilitas

Untuk melihat log observabilitas selama pengembangan lokal, instrumentasikan agen Anda dengan kode observabilitas (lihat Observabilitas untuk contoh kode) dan konfigurasikan variabel lingkungan sebagaimana dijelaskan dalam Variabel observabilitas. Untuk instruksi validasi langkah demi langkah dan output log yang diharapkan, lihat Validasi secara lokal. Setelah dikonfigurasi, pelacakan real-time akan muncul di konsol yang menunjukkan:

  • Jejak pemanggilan agen
  • Rincian eksekusi alat
  • Panggilan inferensi LLM
  • Pesan input dan output
  • Penggunaan token
  • Waktu respons
  • Informasi Kesalahan

Log-log ini membantu Anda melakukan debug masalah, memahami perilaku agen, dan mengoptimalkan performa. Sebelum menerbitkan, gunakan Validasi untuk penerbitan di toko untuk memastikan semua atribut yang diperlukan sudah tersedia.

Langkah berikutnya

Setelah menguji agen Anda secara lokal, terapkan ke Azure dan publikasikan ke Microsoft 365.

Untuk menguji agen Anda di aplikasi Microsoft 365 seperti Teams, Word, dan Outlook, lihat Siklus Hidup Pengembangan Agent 365.

Pemecahan masalah

Bagian ini memberikan solusi untuk masalah umum yang mungkin Anda temui saat menguji agen Anda secara lokal.

Kiat

Panduan Pemecahan Masalah Agent 365 menyediakan rekomendasi pemecahan masalah tingkat tinggi, praktik terbaik, dan tautan ke konten pemecahan masalah untuk setiap bagian siklus hidup pengembangan Agent 365.

Masalah koneksi dan lingkungan

Masalah-masalah ini berkaitan dengan konektivitas jaringan, konflik port, dan masalah penyiapan lingkungan yang mencegah agen Anda berkomunikasi dengan benar.

Masalah koneksi dengan Agents Playground

Gejala: Agents Playground tidak dapat terhubung ke agen Anda.

Solusi:

  • Pastikan server agen Anda berjalan.
  • Periksa apakah nomor port cocok antara agen Anda dan Agents Playground.
  • Pastikan tidak ada aturan firewall yang memblokir koneksi lokal.
  • Coba mulai ulang agen dan Agents Playground.

Versi Agents Playground yang kedaluwarsa

Gejala: Kesalahan tak terduga atau fitur yang tidak tersedia di Agents Playground.

Solusi: Hapus instalasi dan instal ulang Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Konflik port

Gejala: Kesalahan yang menunjukkan port sedang digunakan.

Solusi:

  • Hentikan instansi lain dari agen Anda.
  • Ubah port dalam konfigurasi Anda.
  • Matikan proses yang menggunakan port tersebut.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Gagal menambahkan DeveloperMCPServer

Gejala: Terjadi kesalahan ketika mencoba menambahkan DeveloperMCPServer di Visual Studio Code.

Solusi: Tutup dan buka kembali Visual Studio Code, lalu coba tambahkan server lagi.

Masalah autentikasi dan token

Masalah-masalah ini terjadi ketika agen Anda gagal mengautentikasi dengan benar ke layanan Microsoft 365 atau ketika kredensial Anda kedaluwarsa atau dikonfigurasi secara tidak benar.

Gejala:

  • Kesalahan 401 Tidak Diizinkan
  • Pesan "Token pembawa kedaluwarsa"
  • Kegagalan autentikasi agentic

Akar penyebab:

  • Token kedaluwarsa setelah sekitar satu jam
  • Konfigurasi autentikasi salah
  • Kredensial yang hilang atau tidak valid

Solusi:

  • Untuk kedaluwarsa token pembawa

    Dapatkan ulang token Anda dan perbarui variabel lingkungan Anda.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Untuk kegagalan token pembawa pada setiap server

    Verifikasi file konfigurasi Anda memiliki entri placeholder untuk setiap server (BEARER_TOKEN_<SERVER_NAME>), lalu jalankan a365 develop get-token lagi untuk mengisinya. SDK menghasilkan nama variabel dengan mengubah mcpServerName dalam ToolingManifest.json menjadi huruf kapital dan mengganti tanda hubung dengan garis bawah (misalnya, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Untuk kesalahan autentikasi agentic (Python)

    Periksa file .env:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Untuk kredensial yang hilang

    Pastikan kredensial yang diperlukan sudah tersedia sebelum pengujian.

    Memastikan .env atau appsettings.json berisi:

    • Kunci API dan secret API
    • ID Penyewa
    • ID Klien
    • ID Blueprint (jika menggunakan autentikasi agentic)

    Verifikasi:

    Uji dengan permintaan sederhana di Agents Playground. Anda seharusnya menerima respons tanpa kesalahan 401.

  • Masalah alat dan notifikasi

    Masalah ini mencakup pemanggilan alat, interaksi server MCP, dan pengiriman pemberitahuan.

Email tidak diterima

Gejala: Agen menunjukkan email telah dikirim, tetapi Anda tidak menerimanya

Solusi:

  • Periksa folder Sampah atau Spam.
  • Pengiriman email mungkin tertunda beberapa menit. Tunggu hingga lima menit.
  • Periksa apakah alamat email penerima sudah benar.
  • Periksa log agen apakah ada kesalahan selama pengiriman email.

Respons komentar Word tidak berfungsi

Masalah yang diketahui: Layanan notifikasi saat ini belum bisa memberikan respons langsung terhadap komentar Word. Fungsionalitas ini sedang dikembangkan.

Pesan tidak sampai ke agen

Gejala: Aplikasi agen Anda tidak menerima pesan yang dikirim ke agen di Teams.

Kemungkinan penyebab:

  • Portal Pengembang tidak dikonfigurasi dengan Blueprint agen.
  • Masalah Azure Web App (kegagalan penyebaran, aplikasi tidak berjalan, kesalahan konfigurasi).
  • Instans agen tidak dibuat dengan benar di Teams.

Solusi:

  • Verifikasi konfigurasi Portal Pengembang:

    Pastikan Anda menyelesaikan konfigurasi cetak biru agen di Portal Pengembang. Pelajari cara mengonfigurasi blueprint agen di Portal Pengembang.

  • Periksa kesehatan Azure Web App:

    Jika Anda menyebarkan agen ke Azure, verifikasi Aplikasi Web berjalan dengan benar:

    1. Buka Portal Azure.
    2. Buka sumber daya Aplikasi Web Anda.
    3. Periksa Ikhtisar>Status (akan menunjukkan "Berjalan").
    4. Periksa Log stream di bawah Pemantauan untuk kesalahan runtime.
    5. Tinjau log Pusat Penyebaran untuk memastikan penyebaran berhasil.
    6. Verifikasi Konfigurasi>Pengaturan aplikasi berisi semua variabel lingkungan yang diperlukan.

  • Verifikasi pembuatan instans agen:

    Pastikan Anda membuat instans agen dengan benar di Microsoft Teams:

    1. Buka Microsoft Teams.
    2. Buka Aplikasi dan cari agen Anda.
    3. Pastikan agen muncul di hasil pencarian.
    4. Jika tidak ditemukan, pastikan sudah diterbitkan di pusat admin Microsoft 365 - Agen.
    5. Buat instans baru dengan memilih Add pada agen Anda.
    6. Untuk petunjuk mendetail, lihat Agen onboarding.

Pemecahan masalah log observabilitas

Jika log observabilitas agen Anda tidak muncul seperti yang diharapkan, lihat Pemecahan Masalah di panduan observabilitas.

  • Last updated on