Partilhar via

Usando ferramentas MCP com agentes

O Microsoft Agent Framework oferece suporte à integração com servidores MCP (Model Context Protocol), permitindo que seus agentes acessem ferramentas e serviços externos. Este guia mostra como se conectar a um servidor MCP e usar suas ferramentas dentro do seu agente.

A versão .Net do Agent Framework pode ser usada em conjunto com o MCP C# SDK oficial 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 AIFunction's para que possam ser adicionadas a um agente
  4. Invoque 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 sua conexão de servidor MCP
  • Comando: O executável para executar o servidor MCP (aqui usando npx para executar um pacote Node.js)
  • Argumentos: argumentos de linha de comando passados para o servidor MCP

Recuperando ferramentas disponíveis

Uma vez 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 seu 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 alinham com os recursos de suas ferramentas MCP
  • Ferramentas: Converta as ferramentas MCP em AITool objetos e espalhe-as na matriz de ferramentas
  • O agente terá automaticamente acesso a todas as ferramentas fornecidas pelo servidor MCP

Usando o agente

Uma vez configurado, seu agente pode usar automaticamente as ferramentas 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 irá:

  1. Analise a solicitação do usuário
  2. Determinar quais ferramentas MCP são necessárias
  3. Chame as ferramentas apropriadas através do servidor MCP
  4. Sintetizar os resultados numa 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";

Gestão de Recursos

Descarte sempre 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 sair do escopo.

Servidores MCP comuns

Os servidores MCP populares incluem:

  • @modelcontextprotocol/server-github: Acesse 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 seu 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 Model Context Protocol.

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 ferramentas e serviços externos sem problemas.

Tipos de ferramentas MCP

O Agent Framework suporta 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 HTTP/SSE MCP

Use MCPStreamableHTTPTool para se conectar a servidores MCP via HTTP com Server-Sent Eventos:

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 - Servidores WebSocket MCP

Use MCPWebsocketTool para se conectar a servidores MCP através 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 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 recursos que estendem a funcionalidade do seu agente, mantendo os benefícios de segurança e padronização do Protocolo de Contexto do Modelo.

Próximos passos

Usando fluxos de trabalho como agentes

  • Last updated on