Freigeben über

Verwenden von MCP-Tools mit Agents

Das Modellkontextprotokoll ist ein offener Standard, der definiert, wie Anwendungen Tools und Kontextdaten für große Sprachmodelle (LLMs) bereitstellen. Sie ermöglicht eine konsistente, skalierbare Integration externer Tools in Modellworkflows.

Microsoft Agent Framework unterstützt die Integration mit MCP-Servern (Model Context Protocol), sodass Ihre Agents auf externe Tools und Dienste zugreifen können. In diesem Handbuch wird gezeigt, wie Sie eine Verbindung mit einem MCP-Server herstellen und dessen Tools innerhalb Ihres Agents verwenden.

Überlegungen zur Verwendung von MCP-Servern von Drittanbietern

Ihre Verwendung von Modellkontextprotokollservern unterliegt den Bedingungen zwischen Ihnen und dem Dienstanbieter. Wenn Sie eine Verbindung mit einem Nicht-Microsoft-Dienst herstellen, werden einige Ihrer Daten (z. B. Aufforderungsinhalte) an den Nicht-Microsoft-Dienst übergeben, oder Ihre Anwendung empfängt möglicherweise Daten vom Nicht-Microsoft-Dienst. Sie sind für Ihre Nutzung von Nicht-Microsoft-Diensten und -Daten sowie für alle Gebühren verantwortlich, die dieser Nutzung zugeordnet sind.

Die mcP-Remoteserver, die Sie mit dem in diesem Artikel beschriebenen MCP-Tool verwenden, wurden von Drittanbietern erstellt, nicht von Microsoft. Microsoft hat diese Server nicht getestet oder überprüft. Microsoft hat keine Verantwortung für Sie oder andere In Bezug auf Ihre Nutzung von Remote-MCP-Servern.

Es wird empfohlen, die MCP-Server, die Sie Ihren Agent Framework-basierten Anwendungen hinzufügen, sorgfältig zu überprüfen und nachzuverfolgen. Außerdem wird empfohlen, dass Sie sich auf Server verlassen, die von vertrauenswürdigen Dienstanbietern selbst und nicht von Proxys gehostet werden.

Mit dem MCP-Tool können Sie benutzerdefinierte Header wie Authentifizierungsschlüssel oder Schemas übergeben, die ein MCP-Remoteserver möglicherweise benötigt. Es wird empfohlen, alle Daten zu überprüfen, die für Remote-MCP-Server freigegeben sind, und dass Sie die Daten zu Prüfungszwecken protokollieren. Beachten Sie Nicht-Microsoft-Praktiken für die Aufbewahrung und den Speicherort von Daten.

Von Bedeutung

Sie können Kopfzeilen nur angeben, indem Sie sie bei jeder Ausführung in tool_resources einschließen. Auf diese Weise können Sie API-Schlüssel, OAuth-Zugriffstoken oder andere Anmeldeinformationen direkt in Ihrer Anforderung platzieren. Header-Informationen, die Sie übergeben, sind nur für die aktuelle Ausführung verfügbar und werden nicht gespeichert.

Weitere Informationen zur MCP-Sicherheit finden Sie unter:

Die .NET-Version von Agent Framework kann zusammen mit dem offiziellen MCP C#-SDK verwendet werden, damit Ihr Agent MCP-Tools aufrufen kann.

Das folgende Beispiel zeigt, wie Sie:

  1. Einrichten und MCP-Server
  2. Abrufen der Liste der verfügbaren Tools vom MCP-Server
  3. Konvertieren der MCP-Tools in AIFunction's, damit sie einem Agent hinzugefügt werden können
  4. Aufrufen der Tools von einem Agent mithilfe von Funktionsaufrufen

Einrichten eines MCP-Clients

Erstellen Sie zunächst einen MCP-Client, der eine Verbindung mit Ihrem gewünschten MCP-Server herstellt:

// Create an MCPClient for the GitHub server
await using var mcpClient = await McpClientFactory.CreateAsync(new StdioClientTransport(new()
{
    Name = "MCPServer",
    Command = "npx",
    Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
}));

In diesem Beispiel:

  • Name: Ein Anzeigename für Ihre MCP-Serververbindung
  • Befehl: Die ausführbare Datei zum Ausführen des MCP-Servers (hier mithilfe von npx zum Ausführen eines Node.js-Pakets)
  • Argumente: Befehlszeilenargumente, die an den MCP-Server übergeben werden

Abrufen verfügbarer Tools

Rufen Sie nach der Verbindung die Liste der tools ab, die vom MCP-Server verfügbar sind:

// Retrieve the list of tools available on the GitHub server
var mcpTools = await mcpClient.ListToolsAsync().ConfigureAwait(false);

Die ListToolsAsync() Methode gibt eine Sammlung von Tools zurück, die der MCP-Server verfügbar macht. Diese Tools werden automatisch in AITool-Objekte konvertiert, die von Ihrem Agent verwendet werden können.

Erstellen eines Agents mit MCP-Tools

