Buat instans agen

Setelah menerbitkan agen dan menyediakannya di pusat admin Microsoft, Anda dapat membuat instans agen dan pengguna agen. Instans dan pengguna ini menggunakan blueprint agen dan kode agen yang Anda buat.

Artikel ini memecah prosesnya menjadi tiga langkah utama:

  1. Konfigurasikan agen di Portal Pengembang Teams
  2. Buat instans agen
  3. Uji agen yang telah disebarkan

Jika Anda mengalami masalah, lihat bagian Pemecahan Masalah.

Prasyarat

1. Konfigurasikan agen di Portal Pengembang Teams

Setelah agen diterbitkan, konfigurasikan blueprint agen di Portal Pengembang Teams agar agen Anda terhubung ke infrastruktur perpesanan Microsoft 365. Tanpa konfigurasi ini, agen Anda tidak menerima pesan dari Teams, email, atau layanan Microsoft 365 lainnya.

  1. Dapatkan ID blueprint

    Buka a365.generated.config.json di direktori kerja Anda, kemudian salin nilai dari agentBlueprintId.

  2. Navigasikan ke Portal Pengembang

    Buka browser Anda dan kunjungi halaman konfigurasi:

    https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    Ganti <your-blueprint-id> dengan nilai agentBlueprintId yang Anda salin.

    Catatan

    Jika Anda tidak memiliki akses ke Portal Pengembang, hubungi administrator penyewa Anda untuk memberikan akses atau menyelesaikan konfigurasi ini atas nama Anda.

  3. Konfigurasi agen

    Di Portal Pengembang:

    1. Setel Jenis Agen menjadi Berbasis API

    2. Atur URL Pemberitahuan ke titik akhir perpesanan agen Anda. Temukan nilai messagingEndpoint di a365.generated.config.json.

    3. Pilih Simpan.

    Cuplikan layar yang memperlihatkan halaman konfigurasi Portal Pengembang dengan Jenis Agen disetel ke Berbasis API serta bidang URL Pemberitahuan.

Anda memerlukan konfigurasi ini sebelum dapat membuat instans agen di Teams.

Pelajari selengkapnya tentang blueprint identitas agen dan konfigurasi di Portal Pengembang.

2. Buat instans agen

Sekarang Anda dapat meminta instans blueprint agen Anda dari Teams. Pelajari selengkapnya tentang cara menemukan, membuat, dan mengorientasi agen.

Saat Anda meminta instans agen, Teams mengirimkan permintaan ke admin penyewa Anda untuk disetujui. Admin dapat meninjau dan menyetujui permintaan pada halaman Pusat admin Microsoft - Permintaan Agen.

Setelah admin menyetujui permintaan Anda, Teams membuat instans agen Anda dan membuatnya tersedia di Teams.

3. Uji agen yang telah disebarkan

Setelah membuat instans agen, lakukan pengujian di Microsoft 365 untuk memastikan instans tersebut bekerja dengan baik di lingkungan produksi.

Setelah deployment, dan dengan pemberitahuan agen yang diaktifkan di Agent 365 SDK, agen Anda terintegrasi dengan layanan Microsoft 365. Agen ini bekerja dengan Teams untuk obrolan, saluran, dan rapat; dengan email dan kalender untuk mengirim, menerima, dan menjadwalkan; serta dengan SharePoint dan OneDrive untuk akses dokumen dan berbagi file. Agen ini juga mendukung fitur kolaborasi seperti kehadiran organisasi, tugas Planner, dan komentar dokumen.

Penting

Sama seperti pengguna biasa, pengguna agen juga memerlukan lisensi Microsoft 365 yang sesuai untuk mengakses layanan. Lisensi umum termasuk Microsoft 365 E5, Teams Enterprise, dan Microsoft 365 Copilot.

Melihat agen yang disebarkan di pusat admin

Setelah Anda menerbitkan agen, agen tersebut muncul di pusat admin Microsoft untuk perekrutan. Mungkin perlu beberapa waktu untuk disebarkan.

Buka Pusat Admin Microsoft 365 - Agen untuk:

  • Melihat agen yang diterbitkan
  • Mengelola pengaturan agen
  • Memantau penggunaan agen
  • Mengonfigurasi izin

Menguji agen di Teams

Setelah Anda menerapkan, menerbitkan, dan mengkonfigurasi Blueprint agen serta membuat pengguna agen, uji pengguna agen tersebut secara langsung di Microsoft Teams:

