Použití nástrojů MCP s agenty Foundry

Možnosti agenta Microsoft Foundry můžete rozšířit připojením k nástrojům hostovaným na vzdálených serverech MCP (Model Context Protocol) (přineste si vlastní koncový bod serveru MCP).

Jak používat nástroj Model Context Protocol

Tato část vysvětluje, jak vytvořit agenta Pythonu založeného na Microsoft Foundry s integrací serveru MCP (Model Context Protocol). Agent může využívat nástroje MCP spravované a spouštěné službou Foundry, což umožňuje zabezpečený a řízený přístup k externím prostředkům.

Klíčové funkce

  • Hostovaný server MCP: Server MCP je hostovaný a spravovaný službou Foundry a eliminuje potřebu správy serverové infrastruktury.
  • Trvalí agenti: Agenti se vytvářejí a ukládají na straně serveru, což umožňuje stavové konverzace.
  • Pracovní postup schválení nástrojů: Konfigurovatelné schvalovací mechanismy pro vyvolání nástrojů MCP

Jak to funguje

1. Nastavení prostředí

Ukázka vyžaduje dvě proměnné prostředí:

  • AZURE_FOUNDRY_PROJECT_ENDPOINT: Adresa URL koncového bodu projektu Foundry
  • AZURE_FOUNDRY_PROJECT_MODEL_ID: Název nasazení modelu (výchozí hodnota je 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. Konfigurace agenta

Agent je nakonfigurovaný s konkrétními pokyny a metadaty:

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

Tím se vytvoří agent specializující se na odpovědi na otázky pomocí dokumentace k Microsoft Learn.

3. Definice nástroje MCP

Ukázka vytvoří definici nástroje MCP, která odkazuje na hostovaný server MCP:

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

Klíčové komponenty:

  • serverLabel: Jedinečný identifikátor instance serveru MCP
  • serverUrl: Adresa URL hostovaného serveru MCP
  • AllowedTools: Určuje nástroje ze serveru MCP, které může agent používat.

4. Vytvoření agenta

Agent se vytvoří na straně serveru pomocí sady 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 }
        }));

Výstraha

DefaultAzureCredential je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Tím se vytvoří agent s verzí, který:

  • Žije ve službě Foundry
  • Má přístup k zadaným nástrojům MCP.
  • Může udržovat stav konverzace napříč několika interakcemi.

5. Načítání a spouštění agenta

Vytvořený agent se načte jako AIAgent instance:

AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

6. Konfigurace prostředků nástroje

Ukázka konfiguruje prostředky nástrojů s nastavením schválení:

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

Konfigurace klíče:

  • MCPToolResource: Propojí instanci serveru MCP se spuštěním agenta.
  • RequireApproval: Určuje, kdy je potřeba schválení uživatele pro vyvolání nástrojů.
    • "never": Nástroje se spouštějí automaticky bez schválení.
    • "always": Všechna vyvolání nástrojů vyžadují schválení uživatelem.
    • Můžete také nakonfigurovat vlastní pravidla schválení.

7. Provádění agenta

Agent se vyvolá s otázkou a spustí se pomocí nakonfigurovaných nástrojů 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. Vyčištění

Ukázka ukazuje správné vyčištění prostředků:

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

Návod

Kompletní runnable příklad najdete v ukázce mcp hostovaného agenta .NET Foundry .

Foundry poskytuje bezproblémovou integraci se servery MCP (Model Context Protocol) prostřednictvím architektury agenta Pythonu. Služba spravuje hostování a spouštění serveru MCP a eliminuje správu infrastruktury a zajišťuje zabezpečený a řízený přístup k externím nástrojům.

Nastavení prostředí

Nakonfigurujte přihlašovací údaje projektu Foundry prostřednictvím proměnných prostředí:

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"

Základní integrace MCP

Vytvořte agenta Foundry s hostovanými nástroji 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())

Konfigurace MCP s více nástroji

Použití několika hostovaných nástrojů MCP s jedním agentem:

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

Architektura agenta Pythonu poskytuje bezproblémovou integraci s hostovanými možnostmi MCP v Foundry, která umožňuje zabezpečený a škálovatelný přístup k externím nástrojům a současně zachovává flexibilitu a kontrolu potřebnou pro produkční aplikace.

Návod

Nástroje MCP lze také sbalit do sad nástrojů Foundry – pojmenované kolekce hostovaných nástrojů na straně serveru. Sady nástrojů umožňují spravovat konfiguraci nástrojů jednou a opakovaně ji používat napříč agenty. Podrobnosti o načítání nástrojů a cest ke spotřebě MCP najdete na stránce zprostředkovatele Microsoft Foundry .

Kompletní příklad

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
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)
   - FOUNDRY_PROJECT_ENDPOINT: Your Foundry project endpoint (required)
   - FOUNDRY_MODEL: Your Foundry model deployment name (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 = FoundryChatClient(credential=AzureCliCredential())
    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())

Další kroky

Místní nástroje MCP

  • Last updated on