Bagikan melalui

Menambahkan dan mengelola alat

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.

Modul Tooling memungkinkan pengembang untuk menemukan, mengonfigurasi, dan mengintegrasikan server Model Context Protocol (MCP) ke dalam alur kerja agen AI. Server MCP mengekspos kemampuan eksternal sebagai alat yang dapat dipanggil agen AI. Untuk gambaran umum server alat yang tersedia, lihat Server alat Agen 365.

Menunjukkan alur permintaan dan respons

Ikhtisar

Integrasi Agent 365 Tooling mengikuti alur kerja empat langkah:

  1. Mengonfigurasi server MCP - Gunakan Agen 365 CLI untuk menemukan dan menambahkan server MCP
  2. Hasilkan manifes - CLI dibuat ToolingManifest.json dengan konfigurasi server
  3. Mengintegrasikan ke dalam kode - Memuat manifes dan mendaftarkan alat dengan orkestrator Anda
  4. Memanggil alat - Agen memanggil alat selama eksekusi untuk melakukan operasi

Prasyarat

Sebelum mengonfigurasi server MCP, pastikan Anda memiliki:

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

Penyiapan identitas agen

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

Menyiapkan prinsipal layanan

Jalankan skrip penyiapan ONE-TIME ini untuk membuat Perwakilan Layanan untuk Alat Agen 365 di penyewa Anda.

Penting

Ini adalah operasi SATU KALI per penyewa yang memerlukan hak istimewa Administrator Global.

  1. Unduh skrip New-Agent365ToolsServicePrincipalProdPublic.ps1

  2. Buka PowerShell sebagai Administrator dan navigasikan ke direktori skrip

  3. Jalankan skrip

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Jika diminta, masuklah dengan informasi masuk Azure Anda.

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

Konfigurasi server DHCP

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

Menemukan server yang tersedia

Cantumkan semua server MCP yang dapat dikonfigurasi:

a365 develop list-available

Menambahkan server MCP

Tambahkan satu atau beberapa server MCP ke konfigurasi agen Anda:

a365 develop add-mcp-servers mcp_MailTools

Mencantumkan server yang dikonfigurasi

Lihat server MCP yang saat ini dikonfigurasi:

a365 develop list-configured

Menghapus server MCP

Hapus server MCP dari konfigurasi Anda:

a365 develop remove-mcp-servers mcp_MailTools

Untuk referensi CLI lengkap, lihat perintah pengembangan a365.

Memahami manifes alat

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

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 berisi:

Parameter Deskripsi
mcpServerName Nama tampilan server MCP
mcpServerUniqueName Pengidentifikasi unik untuk instans server MCP
ruang lingkup Cakupan OAuth yang diperlukan untuk mengakses kemampuan server MCP (Misalnya: McpServers.Mail.All untuk operasi email). Nilai ini diambil dari katalog server MCP saat Anda menjalankan add-mcp-servers perintah.
penonton URI ID Microsoft Entra yang mengidentifikasi sumber daya API target. Nilai ini juga diambil dari katalog server MCP.

Catatan

Nilai scope dan audience secara otomatis diisi oleh Agen 365 CLI 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 kustom ke agen Anda

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

Mencantumkan server alat (Opsional)

Tip

Pengaturan ini adalah 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. Metode ini memungkinkan Anda untuk:

  • Mengkueri semua server MCP yang dikonfigurasi dari ToolingManifest.json
  • Mengambil metadata dan kemampuan server
  • Memverifikasi ketersediaan server sebelum pendaftaran

Metode untuk mencantumkan server alat tersedia dalam paket peralatan inti:

# 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)

“parameters": {

Parameter Jenis KETERANGAN 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 mengautentikasi dengan gateway server MCP Token pembawa OAuth yang valid Wajib

Paket: microsoft-agents-a365-tooling

Mendaftarkan alat dengan orkestrator Anda

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

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

Metode ini:

  • Daftarkan semua alat dari server MCP yang dikonfigurasi dengan orkestrator Anda
  • Menyiapkan detail autentikasi dan koneksi secara otomatis
  • Membuat alat segera tersedia untuk dipanggil agen Anda

Pilih ekstensi orkestrator Anda

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

  • microsoft-agents-a365-tooling: Fungsionalitas alat inti
  • microsoft-agents-a365-tooling-extensions-agentframework: Integrasi Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Integrasi Azure AI Foundry
  • microsoft-agents-a365-tooling-extensions-openai: Integrasi OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel: Integrasi Kernel Semantik

Catatan

Autentikasi secara otomatis dikonfigurasi oleh Agen 365 CLI saat Anda menjalankan a365 develop add-mcp-servers. Cakupan OAuth dan nilai audiens diambil dari katalog server MCP dan disertakan dalam ToolingManifest.json. Metode ekstensi secara otomatis menggunakan nilai-nilai ini untuk menyiapkan autentikasi - tidak diperlukan konfigurasi manual.

Untuk contoh implementasi terperinci, lihat Sampel Agen 365.

Contoh implementasi

Contoh berikut menunjukkan cara mengintegrasikan Agent 365 Tooling dengan kerangka kerja orkestrasi yang berbeda.

Python dengan OpenAI

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

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. Menginisialisasi layanan alat

Buat instans layanan pendaftaran konfigurasi dan 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 OpenAI

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

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 ini menjelaskan parameter yang akan digunakan dengan add_tool_servers_to_agent.

Parameter Deskripsi
agent Instans agen OpenAI untuk mendaftarkan alat.
agentic_app_id Pengidentifikasi unik untuk agen (ID aplikasi agenik).
auth Konteks otorisasi untuk pengguna.
context Percakapan saat ini mengubah konteks dari Agen SDK. Menyediakan identitas pengguna, metadata percakapan, dan konteks autentikasi untuk pendaftaran alat yang aman.
auth_token (Opsional) Token pembawa untuk skenario autentikasi nonagentik.

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 ini add_tool_servers_to_agent secara otomatis:

  • Memuat semua server MCP dari ToolingManifest.json
  • Mendaftarkan alat mereka dengan agen OpenAI
  • Menyiapkan autentikasi berdasarkan konfigurasi manifes
  • Membuat alat tersedia untuk dipanggil agen Anda

Untuk contoh kerja lengkap, lihat repositori Sampel Agen 365.

Uji dan Pantau:

Menguji agen

Setelah mengintegrasikan alat MCP ke agen Anda, uji pemanggilan alat untuk memastikan alat berfungsi dengan benar dan menangani skenario yang berbeda. Ikuti panduan pengujian untuk menyiapkan lingkungan Anda, lalu fokus terutama pada bagian Pemanggilan alat pengujian untuk memvalidasi alat MCP Anda berfungsi seperti yang diharapkan.

Menambahkan pengamatan

Tambahkan pengamatan ke agen Anda untuk memantau dan melacak pemanggilan alat MCP agen Anda, menambahkan kemampuan pengamatan untuk melacak performa, masalah debug, dan memahami pola penggunaan alat. Pelajari selengkapnya tentang menerapkan pelacakan dan pemantauan

  • Last updated on