Menambahkan dan mengelola alat

Modul Tooling membantu pengembang menemukan, mengonfigurasi, dan mengintegrasikan server Model Context Protocol (MCP) ke alur kerja agen AI. Server MCP mengekspos kemampuan eksternal sebagai alat yang dapat digunakan oleh agen AI. Untuk gambaran server tooling yang tersedia, lihat server tooling Agent 365.

Menunjukkan alur permintaan dan respons

Ikhtisar

Integrasi Agent 365 Tooling mengikuti alur kerja berikut:

  1. Konfigurasikan server MCP - Gunakan Agent 365 CLI untuk menemukan dan menambahkan server MCP
  2. Buat manifes - CLI membuat ToolingManifest.json di folder proyek Anda dengan konfigurasi server.
  3. Terapkan izin ke Blueprint - Seorang Administrator Global memberikan izin OAuth2 ke Blueprint agen dengan menjalankan a365 setup all (first-time setup) or a365 setup permissions mcp (jika Blueprint sudah ada). Bagaimanapun, perintah membaca ToolingManifest.json dan memerlukan persetujuan admin. Langkah ini selalu dilakukan secara terpisah dari penambahan server ke manifes.
  4. Integrasikan ke kode - Muat manifes dan daftarkan alat dengan orkestrator Anda.
  5. Panggil alat - Agen memanggil alat selama eksekusi untuk melakukan operasi.

Prasyarat

Sebelum mengonfigurasi server MCP, pastikan Anda memiliki:

  • Agent 365 CLI diinstal dan dikonfigurasi
  • .NET 8.0 SDK atau lebih tinggi - Unduh
  • Hak istimewa Administrator Global di penyewa Microsoft 365 Anda

Penyiapan identitas agen

Jika Anda menggunakan autentikasi agen, selesaikan proses pendaftaran agen untuk membuat identitas agen Anda sebelum mengonfigurasi server MCP. Proses ini membuat ID agen Entra dan pengguna agen yang memungkinkan agen Anda mengautentikasi dan mengakses alat MCP.

Penyiapan autentikasi OBO

Jika Anda menggunakan autentikasi Atas Nama (OBO) alih-alih autentikasi agen, agen Anda dapat mengakses alat MCP menggunakan izin pengguna yang didelegasikan tanpa identitas pengguna agen. Dalam alur OBO, agen menukar token yang didelegasikan pengguna untuk melakukan tindakan atas nama pengguna.

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

Menyiapkan prinsipal layanan

Jalankan skrip penyiapan satu kali ini untuk membuat prinsipal layanan untuk Alat Agent 365 di penyewa Anda.

Penting

Operasi ini, yang hanya dilakukan satu kali per penyewa, memerlukan hak istimewa Administrator Global.

  1. Unduh skrip New-Agent365ToolsServicePrincipalProdPublic.ps1 script.

  2. Buka PowerShell sebagai Administrator dan masuk ke direktori skrip.

  3. Jalankan skrip.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Masuk menggunakan kredensial Azure Anda saat diminta.

Setelah selesai, penyewa Anda siap untuk pengembangan agen dan konfigurasi server MCP.

Konfigurasi server MCP

Gunakan Agent 365 CLI untuk menemukan, menambah, dan mengelola server MCP untuk agen Anda. Untuk daftar lengkap server MCP yang tersedia beserta kemampuannya, lihat katalog server MCP.

Temukan server yang tersedia

Daftar semua server MCP yang dapat Anda konfigurasikan:

a365 develop list-available

Menambahkan server MCP

Tambahkan satu atau beberapa server MCP ke konfigurasi agen Anda:

a365 develop add-mcp-servers mcp_MailTools

Penting

Perintah ini hanya memperbarui ToolingManifest.json di folder proyek Anda — perintah ini tidak memberikan izin apa pun ke blueprint. Penerapan izin bergantung pada tahap proses penyiapan:

  • Sebelum pengaturan awal: Jalankan a365 develop add-mcp-servers dulu, lalu lanjutkan dengan a365 setup all. Perintah setup all mencakup langkah pemberian izin MCP sebagai bagian dari pembuatan blueprint.
  • Setelah blueprint ada: Administrator Global harus menjalankan a365 setup permissions mcp secara terpisah. Admin a365.config.json harus menunjuk deploymentProjectPath ke folder proyek yang berisi ToolingManifest.json yang diperbarui. Hingga langkah ini selesai, izin server MCP baru tidak terlihat di blueprint.

