Usando ferramentas mcp com agentes

A versão do .Net do Agent Framework pode ser usada junto com o SDK oficial do MCP C# para permitir que seu agente chame ferramentas MCP.

O exemplo a seguir mostra como:

1. Configurar e servidor MCP
2. Recuperar a lista de ferramentas disponíveis do servidor MCP
3. Converter as ferramentas MCP em 's para AIFunctionque elas possam ser adicionadas a um agente
4. Invocar as ferramentas de um agente usando a chamada de função

Configurando um cliente MCP

Primeiro, crie um cliente MCP que se conecte ao servidor MCP desejado:

// 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"],
}));

Neste exemplo:

• Nome: um nome amigável para a conexão do servidor MCP
• Comando: o executável para executar o servidor MCP (aqui usando npx para executar um pacote de Node.js)
• Argumentos: argumentos de linha de comando passados para o servidor MCP

Recuperando ferramentas disponíveis

Depois de conectado, recupere a lista de ferramentas disponíveis no servidor MCP:

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

O ListToolsAsync() método retorna uma coleção de ferramentas que o servidor MCP expõe. Essas ferramentas são convertidas automaticamente em objetos AITool que podem ser usados pelo agente.

Criando um agente com ferramentas mcp

Crie seu agente e forneça as ferramentas mcp durante a inicialização:

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

Pontos principais:

• Instruções: forneça instruções claras que se alinhem aos recursos das ferramentas do MCP
• Ferramentas: converter as ferramentas MCP em AITool objetos e espalhá-las para a matriz de ferramentas
• O agente terá acesso automático a todas as ferramentas fornecidas pelo servidor MCP

Usando o agente

Depois de configurado, o agente pode usar automaticamente as ferramentas do MCP para atender às solicitações do usuário:

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

O agente:

1. Analisar a solicitação do usuário
2. Determinar quais ferramentas MCP são necessárias
3. Chamar as ferramentas apropriadas por meio do servidor MCP
4. Sintetizar os resultados em uma resposta coerente

Configuração do Ambiente

Certifique-se de configurar as variáveis de ambiente necessárias:

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

Gerenciamento de Recursos

Sempre descarte corretamente os recursos do cliente MCP:

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

O uso await using garante que a conexão do cliente MCP seja fechada corretamente quando ela sair do escopo.

Servidores MCP comuns

Os servidores MCP populares incluem:

• @modelcontextprotocol/server-github: acessar os repositórios e dados do GitHub
• @modelcontextprotocol/server-filesystem: operações do sistema de arquivos
• @modelcontextprotocol/server-sqlite: acesso ao banco de dados SQLite

Cada servidor fornece diferentes ferramentas e recursos que estendem a funcionalidade do agente. Essa integração permite que seus agentes acessem perfeitamente dados e serviços externos, mantendo os benefícios de segurança e padronização do Protocolo de Contexto do Modelo.

O código-fonte completo e as instruções para executar este exemplo estão disponíveis aqui.

O Python Agent Framework fornece suporte abrangente para integração com servidores MCP (Model Context Protocol) por meio de vários tipos de conexão. Isso permite que seus agentes acessem diretamente ferramentas e serviços externos.

Tipos de ferramentas MCP

O Agent Framework dá suporte a três tipos de conexões MCP:

MCPStdioTool – Servidores MCP locais

Use MCPStdioTool para se conectar a servidores MCP que são executados como processos locais usando entrada/saída padrão:

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 – Servidores MCP HTTP/SSE

Use MCPStreamableHTTPTool para se conectar a servidores MCP por HTTP com eventos 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://v4.hkg1.meaqua.org/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 – Servidores MCP WebSocket

Use MCPWebsocketTool para se conectar a servidores MCP por meio de conexões 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())

Servidores MCP populares

Servidores MCP comuns que você pode usar com o Python Agent Framework:

• Calculadora: uvx mcp-server-calculator – Cálculos matemáticos
• Sistema de arquivos: uvx mcp-server-filesystem – Operações do sistema de arquivos
• GitHub: npx @modelcontextprotocol/server-github – Acesso ao repositório GitHub
• SQLite: uvx mcp-server-sqlite – Operações de banco de dados

Cada servidor fornece diferentes ferramentas e funcionalidades que estendem a funcionalidade do agente, mantendo os benefícios de segurança e padronização do Protocolo de Contexto de Modelo.