Mulai pengujian

  1. Cari pengguna agen baru Anda di Teams.

    Catatan

    Proses pembuatan pengguna agen bersifat asinkron. Diperlukan waktu beberapa menit hingga beberapa jam agar pengguna agen dapat dicari setelah Anda membuatnya.

  2. Mulai obrolan baru dengan instans agen yang baru Anda buat.

  3. Kirim pesan pengujian untuk memverifikasi fungsionalitas agen.

Contoh pesan pengujian

Jika Anda mengonfigurasi agen dengan Email, kirim pesan ini untuk menguji fungsionalitas email. Perbarui nilai email recipient@contoso.com penerima.

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

Agen memproses permintaan dan mengirim email tanpa memerlukan konfirmasi lebih lanjut.

Checklist verifikasi

Setelah membuat instans agen, verifikasi bahwa instans tersebut berfungsi dengan benar di Teams.

✅ Konfigurasi portal pengembang disimpan
✅ Agen muncul di pencarian aplikasi Teams
✅ Anda dapat membuat instans agen di Teams
✅ Instans agen dibuat
✅ Pengguna agen muncul di organisasi
✅ Agen merespons pesan
✅ Agen dapat melakukan tindakan
✅ Log aplikasi tidak menunjukkan kesalahan
✅ Observabilitas berfungsi di pusat admin

Jika instans agen Anda tidak berfungsi seperti yang diharapkan, lihat bagian Pemecahan Masalah untuk solusi terperinci untuk masalah umum.

Pastikan konfigurasi portal pengembang sudah disimpan

Navigasikan ke: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ Jenis Agen menampilkan: URL Notifikasi✅Berbasis API cocok dengan titik akhir ✅ perpesanan agen Anda Menampilkan pesan Berhasil Disimpan

Pastikan agen Anda muncul di Teams

  1. Buka Aplikasi >Teams

  2. Cari nama agen Anda

    ✅ Agen muncul di hasil penelusuran ✅ Beserta ikon dan deskripsinya

Pastikan Anda dapat membuat instansi agen di Teams

Pilih agen Anda di aplikasi Teams

✅ Tombol Minta Instans/Buat Instans diaktifkan ✅ Dapat meminta instans tanpa kesalahan

Verifikasi instans agen telah dibuat

Setelah memilih Minta Instans:

✅ Permintaan berhasil dikirim ke admin

Verifikasi pengguna agen muncul di organisasi

Di Pusat admin Microsoft 365:

  1. Buka: https://admin.cloud.microsoft/#/agents/all
  2. Navigasikan ke tab Semua Permintaan Agen

✅ Permintaan instans agen Anda ditampilkan dengan status menunggu peninjauan ✅ Admin dapat menyetujui instans agen untuk digunakan ✅ Pengguna dapat membuat instans dari Teams dan memberinya nama.

Verifikasi agen merespons pesan

Di obrolan Teams dengan agen Anda - Kirim pesan tes: Hello!

✅ Agen menunjukkan indikator pengetikan ✅ Agen merespons dalam beberapa detik ✅ Respons koheren dan relevan

Verifikasi apakah agen dapat melakukan tindakan

Jika Anda mengonfigurasi alat, uji fungsionalitasnya. Misalnya, jika Anda menambahkan server MCP Mail, kirim email tes ke diri sendiri.

Yang harus dilakukan agen:

✅ Mengakui permintaan ✅ Menjalankan panggilan alat ✅ Mengonfirmasi keberhasilan penyelesaian

Anda harus memverifikasi bahwa email telah tiba di kotak masuk Anda.

Periksa fungsionalitas

Daftar periksa berikut memberikan pendekatan pengujian sistematis untuk agen Anda:

Fungsionalitas dasar:

✅ Agen merespons salam sederhana. ✅ Agen menangani percakapan bertahap. ✅ Agen memberikan respons yang relevan.

Fungsionalitas alat:

Tergantung konfigurasi server MCP

✅ Dapat mengirim email. ✅ Dapat mengakses kalender. ✅ Dapat mencari dokumen. ✅ Dapat melakukan tindakan yang dikonfigurasi.

Penanganan kesalahan:

✅ Menangani permintaan yang tidak valid dengan baik. ✅ Memberikan pesan kesalahan yang bermanfaat. ✅ Tidak mengalami crash ketika menerima masukan yang tidak terduga.