Daftar server yang dikonfigurasi

Lihat server MCP yang saat ini dikonfigurasi:

a365 develop list-configured

Hapus server MCP

Hapus server MCP dari konfigurasi:

a365 develop remove-mcp-servers mcp_MailTools

Untuk referensi CLI lengkap, lihat perintah pengembangan a365.

Gunakan server mock tooling untuk pengujian

Untuk pengujian dan pengembangan, gunakan mock tooling server CLI Agent 365 daripada menghubungkan ke server MCP yang sebenarnya. Mock server menyimulasikan interaksi server MCP, sehingga Anda dapat menguji agen secara lokal tanpa ketergantungan eksternal seperti autentikasi.

Server tiruan menawarkan manfaat berikut untuk pengembangan dan pengujian lokal:

  • Pengembangan offline: Uji agen Anda tanpa konektivitas internet atau dependensi eksternal.
  • Pengujian yang konsisten: Dapatkan respons yang dapat diprediksi untuk pengujian kasus tepi.
  • Debugging: Melihat semua permintaan dan respons secara real-time
  • Iterasi cepat: Tidak perlu menunggu panggilan API eksternal atau menyiapkan lingkungan pengujian yang kompleks.

Mulai mock tooling server menggunakan perintah a365 develop start-mock-tooling-server.

Pelajari cara menyiapkan dan mengonfigurasi mock tooling server.

Catatan

