Panduan Cepat: Menyiapkan dan menjalankan agen sampel Agent Framework Python

Dalam Mulai Cepat ini, pelajari penyiapan agen kerangka kerja Python Agent yang berfungsi menggunakan alat, pemberitahuan, observabilitas, dan pengujian agen Agent 365 menggunakan Agents Playground dan Teams.

Prasyarat

Jika Anda berencana untuk menggunakan Visual Studio Code, Anda harus menginstal .NET. (.NET 8.0 direkomendasikan.)
Python 3.11+ telah diinstal
Manajer paket UV terinstal. Lakukan instalasi ini di terminal menggunakan pip install uv.
Dependensi Microsoft Agents Toolkit/Agent Framework

Sampel yang digunakan dalam panduan bergantung pada pustaka Agent Framework yang disediakan melalui Microsoft 365 Agents Toolkit atau ATK. Anda akan secara otomatis menginstalnya saat Anda menggunakan ekstensi Agents Toolkit di VS Code untuk membuat kerangka sampel, atau Anda dapat menginstal paket secara manual menggunakan perintah ini:
```
uv pip install -e . --prerelease=allow
```
Akses ke GitHub
Proyek Agen AI yang sudah ada. Mulai cepat ini menggunakan agen sampel Agent 365 dari toolkit agen Microsoft 365 yang juga dikenal sebagai ATK dalam VS Code.
A365 CLI
Autentikasi Identitas Agen

Siapkan Agent Framework dan sampel Python dari Microsoft 365 Agents Toolkit

Untuk menyiapkan semuanya, Anda menginstal Microsoft 365 Agents Toolkit di VS Code, membuka galeri sampel, dan merancah Agent Framework + sampel Python secara lokal sehingga Anda dapat mengonfigurasi dan menjalankannya nanti. Cuplikan layar berikut menampilkan tampilan yang akan muncul selama proses berlangsung.

Buka Visual Studio Code, lalu buka panel EkstensiCtrl+Shift+X.
Di bilah pencarian, ketik "Agents Toolkit".
Anda akan melihat hasilnya seperti yang ditampilkan pada cuplikan layar berikut.
Pilih Microsoft 365 Agents Toolkit.
Pilih Instal.

VS Code menampilkan tampilan detail ekstensi yang mirip dengan:
Setelah diinstal, ikon M365 Agents Toolkit muncul di bilah navigasi kiri.
Pilih ikon tersebut untuk mendapatkan pengalaman selamat datang.

Sekarang Anda akan melihat opsi seperti Buat Agen Deklaratif, Buat Agen/Aplikasi Baru, dan Lihat Sampel, seperti yang ditunjukkan di sini:
Pilih Lihat Sampel.
Dalam daftar sampel, gulir untuk menemukan sampel agen Agent Framework + Python.
Pilih.

Anda akan melihat dua pilihan: Buat (perancah secara lokal) atau Lihat di GitHub.
Pilih Buat.
Saat diminta, pilih folder di komputer Anda di mana sampel akan dibuat. Misalnya: C:\A365-python-sample

Toolkit ini menghasilkan Agent Framework + sampel Python ke dalam subfolder (misalnya sample_agent) dan kemudian membukanya secara otomatis di VS Code.

Setelah proses scaffolding selesai, Anda sekarang memiliki proyek Agent Framework + agen Python yang sepenuhnya berfungsi di komputer Anda
Instal paket Agent 365 yang diperlukan

Sebelum menjalankan sampel, buka pyproject.toml di proyek Anda dan konfirmasikan bahwa semua dependensi yang diperlukan untuk Agent 365 dan Agent Framework sudah tercantum. Sampel yang dihasilkan oleh Microsoft 365 Agents Toolkit sudah mencantumkan semua entri yang diperlukan.

Setelah Anda meninjau pyproject.toml, instal semuanya dengan menjalankan perintah ini:
```
uv pip install -e . --prerelease=allow
```
Perintah ini mengunduh semua pustaka Agent 365 SDK, dependensi Agent framework, komponen hosting, dan dependensi lain yang ditentukan dalam sampel.
Setelah instalasi, verifikasi bahwa proyek berhasil dibangun dan dijalankan dengan memulai server pengembangan menggunakan perintah ini:
```
uv run python start_with_generic_host.py
```

