Mulai cepat: Menyiapkan dan menjalankan agen sampel kerangka kerja Agen Python

Dalam Mulai Cepat ini, telusuri penyiapan agen kerangka kerja Python Agent yang berfungsi menggunakan Agen 365 untuk alat, pemberitahuan, pengamatan, dan pengujian agen menggunakan Agents Playground dan Teams.

Prasyarat

Jika Anda berencana menggunakan Visual Studio Code, Anda harus menginstal .NET. (.NET 8.0 disarankan.)
Python 3.11+ terinstal
Manajer Paket UV terinstal. Instal ini di terminal menggunakan pip install uv.
Dependensi Microsoft Agents Toolkit / Agent Framework

Sampel yang digunakan dalam panduan bergantung pada pustaka Kerangka Kerja Agen yang disediakan melalui Toolkit atau ATK Agen Microsoft 365. Anda akan menginstalnya secara otomatis saat Menggunakan ekstensi Toolkit Agen di Visual Studio Code untuk membuat perancah sampel, atau Anda dapat menginstal paket secara manual menggunakan perintah ini:
```
uv pip install -e . --find-links ../dist --pre
```
Akses ke GitHub
Proyek Agen AI yang ada. Mulai cepat ini menggunakan agen sampel Agen 365 dari toolkit agen Microsoft 365 yang juga dikenal sebagai ATK di VS Code.
A365 CLI
Autentikasi Identitas Agen

Menyiapkan kerangka kerja Agen + sampel Python dari Toolkit Agen Microsoft 365

Untuk menyiapkan semuanya, Anda menginstal Toolkit Agen Microsoft 365 di Visual Studio Code, membuka galeri sampel, dan membuat perancah kerangka kerja Agen + sampel Python secara lokal sehingga Anda dapat mengonfigurasi dan menjalankannya nanti. Cuplikan layar berikut menunjukkan apa yang harus Anda harapkan untuk dilihat saat Anda pergi.

Buka Visual Studio Code, lalu buka panel Ekstensi Ctrl+Shift+X.
Di bilah pencarian, ketik "Agents Toolkit".
Anda akan melihat hasil yang ditampilkan dalam cuplikan layar di sini:
Toolkit Agen Microsoft 365
Pilih Instal.

Visual Studio Code memperlihatkan tampilan detail ekstensi yang mirip dengan:
Setelah diinstal, ikon Toolkit Agen M365 muncul di bilah navigasi kiri.
Pilih untuk membuka pengalaman selamat datang.

Anda sekarang akan melihat opsi seperti Membangun Agen Deklaratif, Membuat Agen/Aplikasi Baru, dan Melihat Sampel, seperti yang ditunjukkan di sini:
Pilih Tampilkan Sampel.
Dalam daftar sampel, gulir untuk menemukan kerangka kerja Agen + sampel agen Python .
Pilih.

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

Perancah toolkit melipat kerangka kerja Agen + sampel Python ke dalam subfolder (seperti sample_agent) dan kemudian membukanya secara otomatis di Visual Studio Code.

Setelah perancah selesai, Anda sekarang memiliki kerangka kerja Agen yang berfungsi penuh + proyek agen Python di komputer Anda
Menginstal paket Agen 365 yang diperlukan

Sebelum menjalankan sampel, buka package.json di proyek Anda dan konfirmasikan bahwa semua dependensi kerangka kerja Agen 365 dan Agen yang diperlukan tercantum. Sampel yang dihasilkan oleh Toolkit Agen Microsoft 365 sudah menyertakan entri ini.

Setelah Anda meninjau package.json, instal semuanya dengan menjalankan perintah ini:
```
uv pip install -e
```
Ini menarik semua pustaka Agen 365 SDK, dependensi kerangka kerja Agen, komponen hosting, dan dependensi lain yang ditentukan dalam sampel.
Setelah penginstalan, verifikasi proyek yang dibangun dan dijalankan dengan memulai server dev 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 pengembangan a365 di CLI.

Saat bekerja dengan server MCP, Anda dapat:

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

Setelah server MCP ditambahkan, manifes peralatan agen Anda diperluas untuk menyertakan 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 pemberitahuan dan penanganan

Agen sampel berlangganan semua pemberitahuan Agen 365 SDK menggunakan onAgentNotification("*") dan merutekannya ke satu handler. Handler ini memungkinkan agen untuk bereaksi terhadap peristiwa latar belakang atau sistem, bukan hanya pesan pengguna langsung.

Pelajari cara memberi tahu agen

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

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 menunjukkan perubahan minimal yang diperlukan untuk mengaktifkan pengamatan dalam sampel. Ini menginisialisasi SDK Observabilitas Agen 365 dan membungkus setiap pemanggilan agen dengan InferenceScope begitu input, output, dan metadata dapat ditangkap secara otomatis.

Kode berikut menunjukkan contoh pengamatan yang disederhanakan dalam agent.py file.

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 adalah penyiapan observabilitas lengkap yang diperlukan untuk sampel kerangka kerja Python + Agent. Pelajari selengkapnya tentang pengamatan

Menguji agen

Atur variabel lingkungan yang diperlukan, pilih mode autentikasi, dan mulai agen secara lokal. Anda dapat menguji semuanya secara menyeluruh dengan Agen Playground tanpa memerlukan penyewa Microsoft 365 kecuali Anda ingin menerbitkan agen dan menggunakannya di aplikasi seperti Teams atau Outlook.

Gambaran umum langkah pengujian

Tambahkan kunci API dan pengaturan model Anda ke .env file sehingga sampel dapat berbicara dengan LLM.
Pilih mode autentikasi Anda. Untuk pengembangan lokal, sampel mendukung Agentic Auth menggunakan nilai yang dibuat dari Cetak Biru Agen Anda.
Mulai agen secara lokal, yang mengeksposnya ke alat seperti Agents Playground.
Gunakan Agen Playground untuk menguji pesan, alat, dan pemberitahuan tanpa menyiapkan penyewa atau menyebarkan apa pun.
Saat Anda siap untuk perilaku dunia nyata, terbitkan penyewa Microsoft 365 dan uji agen di dalam permukaan Teams, Outlook, atau Microsoft 365 lainnya.

Pelajari selengkapnya tentang pengujian

Terbitkan agen Anda

Saat agen Anda siap untuk pengalaman Microsoft 365 aktual seperti obrolan Teams, pesan Outlook, Word @mentions, Anda menerbitkannya ke penyewa Microsoft 365. Perintah Agen 365 CLI publish menangani kemasan: perintah ini memperbarui manifes Anda, membedel semuanya, dan mengunggah agen ke Pusat Admin Microsoft.

Selama penerbitan, tinjau dan sesuaikan nama, deskripsi, ikon, dan versi agen sebelum menyelesaikan unggahan. Setelah dipublikasikan, agen Anda menjadi dapat ditemukan dan dapat diinstal di dalam penyewa.

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

Pelajari selengkapnya tentang alur kerja lengkap dan instruksi langkah demi langkah

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-02