Bagian berikut untuk mengonfigurasi manifes dan mengintegrasikan alat ke agen Anda bekerja dengan cara yang sama, baik Anda menggunakan mock tooling server maupun server MCP yang sebenarnya. Atur variabel lingkungan MCP_PLATFORM_ENDPOINT Anda untuk menunjuk ke server tiruan (misalnya: http://localhost:5309) alih-alih titik akhir produksi.

Memahami manifes tooling

Saat Anda menjalankan a365 develop add-mcp-servers, CLI akan menghasilkan file ToolingManifest.json yang berisi konfigurasi untuk semua server MCP. Runtime agen menggunakan manifes ini untuk memahami server mana yang tersedia dan cara mengautentikasikannya.

Struktur manifes

Contoh: ToolingManifest.json

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Parameter manifes

Setiap entri server MCP memuat:

Parameter Deskripsi
mcpServerName Nama tampilan server MCP.
mcpServerUniqueName Pengidentifikasi unik untuk instans server MCP.
cakupan Cakupan OAuth yang diperlukan untuk mengakses kemampuan server MCP (misalnya: McpServers.Mail.All untuk operasi email). Perintah add-mcp-servers mengambil nilai ini dari katalog server MCP.
audiens URI Microsoft Entra ID yang mengidentifikasi sumber daya API target. Perintah add-mcp-servers mengambil nilai ini dari katalog server MCP.

Catatan

Agent 365 CLI secara otomatis mengisi nilai scope dan audience saat Anda menambahkan server MCP. Nilai-nilai ini berasal dari katalog server MCP dan menentukan izin yang diperlukan untuk mengakses setiap server MCP.

Mengintegrasikan alat ke agen

Setelah menghasilkan manifes alat, integrasikan server MCP yang telah dikonfigurasi ke kode agen Anda. Bagian ini mencakup langkah inspeksi opsional dan langkah-langkah integrasi yang diperlukan.

Daftar server alat (opsional)

Kiat

Langkah ini bersifat opsional. Gunakan layanan konfigurasi server alat untuk memeriksa server alat yang tersedia dari manifes alat sebelum menambahkannya ke orkestrator Anda.

Gunakan layanan konfigurasi server alat untuk menemukan server alat mana yang tersedia untuk agen Anda dari manifes alat. Dengan metode ini, Anda dapat:

  • Membuat kueri atas semua server MCP yang telah dikonfigurasi dari file ToolingManifest.json.
  • Mengambil metadata dan kapabilitas server.
  • Memverifikasi ketersediaan server sebelum pendaftaran.

Metode untuk menampilkan daftar server alat yang tersedia dalam paket inti tooling:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Parameter:

Parameter Jenis Deskripsi Nilai yang Diharapkan Diperlukan/Opsional
agentic_app_id str Pengidentifikasi unik untuk instans aplikasi agen String ID aplikasi agen yang valid Wajib
auth_token str Token pembawa untuk autentikasi menggunakan gateway server MCP Token pembawa OAuth yang valid Wajib

Paket: microsoft_agents_a365.tooling

Mendaftarkan alat dengan orkestrator

Gunakan metode ekstensi khusus untuk framework untuk mendaftarkan semua server MCP pada kerangka kerja orkestrasi Anda:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Metode-metode ini:

  • Mendaftarkan semua alat dari server MCP yang dikonfigurasi dengan orkestrator Anda
  • Mengonfigurasi autentikasi dan informasi koneksi secara otomatis
  • Buat alat segera tersedia untuk dipanggil agen Anda

Memilih ekstensi orkestrator Anda

Modul Agent 365 Tooling menyediakan paket ekstensi khusus untuk kerangka kerja orkestrasi yang berbeda:

Catatan

Saat Anda menjalankan a365 develop add-mcp-servers, CLI secara otomatis mengambil cakupan OAuth dan nilai audiens dari katalog server MCP dan menuliskannya ke ToolingManifest.json. Metode ekstensi menggunakan nilai-nilai ini untuk menyiapkan autentikasi saat runtime — tidak diperlukan konfigurasi manual dalam kode agen Anda. Namun, Administrator Global masih harus memberikan izin ini ke blueprint agen sebelum agen Anda dapat menggunakannya dalam produksi: melalui a365 setup all (penyiapan pertama kali) atau a365 setup permissions mcp (jika blueprint sudah ada).

Untuk contoh implementasi terperinci, lihat Contoh Agent 365.

Contoh implementasi

Contoh-contoh berikut menunjukkan cara mengintegrasikan Agent 365 Tooling dengan berbagai kerangka kerja orkestrasi.

Python dengan OpenAI

Contoh ini menunjukkan cara mengintegrasikan alat MCP dengan OpenAI dalam aplikasi Python.

1. Tambah pernyataan impor

Tambahkan impor yang diperlukan untuk mengakses modul Tooling dan ekstensi OpenAI:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Inisialisasi layanan alat

Buat instans layanan konfigurasi dan pendaftaran alat:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. Daftarkan alat MCP dengan agen AI OpenAI

Gunakan metode add_tool_servers_to_agent untuk mendaftarkan semua alat MCP yang telah dikonfigurasi dengan agen OpenAI Anda. Metode ini menangani skenario autentikasi agenik dan nonagenik:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Parameter metode

Tabel berikut menjelaskan parameter yang digunakan dengan metode add_tool_servers_to_agent.

Parameter Deskripsi
agent Instans agen OpenAI tempat alat didaftarkan.
agentic_app_id Pengidentifikasi unik untuk agen (ID aplikasi agenik).
auth Konteks otorisasi untuk pengguna.
context Konteks giliran percakapan saat ini dari Agents SDK. Menyediakan identitas pengguna, metadata percakapan, dan konteks autentikasi untuk pendaftaran alat yang aman.
auth_token (Opsional) token pembawa untuk skenario autentikasi nonagenik.

4. Panggilan selama inisialisasi

Pastikan Anda memanggil metode penyiapan selama inisialisasi sebelum menjalankan agen:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

Metode add_tool_servers_to_agent secara otomatis:

  • Memuat semua server MCP dari file ToolingManifest.json.
  • Mendaftarkan alat mereka ke agen OpenAI.
  • Menyiapkan autentikasi berdasarkan konfigurasi manifes.
  • Membuat alat tersedia untuk digunakan oleh agen Anda.

Untuk contoh penggunaan lengkap, lihat repositori Sampel Agent 365.

Cara lain untuk mengakses server MCP Agent 365

Selain Agent 365 SDK, Anda dapat mengakses server MCP Agent 365 melalui pengalaman pengembangan lainnya:

  • Visual Studio Code - Sambungkan langsung ke server MCP untuk alur kerja pengembangan kustom.
  • Microsoft Copilot Studio - Integrasikan server MCP ke alur percakapan menggunakan pengalaman low-code.
  • Azure AI Foundry - Gunakan server MCP dengan dukungan SDK penuh dan kemampuan orkestrasi tingkat lanjut.

Untuk gambaran lengkap tentang server MCP yang tersedia dan opsi integrasi di seluruh platform ini, lihat Gambaran umum server tooling Agent 365.

Bawa Server MCP (BYO) Anda sendiri

Fitur server MCP Bring Your Own (BYO) memungkinkan Anda mendaftarkan server MCP eksternal milik Anda ke Microsoft Agent 365 agar dapat dikelola, disetujui, dan dipantau secara terpusat di pusat admin Microsoft 365. Server-server tersebut diarahkan melalui tooling gateway Agent 365, memberi admin kontrol atas persetujuan, akses, dan kebijakan, serta memungkinkan tim keamanan untuk memantau penggunaan melalui telemetri. Sebagai pengembang, Anda dapat mendaftarkan server MCP Anda menggunakan Agent 365 CLI, lalu meminta admin Anda untuk meninjau dan menyetujui pendaftaran serta memberikan izin. Server yang telah disetujui kemudian dapat digunakan dalam alat klien yang didukung, dan pemantauan berkelanjutan akan memastikan kepatuhan serta visibilitas di seluruh integrasi.

Untuk petunjuk lengkap, lihat Bawa server (BYO) MCP Anda sendiri.

Menguji agen

Setelah mengintegrasikan alat MCP ke agen, uji pemanggilan alat untuk memastikannya berfungsi dengan benar dan dapat menangani skenario yang berbeda. Ikuti panduan pengujian untuk menyiapkan lingkungan Anda. Selanjutnya, fokuskan perhatian Anda terutama pada bagian Uji pemanggilan alat untuk memvalidasi bahwa alat MCP Anda berfungsi sesuai harapan. Juga, cek mock tooling server untuk menguji koneksi server MCP dan pemanggilan alat tanpa perlu menangani autentikasi.

Menambahkan observabilitas

Tambahkan observabilitas ke agen Anda untuk memantau dan melacak pemanggilan alat MCP agen Anda. Dengan menambahkan kemampuan observabilitas, Anda dapat melacak performa, men-debug masalah, dan memahami pola penggunaan alat. Pelajari lebih lanjut cara menerapkan pelacakan dan pemantauan.

Pemecahan masalah

Bagian ini mencantumkan masalah umum saat Anda mengonfigurasi dan menggunakan server dan alat MCP.

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.

Permasalahan server dan alat MCP

Gejala:

  • Kegagalan pemanggilan alat.
  • Kesalahan "Server MCP tidak ditemukan".
  • Kesalahan izin ditolak saat memanggil alat.

Akar penyebab:

  • Server MCP belum dikonfigurasi.
  • Izin tidak ada.
  • Prinsipal layanan tidak disiapkan.
  • Kebingungan antara server tiruan dan server produksi.

Solusi: Coba solusi berikut untuk mengatasi masalah tersebut.

  • Pastikan server MCP telah dikonfigurasi

    Cantumkan server yang telah dikonfigurasi dan tambahkan yang belum ada.

    # List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

  • Periksa keberadaan prinsipal layanan

    Pastikan prinsipal layanan yang diperlukan telah dibuat untuk alat.

    # Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Untuk pengembangan dan pengujian awal, gunakan server tiruan

    Gunakan mock tooling server untuk pengembangan dan pengujian lokal awal, jika Anda ingin menguji aspek lain dari agen Anda tanpa komponen tooling produksi.

    # Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309

    Pelajari tentang mock tooling server.

  • Verifikasi izin di pusat admin

    Pastikan agen Anda memiliki izin MCP yang diperlukan.

    • Verifikasi bahwa izin API Blueprint agen Anda di Portal Azure mencakup seluruh izin server MCP.

    Verifikasi:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on