Bagikan melalui

Menguji agen menggunakan Microsoft Agent 365 SDK

Penting

Anda harus menjadi bagian dari program pratinjau Frontier untuk mendapatkan akses awal ke Microsoft Agent 365. Frontier menghubungkan Anda langsung dengan inovasi AI terbaru Microsoft. Pratinjau frontier tunduk pada ketentuan pratinjau yang ada dari perjanjian pelanggan Anda. Karena fitur-fitur ini masih dalam pengembangan, ketersediaan dan kemampuannya dapat berubah dari waktu ke waktu.

Uji agen Anda secara lokal menggunakan Agents Playground sebelum penyebaran. Panduan ini mencakup penyiapan lingkungan pengembangan Anda, mengonfigurasi autentikasi, dan memvalidasi fungsionalitas agen Anda dengan alat pengujian Agents Playground.

Setelah agen bekerja secara lokal, Anda dapat menyebarkan dan menerbitkannya untuk mengujinya di aplikasi Microsoft 365 seperti Teams.

Prasyarat

Sebelum memulai, pastikan Anda memiliki prasyarat berikut:

Prasyarat umum

Prasyarat khusus bahasa

Mengonfigurasi lingkungan pengujian agen

Bagian ini mencakup pengaturan variabel lingkungan, mengautentikasi lingkungan pengembangan Anda, dan menyiapkan agen bertenaga Agen 365 Anda untuk pengujian.

Menyiapkan lingkungan pengujian agen Anda mengikuti alur kerja berurutan:

  1. Mengonfigurasi lingkungan Anda - Membuat atau memperbarui file konfigurasi lingkungan Anda

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

  3. Mengonfigurasi autentikasi - Menyiapkan autentikasi agenik

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

    1. Variabel Otentikasi
    2. Konfigurasi titik akhir MCP
    3. Variabel pengamatan
    4. Konfigurasi server aplikasi agen

Setelah menyelesaikan langkah-langkah ini, Anda siap untuk mulai menguji agen Anda di Agents Playground.

Langkah 1: Mengonfigurasi lingkungan Anda

Siapkan file konfigurasi Anda:

cp .env.template .env

Catatan

Lihat sampel Microsoft Agent 365 SDK untuk menemukan templat konfigurasi yang menunjukkan bidang yang diperlukan.

Langkah 2: Konfigurasi LLM

Konfigurasikan pengaturan OpenAI atau Azure OpenAI untuk pengujian lokal. Tambahkan kunci API dan titik akhir layanan yang diperoleh dari prasyarat ke file konfigurasi Anda bersama dengan parameter model apa pun.

Tambahkan ke file Anda .env :

# 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 KETERANGAN Wajib Contoh
OPENAI_API_KEY Kunci API untuk layanan OpenAI Untuk OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Menggunakan API layanan Azure OpenAI Untuk Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL titik akhir layanan Azure OpenAI 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: Mengonfigurasi nilai autentikasi untuk autentikasi identitas agen

Gunakan perintah A365 CLI a365 config display untuk mengambil kredensial cetak biru agen Anda.

a365 config display -g

Perintah ini menampilkan konfigurasi cetak biru agen Anda. Masukkan nilai berikut:

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

Gunakan nilai-nilai ini untuk mengonfigurasi autentikasi agen di agen Anda:

Tambahkan pengaturan berikut ke file Anda .env , ganti nilai tempat penampung 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 KETERANGAN Wajib Contoh
USE_AGENTIC_AUTH Mengaktifkan mode autentikasi agenik Ya true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID klien cetak biru agen dari a365 config display -g Ya 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Rahasia klien cetak biru agen dari a365 config display -g Ya abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID ID penyewa Microsoft Entra dari a365 config display -g Ya adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Catatan

Untuk .NET, pastikan USE_AGENTIC_AUTH=true juga diatur dalam launchSettings.json (lihat Langkah 4: Referensi variabel lingkungan)

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 agenik berfungsi dengan baik.

Tambahkan ke file Anda .env :

# 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 KETERANGAN Wajib
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Jenis handler autentikasi Ya
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Cakupan autentikasi untuk Microsoft Graph Ya
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nama koneksi cetak biru alternatif Ya
CONNECTIONSMAP_0_SERVICEURL Pola URL layanan untuk pemetaan koneksi Ya
CONNECTIONSMAP_0_CONNECTION Nama koneksi untuk pemetaan Ya

Konfigurasi titik akhir privat

Konfigurasi titik akhir MCP (Model Context Protocol) diperlukan untuk menentukan titik akhir platform Agen 365 mana yang harus disambungkan oleh agen Anda. Saat Anda membuat manifes alat yang menentukan server alat untuk agen Anda, Anda harus menentukan titik akhir platform MCP. Titik akhir ini menentukan lingkungan mana (praprod, pengujian, atau produksi) yang terhubung ke server alat MCP untuk kemampuan integrasi Microsoft 365.

