Uso de herramientas de MCP con agentes de Foundry

Puede ampliar las funcionalidades del agente de Azure AI Foundry conectándolo a herramientas hospedadas en servidores remotos del Protocolo de contexto de modelo (MCP), aportando su propio punto de conexión del servidor MCP.

Uso de la herramienta Protocolo de contexto de modelo

En esta sección se explica cómo crear un agente de IA mediante Azure Foundry (Azure AI) con una integración del servidor hospedado del Protocolo de contexto de modelo (MCP). El agente puede usar herramientas de MCP administradas y ejecutadas por el servicio Azure Foundry, lo que permite el acceso seguro y controlado a recursos externos.

Características clave

Servidor MCP hospedado: El servidor MCP se hospeda y administra mediante Azure AI Foundry, lo que elimina la necesidad de administrar la infraestructura del servidor.
Agentes persistentes: los agentes se crean y almacenan en el servidor, lo que permite conversaciones con estado.
Flujo de trabajo de aprobación de herramientas: mecanismos de aprobación configurables para invocaciones de herramientas MCP

Funcionamiento

1. Configuración del entorno

El ejemplo requiere dos variables de entorno:

AZURE_FOUNDRY_PROJECT_ENDPOINT: dirección URL del punto de conexión del proyecto de Azure AI Foundry
AZURE_FOUNDRY_PROJECT_MODEL_ID: el nombre de implementación del modelo (el valor predeterminado es "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. Configuración del agente

El agente se configura con instrucciones y metadatos específicos:

const string AgentName = "MicrosoftLearnAgent";
const string AgentInstructions = "You answer questions by searching the Microsoft Learn content only.";

Esto crea un agente especializado para responder preguntas mediante la documentación de Microsoft Learn.

3. Definición de la herramienta MCP

El ejemplo crea una definición de herramienta MCP que apunta a un servidor MCP hospedado:

var mcpTool = new MCPToolDefinition(
    serverLabel: "microsoft_learn",
    serverUrl: "https://learn.microsoft.com/api/mcp");
mcpTool.AllowedTools.Add("microsoft_docs_search");

Componentes claves:

serverLabel: identificador único para la instancia del servidor MCP
serverUrl: la dirección URL del servidor MCP hospedado
AllowedTools: especifica qué herramientas del servidor MCP puede usar el agente.

4. Creación persistente del agente

El agente se crea en el lado servidor mediante el SDK de agentes persistentes de Azure AI Foundry:

var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());

var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: model,
    name: AgentName,
    instructions: AgentInstructions,
    tools: [mcpTool]);

Advertencia

DefaultAzureCredential es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere la posibilidad de usar una credencial específica (por ejemplo, ManagedIdentityCredential) para evitar problemas de latencia, sondeos de credenciales no deseados y posibles riesgos de seguridad de los mecanismos de reserva.

Esto crea un agente persistente que:

Reside en el servicio Azure AI Foundry
Tiene acceso a las herramientas de MCP especificadas.
Puede mantener el estado de la conversación entre varias interacciones

5. Recuperación y ejecución del agente

El agente creado se recupera como una AIAgent instancia de :

AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

6. Configuración de recursos de herramientas

En el ejemplo se configuran los recursos de la herramienta con la configuración de aprobación:

var runOptions = new ChatClientAgentRunOptions()
{
    ChatOptions = new()
    {
        RawRepresentationFactory = (_) => new ThreadAndRunOptions()
        {
            ToolResources = new MCPToolResource(serverLabel: "microsoft_learn")
            {
                RequireApproval = new MCPApproval("never"),
            }.ToToolResources()
        }
    }
};

Configuración de claves:

MCPToolResource: vincula la instancia del servidor MCP a la ejecución del agente
RequireApproval: controla cuándo se necesita la aprobación del usuario para las invocaciones de herramientas
- "never": las herramientas se ejecutan automáticamente sin aprobación.
- "always": todas las invocaciones de herramientas requieren aprobación del usuario.
- También se pueden configurar reglas de aprobación personalizadas.

7. Ejecución del agente

El agente se invoca con una pregunta y se ejecuta mediante las herramientas de MCP configuradas:

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. Limpieza

En el ejemplo se muestra la limpieza de recursos adecuada:

await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);

Sugerencia

Consulte los ejemplos de .NET para obtener ejemplos completos de ejecución.

Azure AI Foundry proporciona una integración perfecta con los servidores del Protocolo de contexto de modelo (MCP) a través del marco del agente de Python. El servicio administra el hospedaje y la ejecución del servidor MCP, lo que elimina la administración de la infraestructura al tiempo que proporciona acceso seguro y controlado a herramientas externas.

Configuración del entorno

Configure las credenciales del proyecto de Azure AI Foundry mediante variables de entorno:

import os
from azure.identity.aio import AzureCliCredential
from agent_framework.azure import AzureAIAgentClient

# Required environment variables
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = "https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"] = "gpt-4o-mini"  # Optional, defaults to this

Integración básica de MCP

Cree un agente de Azure AI Foundry con herramientas de MCP hospedadas:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def basic_foundry_mcp_example():
    """Basic example of Azure AI Foundry agent with hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as client,
    ):
        # 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
        agent = client.as_agent(
            name="MicrosoftLearnAgent", 
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=learn_mcp,
        )

        # Simple query without approval workflow
        result = await agent.run(
            "Please summarize the Azure AI Agent documentation related to MCP tool calling?"
        )
        print(result)

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

Configuración de MCP de varias herramientas

Use varias herramientas de MCP hospedadas con un solo agente:

async def multi_tool_mcp_example():
    """Example using multiple hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as client,
    ):
        # 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.github.com/mcp",
            approval_mode="always_require",  # Require approval for GitHub operations
            headers={"Authorization": "Bearer github-token"},
        )

        # Create agent with multiple MCP tools
        agent = client.as_agent(
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[learn_mcp, github_mcp],
        )

        result = await agent.run(
            "Find Azure documentation and also check the latest commits in microsoft/semantic-kernel"
        )
        print(result)

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

El marco del agente de Python proporciona una integración perfecta con las funcionalidades de MCP hospedadas de Azure AI Foundry, lo que permite el acceso seguro y escalable a herramientas externas, a la vez que mantiene la flexibilidad y el control necesarios para las aplicaciones de producción.

Ejemplo completo

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient
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_RESPONSES_MODEL_ID: 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 = OpenAIResponsesClient()
    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())

Pasos siguientes

Uso de flujos de trabajo como agentes

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-02-13