استخدام أدوات MCP المستضافة مع الوكلاء

يمكنك توسيع قدرات عامل Microsoft Foundry الخاص بك عن طريق توصيله بالأدوات المستضافة على خوادم بروتوكول سياق النموذج البعيد (MCP) (إحضار نقطة نهاية خادم MCP الخاص بك).

كيفية استخدام أداة بروتوكول سياق النموذج

يشرح هذا القسم كيفية إنشاء عامل مع تكامل خادم بروتوكول سياق النموذج المستضاف (MCP). يمكن للعامل استخدام أدوات MCP التي تتم إدارتها وتنفيذها بواسطة خدمة الذكاء الاصطناعي المدعومة، ما يسمح بالوصول الآمن والمتحكم فيه إلى الموارد الخارجية.

الميزات الأساسية

• خادم MCP المستضاف: تتم استضافة خادم MCP وإدارته بواسطة Foundry، مما يلغي الحاجة إلى إدارة البنية الأساسية للخادم
• العوامل الدائمة: يتم إنشاء العوامل وتخزينها من جانب الخادم، ما يسمح بإجراء محادثات ذات حالة
• سير عمل الموافقة على الأداة: آليات الموافقة القابلة للتكوين لادعاءات أداة MCP

كيفية عملها

1. إعداد البيئة

يتطلب النموذج متغيرين للبيئة:

• AZURE_FOUNDRY_PROJECT_ENDPOINT: رابط نقطة نهاية مشروع Foundry الخاص بك
• AZURE_FOUNDRY_PROJECT_MODEL_ID: اسم توزيع النموذج (افتراضيا إلى "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. تكوين العامل

يتم تكوين العامل مع إرشادات وبيانات تعريف محددة:

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

يؤدي هذا إلى إنشاء وكيل متخصص للإجابة عن الأسئلة باستخدام وثائق Microsoft Learn.

3. تعريف أداة MCP

ينشئ النموذج تعريف أداة MCP الذي يشير إلى خادم MCP مستضاف:

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

المكونات الرئيسية:

• serverLabel: معرف فريد لمثيل خادم MCP
• serverUrl: عنوان URL لخادم MCP المستضاف
• AllowedTools: يحدد الأدوات من خادم MCP الذي يمكن للعامل استخدامه

4. إنشاء عامل

يتم إنشاء العامل من جانب الخادم باستخدام Azure AI Projects SDK:

var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

var agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    AgentName,
    new ProjectsAgentVersionCreationOptions(
        new DeclarativeAgentDefinition(model)
        {
            Instructions = AgentInstructions,
            Tools = { mcpTool }
        }));

تحذير

DefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد محددة (على سبيل المثال، ManagedIdentityCredential) لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

يؤدي هذا إلى إنشاء عامل تم إصداره:

• يعيش على خدمة Foundry
• لديه حق الوصول إلى أدوات MCP المحددة
• يمكنه الحفاظ على حالة المحادثة عبر تفاعلات متعددة

5. استرداد العامل وتنفيذه

يتم استرداد العامل الذي تم إنشاؤه كمثيل AIAgent :

AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

6. تكوين مورد الأداة

يقوم النموذج بتكوين موارد الأدوات مع إعدادات الموافقة:

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

تكوين المفتاح:

• MCPToolResource: يربط مثيل خادم MCP بتنفيذ العامل
• RequireApproval: عناصر التحكم عند الحاجة إلى موافقة المستخدم على استدعاءات الأدوات
  • "never": يتم تنفيذ الأدوات تلقائيا دون موافقة
  • "always": تتطلب جميع استدعاءات الأدوات موافقة المستخدم
  • يمكن أيضا تكوين قواعد الموافقة المخصصة

7. تنفيذ العامل

يتم استدعاء العامل بسؤال وينفذ باستخدام أدوات MCP المكونة:

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

8. التنظيف

يوضح النموذج تنظيف الموارد المناسب:

await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(agent.Id);

Tip

راجع نموذج MCP المستضاف لعامل .NET Foundry للحصول على مثال كامل قابل للتشغيل.

يوفر Foundry تكاملا سلسا مع خوادم بروتوكول سياق النموذج (MCP) من خلال إطار عمل عامل Python. تدير الخدمة استضافة خادم MCP وتنفيذه، مما يلغي إدارة البنية الأساسية مع توفير وصول آمن ومتحكم فيه إلى الأدوات الخارجية.