Tambahkan ke file Anda .env :

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variabel KETERANGAN Wajib Default Contoh
MCP_PLATFORM_ENDPOINT URL titik akhir platform MCP (praprod, pengujian, atau prod) Tidak Titik akhir produksi

Penting: Jika MCP_PLATFORM_ENDPOINT tidak ditentukan, ini default ke titik akhir produksi.

Variabel pengamatan

Konfigurasikan variabel yang diperlukan ini untuk mengaktifkan pengelogan dan pelacakan terdistribusi untuk agen Anda. Pelajari selengkapnya tentang fitur observabilitas dan praktik terbaik

Catatan

Konfigurasi pengamatan sama di semua bahasa.

Variabel KETERANGAN Default Contoh
ENABLE_A365_OBSERVABILITY Mengaktifkan/menonaktifkan pengamatan false true
ENABLE_A365_OBSERVABILITY_EXPORTER Ekspor jejak ke layanan pengamatan false true
OBSERVABILITY_SERVICE_NAME Nama layanan untuk pelacakan Nama agen my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Namespace layanan Azure Service Bus agent365-samples my-company-agents

Konfigurasi server aplikasi agen

Konfigurasikan port tempat server aplikasi agen Anda berjalan. Ini bersifat opsional dan berlaku untuk agen Python dan JavaScript.

Tambahkan ke file Anda .env :

# Server Configuration
PORT=3978
Variabel KETERANGAN Wajib Default Contoh
PORT Nomor port tempat server agen berjalan Tidak 3978 3978

Menginstal dependensi dan memulai server aplikasi agen

Setelah lingkungan Anda dikonfigurasi, Anda perlu menginstal dependensi yang diperlukan dan memulai server aplikasi agen Anda secara lokal untuk pengujian.

Instal dependensi: 

uv pip install -e .

Perintah ini membaca dependensi paket yang ditentukan dan pyproject.toml menginstalnya dari PyPI. Saat membuat aplikasi agen dari awal, Anda perlu membuat pyproject.toml file untuk menentukan dependensi Anda. Agen sampel dari repositori sampel sudah memiliki paket ini yang ditentukan. Anda dapat menambahkan atau memperbaruinya sesuai kebutuhan.

Memulai server aplikasi agen

python <main.py>

Ganti <main.py> dengan nama file Python utama Anda yang berisi titik masuk untuk aplikasi agen Anda (misalnya, start_with_generic_host.py, app.py, atau main.py).

Atau menggunakan uv:

uv run python <main.py>

Server agen Anda sekarang harus berjalan dan siap menerima permintaan dari aplikasi Agents Playground atau Microsoft 365.

Agen uji di Agents Playground

Agents Playground adalah alat pengujian lokal yang mensimulasikan lingkungan Microsoft 365 tanpa memerlukan penyiapan penyewa penuh. Ini adalah cara tercepat untuk memvalidasi logika agen dan pemanggilan alat Anda. Untuk informasi selengkapnya, lihat Menguji dengan Agen Playground.

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

agentsplayground

Ini membuka browser web dengan antarmuka Agents Playground. Alat ini menampilkan antarmuka obrolan tempat Anda dapat mengirim pesan ke agen Anda.

Pengujian Dasar

Mulailah dengan memverifikasi agen Anda dikonfigurasi dengan benar. Kirim pesan ke agen:

What can you do?

Agen harus membalas dengan instruksi yang dikonfigurasinya, berdasarkan permintaan dan kemampuan sistem agen Anda. Ini mengonfirmasi bahwa:

  • Agen Anda berjalan dengan benar
  • Agen dapat memproses pesan dan merespons
  • Komunikasi antara Agen Playground dan agen Anda berfungsi

Pemanggilan alat pengujian

Setelah mengonfigurasi server alat MCP Anda di toolingManifest.json (lihat Alat untuk instruksi penyiapan), pemanggilan alat pengujian dengan contoh seperti ini:

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 menggunakan server Mail MCP dan mengonfirmasi bahwa pesan telah dikirim.

Alat kalender

List my calendar events for today

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

Alat SharePoint

List all SharePoint sites I have access to

Respons yang diharapkan: Agen meminta 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

Menguji dengan aktivitas pemberitahuan

Selama pengembangan lokal, Anda dapat menguji skenario pemberitahuan dengan mensimulasikan aktivitas kustom di Agents Playground. Ini memungkinkan Anda memverifikasi penanganan pemberitahuan agen Anda sebelum menyebarkannya ke produksi.