Erstellen Sie Ihren Agent, und stellen Sie während der Initialisierung die MCP-Tools bereit:

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         instructions: "You answer questions related to GitHub repositories only.",
         tools: [.. mcpTools.Cast<AITool>()]);

Warnung

DefaultAzureCredential ist praktisch für die Entwicklung, erfordert aber sorgfältige Überlegungen in der Produktion. Berücksichtigen Sie in der Produktion die Verwendung bestimmter Anmeldeinformationen (z. B. ManagedIdentityCredential), um Latenzprobleme, unbeabsichtigte Anmeldeinformationen probingen und potenzielle Sicherheitsrisiken aus Fallbackmechanismen zu vermeiden.

Wichtige Punkte:

  • Anweisungen: Stellen Sie klare Anweisungen bereit, die den Funktionen Ihrer MCP-Tools entsprechen
  • Tools: Umwandeln der MCP-Tools in AITool Objekte und Verteilen in das Toolsarray
  • Der Agent hat automatisch Zugriff auf alle Tools, die vom MCP-Server bereitgestellt werden.

Den Agent verwenden

Nach der Konfiguration kann Ihr Agent die MCP-Tools automatisch verwenden, um Benutzeranforderungen zu erfüllen:

// Invoke the agent and output the text result
Console.WriteLine(await agent.RunAsync("Summarize the last four commits to the microsoft/semantic-kernel repository?"));

Der Agent führt folgende Aktionen aus:

  1. Analysieren der Anforderung des Benutzers
  2. Ermitteln, welche MCP-Tools erforderlich sind
  3. Aufrufen der entsprechenden Tools über den MCP-Server
  4. Synthetisieren der Ergebnisse in eine kohärente Antwort

Umgebungskonfiguration

Stellen Sie sicher, dass Sie die erforderlichen Umgebungsvariablen einrichten:

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ??
    throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

Ressourcenverwaltung

Immer ordnungsgemäß verwerfen MCP-Clientressourcen:

await using var mcpClient = await McpClientFactory.CreateAsync(...);

Die Verwendung await using stellt sicher, dass die MCP-Clientverbindung ordnungsgemäß geschlossen wird, wenn sie nicht mehr gültig ist.

Allgemeine MCP-Server

Beliebte MCP-Server umfassen:

  • @modelcontextprotocol/server-github: Zugreifen auf GitHub-Repositorys und -Daten
  • @modelcontextprotocol/server-filesystem: Dateisystemvorgänge
  • @modelcontextprotocol/server-sqlite: SQLite-Datenbankzugriff

Jeder Server bietet verschiedene Tools und Funktionen, die die Funktionalität Ihres Agents erweitern. Diese Integration ermöglicht Es Ihren Agents, nahtlos auf externe Daten und Dienste zuzugreifen und gleichzeitig die Sicherheits- und Standardisierungsvorteile des Modellkontextprotokolls aufrechtzuerhalten.

Der vollständige Quellcode und anweisungen zum Ausführen dieses Beispiels finden Sie unter https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Tipp

Vollständige Runnable-Beispiele finden Sie in den .NET-Beispielen .

Auf diese Weise können Ihre Agents nahtlos auf externe Tools und Dienste zugreifen.

MCP-Tooltypen

Das Agent Framework unterstützt drei Arten von MCP-Verbindungen:

MCPStdioTool - Lokale MCP-Server

Wird MCPStdioTool verwendet, um eine Verbindung mit MCP-Servern herzustellen, die als lokale Prozesse mit Standardeingabe/Ausgabe ausgeführt werden:

import asyncio
from agent_framework import Agent, MCPStdioTool
from agent_framework.openai import OpenAIChatClient

async def local_mcp_example():
    """Example using a local MCP server via stdio."""
    async with (
        MCPStdioTool(
            name="calculator",
            command="uvx",
            args=["mcp-server-calculator"]
        ) as mcp_server,
        Agent(
            chat_client=OpenAIChatClient(),
            name="MathAgent",
            instructions="You are a helpful math assistant that can solve calculations.",
        ) as agent,
    ):
        result = await agent.run(
            "What is 15 * 23 + 45?",
            tools=mcp_server
        )
        print(result)

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

MCPStreamableHTTPTool - HTTP/SSE MCP-Server

Wird MCPStreamableHTTPTool verwendet, um eine Verbindung mit MCP-Servern über HTTP mit Server-Sent-Ereignissen herzustellen:

import asyncio
from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def http_mcp_example():
    """Example using an HTTP-based MCP server."""
    async with (
        AzureCliCredential() as credential,
        MCPStreamableHTTPTool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
            headers={"Authorization": "Bearer your-token"},
        ) as mcp_server,
        Agent(
            chat_client=AzureAIAgentClient(async_credential=credential),
            name="DocsAgent",
            instructions="You help with Microsoft documentation questions.",
        ) as agent,
    ):
        result = await agent.run(
            "How to create an Azure storage account using az cli?",
            tools=mcp_server
        )
        print(result)

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