إعداد البيئة

تكوين بيانات اعتماد مشروع Foundry من خلال متغيرات البيئة:

import os
from azure.identity.aio import AzureCliCredential
from agent_framework.foundry import FoundryChatClient

# Required environment variables
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = "https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
os.environ["FOUNDRY_MODEL"] = "gpt-4o-mini"

تكامل MCP الأساسي

إنشاء عامل Foundry باستخدام أدوات MCP المستضافة:

import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async def basic_foundry_mcp_example():
    """Basic example of Foundry agent with hosted MCP tools."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        # Create a hosted MCP tool using the client method
        learn_mcp = client.get_mcp_tool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
        )

        # Create agent with hosted MCP tool
        async with Agent(
            client=client,
            name="MicrosoftLearnAgent",
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=[learn_mcp],
        ) as agent:
            # Simple query without approval workflow
            result = await agent.run(
                "Please summarize the Azure AI Agent documentation related to MCP tool calling?"
            )
            print(result.text)

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

تكوين MCP متعدد الأدوات

استخدم أدوات MCP متعددة مستضافة مع عامل واحد:

async def multi_tool_mcp_example():
    """Example using multiple hosted MCP tools."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        # Create multiple MCP tools using the client method
        learn_mcp = client.get_mcp_tool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
            approval_mode="never_require",  # Auto-approve documentation searches
        )
        github_mcp = client.get_mcp_tool(
            name="GitHub MCP",
            url="https://api.githubcopilot.com/mcp/",
            approval_mode="always_require",  # Require approval for GitHub operations
            headers={"Authorization": "Bearer github-token"},
        )

        # Create agent with multiple MCP tools
        async with Agent(
            client=client,
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[learn_mcp, github_mcp],
        ) as agent:
            result = await agent.run(
                "Find Azure documentation and also check the latest commits in microsoft/semantic-kernel"
            )
            print(result.text)

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

يوفر إطار عمل عامل Python تكاملا سلسا مع قدرات MCP المستضافة من Foundry، ما يتيح الوصول الآمن والقابل للتطوير إلى الأدوات الخارجية مع الحفاظ على المرونة والتحكم اللازمين لتطبيقات الإنتاج.

Tip

يمكن أيضا تجميع أدوات MCP في تكوينات مربع أدوات Microsoft Foundry — المجموعات المسماة من جانب الخادم التي تم إصدارها من الأدوات المستضافة. راجع Microsoft Foundry Toolbox للحصول على مرفق عامل مدار وإرشادات استهلاك MCP.

مثال كامل

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from dotenv import load_dotenv

"""
MCP GitHub Integration with Personal Access Token (PAT)

This example demonstrates how to connect to GitHub's remote MCP server using a Personal Access
Token (PAT) for authentication. The agent can use GitHub operations like searching repositories,
reading files, creating issues, and more depending on how you scope your token.

Prerequisites:
1. A GitHub Personal Access Token with appropriate scopes
   - Create one at: https://github.com/settings/tokens
   - For read-only operations, you can use more restrictive scopes
2. Environment variables:
   - GITHUB_PAT: Your GitHub Personal Access Token (required)
   - OPENAI_API_KEY: Your OpenAI API key (required)
   - OPENAI_MODEL: Your OpenAI model ID (required)
"""


async def github_mcp_example() -> None:
    """Example of using GitHub MCP server with PAT authentication."""
    # 1. Load environment variables from .env file if present
    load_dotenv()

    # 2. Get configuration from environment
    github_pat = os.getenv("GITHUB_PAT")
    if not github_pat:
        raise ValueError(
            "GITHUB_PAT environment variable must be set. Create a token at https://github.com/settings/tokens"
        )

    # 3. Create authentication headers with GitHub PAT
    auth_headers = {
        "Authorization": f"Bearer {github_pat}",
    }

    # 4. Create agent with the GitHub MCP tool using instance method
    # The MCP tool manages the connection to the MCP server and makes its tools available
    # Set approval_mode="never_require" to allow the MCP tool to execute without approval
    client = OpenAIChatClient()
    # This hosted MCP tool is executed remotely by OpenAI, not locally by your application.
    github_mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        headers=auth_headers,
        approval_mode="never_require",
    )

    # 5. Create agent with the GitHub MCP tool
    async with Agent(
        client=client,
        name="GitHubAgent",
        instructions=(
            "You are a helpful assistant that can help users interact with GitHub. "
            "You can search for repositories, read file contents, check issues, and more. "
            "Always be clear about what operations you're performing."
        ),
        tools=github_mcp_tool,
    ) as agent:
        # Example 1: Get authenticated user information
        query1 = "What is my GitHub username and tell me about my account?"
        print(f"\nUser: {query1}")
        result1 = await agent.run(query1)
        print(f"Agent: {result1.text}")

        # Example 2: List my repositories
        query2 = "List all the repositories I own on GitHub"
        print(f"\nUser: {query2}")
        result2 = await agent.run(query2)
        print(f"Agent: {result2.text}")


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