Sebelum menguji aktivitas pemberitahuan, pastikan Anda memiliki:

Pemberitahuan memerlukan konfigurasi alat yang tepat dan penyiapan pemberitahuan agar berfungsi dengan benar. Anda bisa menguji skenario seperti pemberitahuan email atau komentar Word menggunakan fitur aktivitas kustom.

Untuk mengirim aktivitas kustom:

  1. Mulai agen dan Agen Playground Anda
  2. Di Agen Playground, navigasikan ke Menipu aktivitas Kustom Aktivitas>
  3. conversationId Salin dari aktivitas (ID percakapan berubah setiap kali Agen Playground dimulai ulang)
  4. Tempelkan JSON aktivitas kustom Anda dan perbarui personal-chat-id bidang dengan ID percakapan yang Anda salin. Lihat contoh pemberitahuan Email
  5. Pilih Tambah aktivitas.
  6. Menampilkan hasilnya di percakapan obrolan dan panel log

Pemberitahuan Email

Ini mensimulasikan email yang dikirim ke agen. Ganti nilai tempat penampung dengan detail agen Anda yang sebenarnya:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Melihat log pengamatan

Untuk melihat log pengamatan selama pengembangan lokal, instrumen agen Anda dengan kode observabilitas (lihat Observabilitas untuk contoh kode) dan konfigurasikan variabel lingkungan seperti yang dijelaskan dalam variabel Observabilitas. Setelah dikonfigurasi, jejak real-time muncul di konsol yang menunjukkan:

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

Log ini membantu Anda men-debug masalah, memahami perilaku agen, dan mengoptimalkan performa.

Mengatasi Masalah

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

Masalah koneksi dan lingkungan

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

Masalah koneksi Agents Playground

Gejala: Agen Playground tidak dapat terhubung ke agen Anda

### Solusi:

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

Versi Playground Agen yang Kedaluarsa

Gejala: Kesalahan tak terduga atau fitur yang hilang di Agents Playground

Solusi: Hapus instalan dan instal ulang Agen Playground:

winget uninstall agentsplayground
winget install agentsplayground

Konflik port

Gejala: Kesalahan yang menunjukkan port sudah digunakan

### Solusi:

  • Menghentikan instans lain dari agen Anda
  • Mengubah port dalam konfigurasi Anda
  • Matikan proses apa pun menggunakan port:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Tidak dapat menambahkan DeveloperMCPServer

Gejala: Kesalahan saat mencoba menambahkan DeveloperMCPServer di Visual Studio Code

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

Masalah autentikasi

Masalah ini terjadi saat agen Anda tidak dapat mengautentikasi dengan benar dengan layanan Microsoft 365 atau saat kredensial kedaluwarsa atau salah dikonfigurasi.

Token pembawa kedaluwarsa

Gejala: Kesalahan autentikasi atau respons 401 Tidak Sah

Solusi: Token pembawa kedaluwarsa setelah sekitar 1 jam. Dapatkan token baru dan perbarui konfigurasi Anda.

Kesalahan autentikasi agenik di Python

Gejala: Kesalahan saat memperoleh token instans agenik

Solusi: Verifikasi ALT_BLUEPRINT_NAME pengaturan di :.env

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Masalah alat dan pemberitahuan

Masalah ini melibatkan masalah dengan pemanggilan alat, interaksi server MCP, dan pengiriman pemberitahuan.

Email tidak diterima

Gejala: Agen menunjukkan email dikirim, tetapi Anda tidak menerimanya

### Solusi:

  • Periksa folder spam Anda.
  • Pengiriman email dapat ditunda beberapa menit - tunggu hingga 5 menit
  • Verifikasi alamat email penerima sudah benar
  • Periksa log agen untuk kesalahan apa pun selama pengiriman email

Respons komentar Word tidak berfungsi

Masalah yang diketahui: Layanan pemberitahuan saat ini tidak dapat merespons langsung komentar Word. Fungsionalitas ini sedang dikembangkan.

Mendapatkan Bantuan

Jika Anda mengalami masalah yang tidak tercakup di bagian pemecahan masalah ini, jelajahi sumber daya ini:

Repositori Microsoft Agent 365 SDK

Dukungan lainnya

Langkah berikutnya

Setelah berhasil menguji agen secara lokal, Anda siap untuk menyebarkannya ke Azure dan menerbitkannya ke Microsoft 365:

  • Menyebarkan dan menerbitkan agen: Pelajari cara menyebarkan agen Anda ke Azure Web App dan menerbitkannya ke Pusat Admin Microsoft, membuatnya tersedia untuk ditemukan dan disewa organisasi Anda di Microsoft 365.
  • Last updated on