Performa:

✅ Merespons dalam beberapa detik. ✅ Tidak ada kesalahan timeout. ✅ Waktu respons yang konsisten.

Periksa log aplikasi

Untuk melihat apa yang dilakukan agen Anda, periksa log aplikasi dengan menggunakan perintah az webapp log tail.

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Hal yang perlu diperhatikan pada log:

✅ Permintaan masuk dari Teams ✅ Autentikasi berhasil ✅ Panggilan alat yang dieksekusi ✅ Respons yang dikirim ❌ Pesan error atau pengecualian

Verifikasi observabilitas di pusat admin

Setelah agen Anda mulai berjalan:

  1. Buka: https://admin.cloud.microsoft/#/agents/all.

  2. Pilih agen Anda dan buka tab Aktivitas.

    Anda harus melihat:

    ✅ Sesi terlihat. ✅ Setiap sesi menunjukkan pemicu dan tindakan. ✅ Panggilan alat dicatat dengan stempel waktu.

Langkah berikutnya

Agen Anda sekarang aktif di cloud dan siap bekerja bersama tim Anda di Microsoft 365. Apa yang awalnya merupakan kode lokal kini telah menjadi asisten yang terdaftar dan siap digunakan di lingkungan perusahaan, yang memungkinkan pengguna membuat instans agen di seluruh organisasi Anda.

Siklus hidup pengembangan agen Anda selesai, tetapi dampaknya baru saja dimulai. Sebagian besar dari apa yang Anda buat dalam siklus pengembangan Agent 365 bersifat sumber terbuka dan menyambut kontribusi komunitas. Munculkan bug, permintaan fitur, dan permintaan pull:

  • Sampel Agent 365: Apakah Anda memiliki agen sampel yang menarik dan menyenangkan? Bagikan kode agen Anda dengan komunitas sumber terbuka di sini!
  • Node.js SDK: Agent 365 SDK untuk Node.js.
  • Python SDK: Agent 365 SDK di Python.
  • .NET SDK: Agent 365 SDK di C# (.NET).
  • Agent 365 DevTools CLI: CLI untuk membantu Anda melalui seluruh siklus hidup pengembangan Agent 365.

Pemecahan masalah

Bagian ini berisi masalah umum saat membuat dan menguji instans agen.

Kiat

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

Agen tidak muncul di Teams

Gejala: Agen muncul di pusat admin tetapi Anda tidak dapat menemukannya di Aplikasi Teams.

Penyebab utama: Konfigurasi Portal Pengembang belum dilakukan.

Solusi:

  1. Dapatkan ID blueprint Anda dari a365.generated.config.json — cari agentBlueprintId.

  2. Konfigurasikan di Portal Pengembang:

    1. Buka: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    2. Setel Jenis Agen menjadi Berbasis API

    3. Atur URL Pemberitahuan ke titik akhir perpesanan agen Anda. Temukan nilai messagingEndpoint di a365.generated.config.json.

    4. Pilih Simpan.

  3. Tunggu 5-10 menit untuk propagasi.

Verifikasi:

  • Buka Teams > Apps > Cari agen Anda.
  • Agen muncul dan tersedia untuk ditambahkan.

Tidak dapat membuat instans agen di Teams

Gejala: Agen muncul di Teams tetapi Anda tidak dapat menambah atau membuat instans; Minta Instans tombol tidak berfungsi.

Akar penyebab: Microsoft Agent 365 Frontier tidak diaktifkan untuk penyewa.

Solusi: Hubungi administrator penyewa Anda untuk memastikan bahwa Microsoft Agent 365 Frontier telah diaktifkan pada penyewa.

Pelajari lebih lanjut tentang Frontier.

Verifikasi:

Fitur Frontier akan muncul dalam Microsoft 365 Copilot dan aplikasi Microsoft 365 setelah lisensi dan pengaturan admin Anda memungkinkan.

Agen tidak merespons pesan

Gejala: Anda membuat instans agen tetapi instans tersebut tidak merespons pesan. Log tidak muncul di aplikasi.

Akar penyebab: Beberapa kemungkinan penyebab - masalah titik akhir perpesanan, masalah autentikasi, atau kesalahan konfigurasi.

