Bagikan melalui

Menggunakan alat MCP dengan Agen Foundry

Anda dapat memperluas kemampuan agen Azure AI Foundry Anda dengan menyambungkannya ke alat yang dihosting di server Protokol Konteks Model Jarak Jauh (MCP) (bawa titik akhir server MCP Anda sendiri).

Cara menggunakan alat Protokol Konteks Model

Bagian ini menjelaskan cara membuat agen AI menggunakan Azure Foundry (Azure AI) dengan integrasi server Model Context Protocol (MCP) yang dihosting. Agen dapat menggunakan alat MCP yang dikelola dan dijalankan oleh layanan Azure Foundry, memungkinkan akses yang aman dan terkontrol ke sumber daya eksternal.

Fitur Utama

  • Server MCP yang dihosting: Server MCP dihosting dan dikelola oleh Azure AI Foundry, menghilangkan kebutuhan untuk mengelola infrastruktur server
  • Agen Persisten: Agen dibuat dan disimpan sisi server, memungkinkan percakapan stateful
  • Alur Kerja Persetujuan Alat: Mekanisme persetujuan yang dapat dikonfigurasi untuk pemanggilan alat MCP

Cara Kerjanya

1. Penyiapan Lingkungan

Sampel memerlukan dua variabel lingkungan:

  • AZURE_FOUNDRY_PROJECT_ENDPOINT: URL titik akhir proyek Azure AI Foundry Anda
  • AZURE_FOUNDRY_PROJECT_MODEL_ID: Nama penyebaran model (default ke "gpt-4.1-mini")
var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") 
    ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_MODEL_ID") ?? "gpt-4.1-mini";

2. Konfigurasi Agen

Agen dikonfigurasi dengan instruksi dan metadata tertentu:

const string AgentName = "MicrosoftLearnAgent";
const string AgentInstructions = "You answer questions by searching the Microsoft Learn content only.";

Ini membuat agen khusus untuk menjawab pertanyaan menggunakan dokumentasi Microsoft Learn.

3. Definisi Alat MCP

Sampel membuat definisi alat MCP yang menunjuk ke server MCP yang dihosting:

var mcpTool = new MCPToolDefinition(
    serverLabel: "microsoft_learn",
    serverUrl: "https://learn.microsoft.com/api/mcp");
mcpTool.AllowedTools.Add("microsoft_docs_search");

Komponen Utama:

  • serverLabel: Pengidentifikasi unik untuk instans server MCP
  • serverUrl: URL server MCP yang dihosting
  • AllowedTools: Menentukan alat mana dari server MCP yang dapat digunakan agen

4. Pembuatan Agen Persisten

Agen dibuat sisi server menggunakan Azure AI Foundry Persistent Agents SDK:

var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());

var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: model,
    name: AgentName,
    instructions: AgentInstructions,
    tools: [mcpTool]);

Ini membuat agen persisten yang:

  • Berada di layanan Azure AI Foundry
  • Memiliki akses ke alat MCP yang ditentukan
  • Dapat mempertahankan status percakapan di beberapa interaksi

5. Pengambilan dan Eksekusi Agen

Agen yang dibuat diambil sebagai AIAgent instans:

AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

6. Konfigurasi Sumber Daya Alat

Sampel mengonfigurasi sumber daya alat dengan pengaturan persetujuan:

var runOptions = new ChatClientAgentRunOptions()
{
    ChatOptions = new()
    {
        RawRepresentationFactory = (_) => new ThreadAndRunOptions()
        {
            ToolResources = new MCPToolResource(serverLabel: "microsoft_learn")
            {
                RequireApproval = new MCPApproval("never"),
            }.ToToolResources()
        }
    }
};

Konfigurasi Kunci:

  • MCPToolResource: Menautkan instans server MCP ke eksekusi agen
  • RequireApproval: Kontrol saat persetujuan pengguna diperlukan untuk pemanggilan alat
    • "never": Alat dijalankan secara otomatis tanpa persetujuan
    • "always": Semua pemanggilan alat memerlukan persetujuan pengguna
    • Aturan persetujuan kustom juga dapat dikonfigurasi

7. Eksekusi Agen

Agen dipanggil dengan pertanyaan dan dijalankan menggunakan alat MCP yang dikonfigurasi:

AgentSession session = await agent.GetNewSessionAsync();
var response = await agent.RunAsync(
    "Please summarize the Azure AI Agent documentation related to MCP Tool calling?", 
    session, 
    runOptions);
Console.WriteLine(response);

8. Pembersihan

Sampel menunjukkan pembersihan sumber daya yang tepat:

await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);

Integrasi MCP Python Azure AI Foundry

Azure AI Foundry menyediakan integrasi yang mulus dengan server Model Context Protocol (MCP) melalui Python Agent Framework. Layanan ini mengelola hosting dan eksekusi server MCP, menghilangkan manajemen infrastruktur sambil menyediakan akses yang aman dan terkontrol ke alat eksternal.

Penyiapan Lingkungan

Konfigurasikan kredensial proyek Azure AI Foundry Anda melalui variabel lingkungan:

import os
from azure.identity.aio import AzureCliCredential
from agent_framework.azure import AzureAIAgentClient

# Required environment variables
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = "https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"] = "gpt-4o-mini"  # Optional, defaults to this

Integrasi MCP Dasar

Buat agen Azure AI Foundry dengan alat MCP yang dihosting:

import asyncio
from agent_framework import HostedMCPTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def basic_foundry_mcp_example():
    """Basic example of Azure AI Foundry agent with hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as chat_client,
    ):
        # Enable Azure AI observability (optional but recommended)
        await chat_client.setup_azure_ai_observability()

        # Create agent with hosted MCP tool
        agent = chat_client.as_agent(
            name="MicrosoftLearnAgent", 
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=HostedMCPTool(
                name="Microsoft Learn MCP",
                url="https://learn.microsoft.com/api/mcp",
            ),
        )

        # Simple query without approval workflow
        result = await agent.run(
            "Please summarize the Azure AI Agent documentation related to MCP tool calling?"
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(basic_foundry_mcp_example())

Konfigurasi MCP Multi-Alat

Gunakan beberapa alat MCP yang dihosting dengan satu agen:

async def multi_tool_mcp_example():
    """Example using multiple hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as chat_client,
    ):
        await chat_client.setup_azure_ai_observability()

        # Create agent with multiple MCP tools
        agent = chat_client.as_agent(
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[
                HostedMCPTool(
                    name="Microsoft Learn MCP",
                    url="https://learn.microsoft.com/api/mcp",
                    approval_mode="never_require",  # Auto-approve documentation searches
                ),
                HostedMCPTool(
                    name="GitHub MCP", 
                    url="https://api.github.com/mcp",
                    approval_mode="always_require",  # Require approval for GitHub operations
                    headers={"Authorization": "Bearer github-token"},
                ),
            ],
        )

        result = await agent.run(
            "Find Azure documentation and also check the latest commits in microsoft/semantic-kernel"
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(multi_tool_mcp_example())

Python Agent Framework menyediakan integrasi yang mulus dengan kemampuan MCP yang dihosting Azure AI Foundry, memungkinkan akses yang aman dan dapat diskalakan ke alat eksternal sambil mempertahankan fleksibilitas dan kontrol yang diperlukan untuk aplikasi produksi.

Langkah selanjutnya

Menggunakan alur kerja sebagai Agen

  • Last updated on