أدوات MCP المستضافة

hostedtool توفر الحزمة أنواع علامات للأدوات المستضافة. لا يتم تنفيذ هذه الأدوات محليا - فهي تعلم خدمة الذكاء الاصطناعي بأنه مسموح لها باستدعاء خادم MCP المكون على جانب الخدمة. في Go، استخدم أدوات MCP المستضافة مع واجهة برمجة تطبيقات استجابات OpenAI من خلال openaiprovider.NewResponsesAgent.

إعداد البيئة

تكوين النموذج ونقطة نهاية خادم MCP من خلال متغيرات البيئة:

endpoint := os.Getenv("MCP_SERVER_URL")
if endpoint == "" {
    endpoint = "https://learn.microsoft.com/api/mcp"
}

deployment := os.Getenv("OPENAI_RESPONSES_MODEL")
if deployment == "" {
    deployment = "gpt-4o-mini"
}

تكامل MCP الأساسي

import (
    "os"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/openaiprovider"
    "github.com/microsoft/agent-framework-go/tool"
    "github.com/microsoft/agent-framework-go/tool/hostedtool"
)

mcpTool := &hostedtool.MCPServer{
    ServerName:        "microsoft_learn",
    ServerDescription: "Search Microsoft Learn documentation.",
    ServerAddress:     endpoint,
    AllowedTools:      []string{"microsoft_docs_search"},
}

a := openaiprovider.NewResponsesAgent(client, openaiprovider.AgentConfig{
    Model:        deployment,
    Instructions: "You answer questions by searching Microsoft Learn content only.",
    Config: agent.Config{
        Name:  "MicrosoftLearnAgent",
        Tools: []tool.Tool{mcpTool},
    },
})

resp, err := a.RunText(ctx, "Summarize the Azure AI Agent documentation for MCP tool calling.").Collect()

خوادم MCP المصادق عليها

بالنسبة لخوادم MCP التي تتطلب مصادقة، قم بتعيين Authorization الرؤوس أو توفيرها. قم بتحميل البيانات السرية من المخزن السري أو البيئة الخاصة بالتطبيق الخاص بك، وتجنب التحقق منها في التحكم بالمصادر.

githubMCPTool := &hostedtool.MCPServer{
    ServerName:    "github",
    ServerAddress: "https://api.githubcopilot.com/mcp/",
    Authorization: "Bearer " + os.Getenv("GITHUB_PAT"),
}

خوادم MCP متعددة

توفير العديد من إعلانات خادم MCP المستضافة عندما يجب أن يكون النموذج قادرا على الاختيار بين مجموعات الأدوات البعيدة المختلفة:

tools := []tool.Tool{
    &hostedtool.MCPServer{
        ServerName:    "microsoft_learn",
        ServerAddress: "https://learn.microsoft.com/api/mcp",
        AllowedTools:  []string{"microsoft_docs_search"},
    },
    &hostedtool.MCPServer{
        ServerName:    "github",
        ServerAddress: "https://api.githubcopilot.com/mcp/",
        Authorization: "Bearer " + os.Getenv("GITHUB_PAT"),
    },
}

a := openaiprovider.NewResponsesAgent(client, openaiprovider.AgentConfig{
    Model:        deployment,
    Instructions: "You can search Microsoft documentation and GitHub repositories.",
    Config: agent.Config{
        Name:  "MultiToolAgent",
        Tools: tools,
    },
})

Note

تتطلب أدوات MCP المستضافة موفرا يدعمها، مثل واجهة برمجة تطبيقات استجابات OpenAI من خلال openaiprovider.NewResponsesAgent.

الخطوات التالية

أدوات MCP المحلية