Pemecahan masalah dasar

  1. Pastikan aplikasi web berjalan:

    az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Should be: "Running"

  2. Periksa titik akhir perpesanan:

    • Harusnya: https://<your-app-root-url>/api/messages
    • Pastikan di a365.config.json dan a365.generated.config.json

  3. Uji titik akhir secara langsung:

    curl https://<your-app-root-url>/api/messages
# Should not return 404

  4. Periksa log aplikasi:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
# Look for incoming requests and errors

Diagnostik lanjutan

  1. Verifikasikan autentikasi:

    • Periksa apakah token sudah kedaluwarsa. Perbarui jika diperlukan.
    • Verifikasi kredensial dalam konfigurasi Aplikasi Web.

  2. Periksa konfigurasi alat/MCP:

    • Verifikasi bahwa server MCP telah dikonfigurasi.
    • Pastikan izin telah diberikan.

  3. Uji secara lokal:

    • Jalankan agen secara lokal dengan konfigurasi yang sama.
    • Uji dengan Agents Playground.
    • Jika berfungsi secara lokal tetapi tidak di cloud, berarti ada masalah penyebaran >

Solusi umum

  • Endpoint pesan salah: Perbarui di portal Azure dan Portal Pengembang.
  • Aplikasi web dihentikan: Mulai menggunakan portal Azure atau CLI.
  • Token sudah kedaluwarsa: Perbarui token di variabel lingkungan aplikasi web.
  • Variabel lingkungan yang hilang: Periksa Pengaturan Aplikasi di portal Azure.
  • Masalah server MCP: Verifikasi perwakilan layanan dan izin.
  • Kesalahan kode: Periksa log aplikasi untuk pengecualian.

Verifikasi

Kirim pesan ke agen Anda di Teams dan periksa log aplikasi untuk permintaan masuk.

Anda mungkin juga ingin mencoba:

Panggilan alat gagal

Gejala: Agen merespons pesan tetapi panggilan ke alat gagal. Anda melihat izin ditolak atau kesalahan batas waktu.

Akar penyebab: Izin server MCP hilang, entitas layanan (service principal) tidak dikonfigurasi, masalah konektivitas jaringan, atau konfigurasi alat yang salah.

Solusi

Coba solusi berikut saat panggilan alat gagal:

  • Verifikasi izin di pusat admin

    Tinjau dan setujui izin server MCP yang diperlukan:

    • Buka: https://admin.cloud.microsoft/#/agents/all
    • Pilih agen Anda > Izin
    • Pastikan daftar menyertakan dan menyetujui server MCP yang diperlukan

  • Memeriksa prinsipal layanan

    Jalankan skrip penyiapan satu kali jika Anda belum menjalankannya sebelumnya:

    # Download and run:
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Verifikasi konfigurasi titik akhir MCP

    Pastikan Anda menggunakan titik akhir MCP produksi:

    # Should be production endpoint, not mock
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft

  • Periksa identitas terkelola

    Verifikasi bahwa identitas terkelola telah diaktifkan pada Aplikasi Web Anda:

    # Verify managed identity is enabled
az webapp identity show --name <your-app-name> --resource-group <your-resource-group>

Verifikasi

Uji panggilan alat melalui Teams dan periksa log untuk eksekusi yang berhasil.

Anda mungkin juga ingin mencoba langkah-langkah berikut:

Penetapan lisensi gagal

Gejala: Anda tidak dapat menetapkan lisensi ke pengguna agen. Anda melihat kesalahan lisensi di pusat admin.

Akar penyebab: Jumlah lisensi yang tersedia tidak mencukupi, jenis lisensi tidak sesuai, atau masalah izin.

Solusi

Coba solusi berikut saat penugasan lisensi gagal:

  1. Pastikan lisensi tersedia:

    • Periksa pusat admin Microsoft 365, pilih >Lisensi>Penagihan.
    • Pastikan Microsoft Agent 365 Frontier diaktifkan untuk penyewa.

  2. Tetapkan lisensi secara manual:

    • Buka pusat admin Microsoft 365 >Pengguna.
    • Cari pengguna agen.
    • Tetapkan lisensi yang sesuai.

  3. Lisensi yang diperlukan untuk fungsionalitas penuh:

    • Microsoft 365 E5 (atau setara).
    • Teams Enterprise.
    • Microsoft 365 Copilot (untuk fitur Copilot).

Verifikasi

Periksa apakah profil pengguna di pusat admin menampilkan lisensi yang ditetapkan.

  • Last updated on