Menambahkan alat Microsoft 365 (server MCP)

Anda dapat menjelajahi dan mengelola server MCP menggunakan perintah a365 develop di CLI.

Saat bekerja dengan server MCP, Anda dapat:

Menemukan server MCP yang tersedia untuk digunakan
Menambahkan satu atau beberapa server MCP ke konfigurasi agen Anda
Meninjau server MCP yang saat ini dikonfigurasi
Menghapus server MCP yang tidak lagi Anda perlukan

Setelah server MCP ditambahkan, manifes alat pada agen Anda akan diperluas untuk mencakup entri yang mirip dengan:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Pelajari cara menambahkan dan mengelola alat

Langganan dan penanganan pemberitahuan

Agen contoh berlangganan semua pemberitahuan Agent 365 SDK menggunakan onAgentNotification("*") dan merutekannya ke satu handler. Handler ini memungkinkan agen untuk merespons kejadian latar belakang atau sistem, bukan hanya pesan langsung dari pengguna.

Pelajari cara memberi notifikasi kepada para agen

Kode berikut menunjukkan bagaimana pemberitahuan dikonfigurasi pada file agent.py.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Observabilitas

Cuplikan ini menampilkan perubahan minimal yang diperlukan untuk memungkinkan observabilitas dalam sampel. Cuplikan menginisialisasi SDK Observabilitas Agent 365 dan membungkus setiap pemanggilan agen dalam InferenceScope sehingga input, output, dan metadata dapat ditangkap secara otomatis.

Kode berikut menunjukkan contoh observabilitas yang disederhanakan pada file agent.py.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Kode ini merupakan konfigurasi observabilitas lengkap yang diperlukan untuk contoh Python + Agent Framework. Pelajari selengkapnya tentang observabilitas

Menguji agen

Atur variabel lingkungan yang diperlukan, pilih mode autentikasi, dan mulai agen secara lokal. Anda dapat menguji semuanya secara end-to-end dengan Agents Playground tanpa memerlukan penyewa Microsoft 365, kecuali jika Anda ingin memublikasikan agen dan menggunakannya di aplikasi seperti Teams atau Outlook.

Ringkasan langkah-langkah pengujian

Tambahkan kunci API dan pengaturan model Anda ke file .env agar sampel dapat terhubung dengan LLM.
Pilih mode autentikasi. Untuk pengembangan lokal, sampel mendukung Agentic Auth dengan memanfaatkan nilai yang berasal dari Blueprint Agen.
Jalankan agen secara lokal agar tersedia untuk alat seperti Agents Playground.
Gunakan Agents Playground untuk menguji pesan, alat, dan notifikasi tanpa menyiapkan penyewa atau menyebarkan apa pun.
Saat Anda siap untuk perilaku dunia nyata, publikasikan penyewa Microsoft 365 dan uji agen di Teams, Outlook, atau permukaan Microsoft 365 lainnya.

Pelajari selengkapnya tentang pengujian

Terbitkan agen Anda

Saat agen Anda siap untuk pengalaman Microsoft 365 yang sebenarnya seperti obrolan Teams, pesan Outlook, Word @mentions, Anda publikasikan ke penyewa Microsoft 365. Perintah Agent 365 CLI publishbertanggung jawab atas pengemasan: memperbarui manifes Anda, menggabungkan semuanya, dan mengunggah agen ke pusat admin Microsoft.

Saat proses publikasi, tinjau dan sesuaikan nama, deskripsi, ikon, dan versi agen sebelum menyelesaikan pengunggahan. Setelah dipublikasikan, agen Anda akan terdaftar dan dapat diinstal pada penyewa.

Penting

Setelah agen dipublikasikan, Anda harus mengonfigurasi blueprint agen di Portal Pengembang sebelum membuat instans. Pelajari cara mengonfigurasi blueprint agen di Portal Pengembang

Anda dapat melihat agen yang diterbitkan di sini: https://admin.cloud.microsoft/#/agents/all

Pelajari lebih lanjut tentang alur kerja lengkap dan panduan langkah demi langkah

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-31