MCPWebsocketTool - WebSocket MCP-Server

Wird zum Herstellen einer Verbindung mit MCP-Servern über WebSocket-Verbindungen verwendet MCPWebsocketTool :

import asyncio
from agent_framework import Agent, MCPWebsocketTool
from agent_framework.openai import OpenAIChatClient

async def websocket_mcp_example():
    """Example using a WebSocket-based MCP server."""
    async with (
        MCPWebsocketTool(
            name="realtime-data",
            url="wss://api.example.com/mcp",
        ) as mcp_server,
        Agent(
            chat_client=OpenAIChatClient(),
            name="DataAgent",
            instructions="You provide real-time data insights.",
        ) as agent,
    ):
        result = await agent.run(
            "What is the current market status?",
            tools=mcp_server
        )
        print(result)

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

Allgemeine MCP-Server, die Sie mit Python Agent Framework verwenden können:

  • Rechner: uvx mcp-server-calculator - Mathematische Berechnungen
  • Dateisystem: uvx mcp-server-filesystem - Dateisystemvorgänge
  • GitHub: npx @modelcontextprotocol/server-github - GitHub-Repositoryzugriff
  • SQLite: uvx mcp-server-sqlite - Datenbankvorgänge

Jeder Server bietet verschiedene Tools und Funktionen, die die Funktionalität Ihres Agents erweitern und gleichzeitig die Sicherheits- und Standardisierungsvorteile des Modellkontextprotokolls beibehalten.

Vollständiges Beispiel

# Copyright (c) Microsoft. All rights reserved.

import os

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.openai import OpenAIResponsesClient
from httpx import AsyncClient

"""
MCP Authentication Example

This example demonstrates how to authenticate with MCP servers using API key headers.

For more authentication examples including OAuth 2.0 flows, see:
- https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/clients/simple-auth-client
- https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/servers/simple-auth
"""


async def api_key_auth_example() -> None:
    """Example of using API key authentication with MCP server."""
    # Configuration
    mcp_server_url = os.getenv("MCP_SERVER_URL", "your-mcp-server-url")
    api_key = os.getenv("MCP_API_KEY")

    # Create authentication headers
    # Common patterns:
    # - Bearer token: "Authorization": f"Bearer {api_key}"
    # - API key header: "X-API-Key": api_key
    # - Custom header: "Authorization": f"ApiKey {api_key}"
    auth_headers = {
        "Authorization": f"Bearer {api_key}",
    }

    # Create HTTP client with authentication headers
    http_client = AsyncClient(headers=auth_headers)

    # Create MCP tool with the configured HTTP client
    async with (
        MCPStreamableHTTPTool(
            name="MCP tool",
            description="MCP tool description",
            url=mcp_server_url,
            http_client=http_client,  # Pass HTTP client with authentication headers
        ) as mcp_tool,
        Agent(
            client=OpenAIResponsesClient(),
            name="Agent",
            instructions="You are a helpful assistant.",
            tools=mcp_tool,
        ) as agent,
    ):
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Agent: {result.text}")

Verfügbarmachen eines Agents als MCP-Server

Sie können einen Agent als MCP-Server verfügbar machen, sodass er von jedem MCP-kompatiblen Client (z. B. VS Code GitHub Copilot Agents oder anderen Agents) als Tool verwendet werden kann. Der Name und die Beschreibung des Agents werden zu den MCP-Servermetadaten.

Schließen Sie den Agent in ein Funktionstool ein .AsAIFunction(), erstellen Sie einen McpServerTool, und registrieren Sie ihn mit einem MCP-Server:

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Server;

// Create the agent
AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

// Convert the agent to an MCP tool
McpServerTool tool = McpServerTool.Create(agent.AsAIFunction());

// Set up the MCP server over stdio
HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(settings: null);
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithTools([tool]);

await builder.Build().RunAsync();

Installieren Sie die erforderlichen NuGet-Pakete:

dotnet add package Microsoft.Extensions.Hosting --prerelease
dotnet add package ModelContextProtocol --prerelease

Rufen Sie .as_mcp_server() einen Agent auf, um ihn als MCP-Server verfügbar zu machen:

from agent_framework.openai import OpenAIResponsesClient
from typing import Annotated

def get_specials() -> Annotated[str, "Returns the specials from the menu."]:
    return "Special Soup: Clam Chowder, Special Salad: Cobb Salad"

# Create an agent with tools
agent = OpenAIResponsesClient().as_agent(
    name="RestaurantAgent",
    description="Answer questions about the menu.",
    tools=[get_specials],
)

# Expose the agent as an MCP server
server = agent.as_mcp_server()

Richten Sie den MCP-Server ein, um die Standardeingabe/Ausgabe zu überwachen:

import anyio
from mcp.server.stdio import stdio_server

async def run():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, server.create_initialization_options())

if __name__ == "__main__":
    anyio.run(run)

Nächste Schritte

Verwenden von Workflows als Agents

  • Last updated on