Použití hostovaných nástrojů MCP s agenty

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 s hostovaným serverem MCP (Model Context Protocol). Agent může využívat nástroje MCP spravované a spouštěné backingovou službou AI, 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 }
        }));

Warning

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

Tip

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.

Tip

Nástroje MCP lze také sbalit do Microsoft konfigurace sady nástrojů Foundry – pojmenované kolekce hostovaných nástrojů na straně serveru. Pokyny k používání spravovaného agenta a pokyny k používání MCP najdete v Microsoft Panelu nástrojů Foundry.

Kompletní příklad

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

Hostované nástroje MCP

Balíček hostedtool poskytuje typy značek pro hostované nástroje. Tyto nástroje se nespouštějí místně – informují službu AI, že je povoleno volat nakonfigurovaný server MCP na straně služby. V Go použijte hostované nástroje MCP s rozhraním API pro odpovědi OpenAI prostřednictvím openaiprovider.NewResponsesAgent.

Nastavení prostředí

Nakonfigurujte koncový bod modelu a serveru MCP prostřednictvím proměnných prostředí:

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"
}

Základní integrace 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()

Ověřené servery MCP

Pro servery MCP, které vyžadují ověřování, nastavte Authorization nebo zadejte hlavičky. Načtěte tajné kódy z úložiště tajných kódů nebo prostředí vaší aplikace a vyhněte se jejich kontrole ve správě zdrojového kódu.

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

Několik serverů MCP

Zadejte několik deklarací serveru MCP hostovaných v případě, že by měl být model schopný zvolit mezi různými vzdálenými sadami nástrojů:

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,
    },
})

Poznámka:

Hostované nástroje MCP vyžadují poskytovatele, který je podporuje, například rozhraní API pro odpovědi OpenAI prostřednictvím openaiprovider.NewResponsesAgent.

Další kroky

Místní nástroje MCP

  • Last updated on