Condividi tramite

Uso degli strumenti MCP con gli agenti

Microsoft Agent Framework supporta l'integrazione con i server MCP (Model Context Protocol), consentendo agli agenti di accedere a strumenti e servizi esterni. Questa guida illustra come connettersi a un server MCP e usare i relativi strumenti all'interno dell'agente.

La versione .Net di Agent Framework può essere usata insieme all'SDK C# MCP ufficiale per consentire all'agente di chiamare gli strumenti MCP.

L'esempio seguente illustra come:

  1. Configurare e server MCP
  2. Recuperare l'elenco degli strumenti disponibili dal server MCP
  3. Convertire gli strumenti MCP in AIFunctionin modo che possano essere aggiunti a un agente
  4. Richiamare gli strumenti da un agente usando la chiamata di funzione

Configurazione di un client MCP

Creare prima di tutto un client MCP che si connette al server MCP desiderato:

// 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 questo esempio:

  • Nome: nome descrittivo per la connessione al server MCP
  • Comando: eseguibile per eseguire il server MCP (in questo caso usando npx per eseguire un pacchetto di Node.js)
  • Argomenti: argomenti della riga di comando passati al server MCP

Recupero degli strumenti disponibili

Dopo la connessione, recuperare l'elenco degli strumenti disponibili dal server MCP:

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

Il ListToolsAsync() metodo restituisce una raccolta di strumenti esposti dal server MCP. Questi strumenti vengono convertiti automaticamente in oggetti AITool che possono essere usati dall'agente.

Creazione di un agente con strumenti MCP

Creare l'agente e fornire gli strumenti MCP durante l'inizializzazione:

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

Punti chiave:

  • Istruzioni: fornire istruzioni chiare che si allineano alle funzionalità degli strumenti MCP
  • Strumenti: eseguire il cast degli strumenti MCP agli AITool oggetti e distribuirli nella matrice di strumenti
  • L'agente avrà automaticamente accesso a tutti gli strumenti forniti dal server MCP

Uso dell'agente

Dopo la configurazione, l'agente può usare automaticamente gli strumenti MCP per soddisfare le richieste degli utenti:

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

L'agente:

  1. Analizzare la richiesta dell'utente
  2. Determinare quali strumenti MCP sono necessari
  3. Chiamare gli strumenti appropriati tramite il server MCP
  4. Sintetizzare i risultati in una risposta coerente

Configurazione dell'ambiente

Assicurarsi di configurare le variabili di ambiente necessarie:

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

Gestione risorse

Eliminare sempre correttamente le risorse client MCP:

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

L'uso await using garantisce che la connessione client MCP venga chiusa correttamente quando esce dall'ambito.

Server MCP comuni

I server MCP più diffusi includono:

  • @modelcontextprotocol/server-github: accedere a repository e dati GitHub
  • @modelcontextprotocol/server-filesystem: operazioni del file system
  • @modelcontextprotocol/server-sqlite: accesso al database SQLite

Ogni server offre diversi strumenti e funzionalità che estendono le funzionalità dell'agente. Questa integrazione consente agli agenti di accedere facilmente a dati e servizi esterni mantenendo al tempo stesso i vantaggi di sicurezza e standardizzazione del protocollo di contesto del modello.

Il codice sorgente completo e le istruzioni per eseguire questo esempio sono disponibili qui.

Python Agent Framework offre supporto completo per l'integrazione con i server MCP (Model Context Protocol) tramite più tipi di connessione. In questo modo gli agenti possono accedere facilmente a strumenti e servizi esterni.

Tipi di strumenti MCP

Agent Framework supporta tre tipi di connessioni MCP:

MCPStdioTool - Server MCP locali

Usare MCPStdioTool per connettersi ai server MCP eseguiti come processi locali usando input/output standard:

import asyncio
from agent_framework import ChatAgent, 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,
        ChatAgent(
            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 - Server MCP HTTP/SSE

Usare MCPStreamableHTTPTool per connettersi ai server MCP tramite HTTP con eventi Server-Sent:

import asyncio
from agent_framework import ChatAgent, 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,
        ChatAgent(
            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 - Server MCP WebSocket

Usare MCPWebsocketTool per connettersi ai server MCP tramite connessioni WebSocket:

import asyncio
from agent_framework import ChatAgent, 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,
        ChatAgent(
            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())

Server MCP comuni che è possibile usare con Python Agent Framework:

  • Calcolatrice: uvx mcp-server-calculator - Calcoli matematici
  • File system: uvx mcp-server-filesystem - Operazioni del file system
  • GitHub: npx @modelcontextprotocol/server-github - Accesso al repository GitHub
  • SQLite: uvx mcp-server-sqlite - Operazioni di database

Ogni server offre diversi strumenti e funzionalità che estendono le funzionalità dell'agente mantenendo al tempo stesso i vantaggi di sicurezza e standardizzazione del protocollo di contesto del modello.

Passaggi successivi

Uso dei flussi di lavoro come agenti

  • Last updated on