wehub-resource-sync
14 KiB
14 KiB
Integración del Protocolo de Contexto del Modelo (MCP) con Microsoft Foundry
Esta guía demuestra cómo integrar servidores del Protocolo de Contexto del Modelo (MCP) con agentes de Microsoft Foundry, habilitando una potente orquestación de herramientas y capacidades de IA empresarial.
Introducción
El Protocolo de Contexto del Modelo (MCP) es un estándar abierto que permite a las aplicaciones de IA conectarse de forma segura a fuentes de datos y herramientas externas. Cuando se integra con Microsoft Foundry, MCP permite que los agentes accedan e interactúen con diversos servicios externos, APIs y fuentes de datos de manera estandarizada.
Esta integración combina la flexibilidad del ecosistema de herramientas de MCP con el robusto marco de agentes de Microsoft Foundry, proporcionando soluciones de IA de nivel empresarial con amplias capacidades de personalización.
Nota: Si desea usar MCP en el Servicio de Agentes de Microsoft Foundry, actualmente solo se admiten las siguientes regiones: westus, westus2, uaenorth, southindia y switzerlandnorth
Objetivos de aprendizaje
Al finalizar esta guía, podrá:
- Entender el Protocolo de Contexto del Modelo y sus beneficios
- Configurar servidores MCP para su uso con agentes de Microsoft Foundry
- Crear y configurar agentes con integración de herramientas MCP
- Implementar ejemplos prácticos usando servidores MCP reales
- Manejar respuestas de herramientas y citas en conversaciones con agentes
Requisitos previos
Antes de comenzar, asegúrese de tener:
- Una suscripción a Azure con acceso a Microsoft Foundry
- Python 3.10+ o .NET 8.0+
- Azure CLI instalado y configurado
- Permisos adecuados para crear recursos de IA
¿Qué es el Protocolo de Contexto del Modelo (MCP)?
El Protocolo de Contexto del Modelo es una forma estandarizada para que las aplicaciones de IA se conecten a fuentes externas de datos y herramientas. Los principales beneficios incluyen:
- Integración estandarizada: Interfaz consistente a través de diferentes herramientas y servicios
- Seguridad: Mecanismos seguros de autenticación y autorización
- Flexibilidad: Soporte para diversas fuentes de datos, APIs y herramientas personalizadas
- Extensibilidad: Fácil incorporación de nuevas capacidades e integraciones
Configuración de MCP con Microsoft Foundry
Configuración del entorno
Elija su entorno de desarrollo preferido:
Implementación en Python
Nota Puede ejecutar este notebook
1. Instalar los paquetes requeridos
pip install azure-ai-projects -U
pip install azure-ai-agents==1.1.0b4 -U
pip install azure-identity -U
pip install mcp==1.11.0 -U
2. Importar dependencias
import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import McpTool, RequiredMcpToolCall, SubmitToolApprovalAction, ToolApproval
3. Configurar ajustes de MCP
mcp_server_url = os.environ.get("MCP_SERVER_URL", "https://learn.microsoft.com/api/mcp")
mcp_server_label = os.environ.get("MCP_SERVER_LABEL", "mslearn")
4. Inicializar cliente de proyecto
project_client = AIProjectClient(
endpoint="https://your-project-endpoint.services.ai.azure.com/api/projects/your-project",
credential=DefaultAzureCredential(),
)
5. Crear herramienta MCP
mcp_tool = McpTool(
server_label=mcp_server_label,
server_url=mcp_server_url,
allowed_tools=[], # Opcional: especificar herramientas permitidas
)
6. Ejemplo completo en Python
with project_client:
agents_client = project_client.agents
# Crear un nuevo agente con herramientas MCP
agent = agents_client.create_agent(
model="Your AOAI Model Deployment",
name="my-mcp-agent",
instructions="You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
tools=mcp_tool.definitions,
)
print(f"Created agent, ID: {agent.id}")
print(f"MCP Server: {mcp_tool.server_label} at {mcp_tool.server_url}")
# Crear hilo para comunicación
thread = agents_client.threads.create()
print(f"Created thread, ID: {thread.id}")
# Crear mensaje para el hilo
message = agents_client.messages.create(
thread_id=thread.id,
role="user",
content="What's difference between Azure OpenAI and OpenAI?",
)
print(f"Created message, ID: {message.id}")
# Manejar aprobaciones de herramientas y ejecutar agente
mcp_tool.update_headers("SuperSecret", "123456")
run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)
print(f"Created run, ID: {run.id}")
while run.status in ["queued", "in_progress", "requires_action"]:
time.sleep(1)
run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
if run.status == "requires_action" and isinstance(run.required_action, SubmitToolApprovalAction):
tool_calls = run.required_action.submit_tool_approval.tool_calls
if not tool_calls:
print("No tool calls provided - cancelling run")
agents_client.runs.cancel(thread_id=thread.id, run_id=run.id)
break
tool_approvals = []
for tool_call in tool_calls:
if isinstance(tool_call, RequiredMcpToolCall):
try:
print(f"Approving tool call: {tool_call}")
tool_approvals.append(
ToolApproval(
tool_call_id=tool_call.id,
approve=True,
headers=mcp_tool.headers,
)
)
except Exception as e:
print(f"Error approving tool_call {tool_call.id}: {e}")
if tool_approvals:
agents_client.runs.submit_tool_outputs(
thread_id=thread.id, run_id=run.id, tool_approvals=tool_approvals
)
print(f"Current run status: {run.status}")
print(f"Run completed with status: {run.status}")
# Mostrar conversación
messages = agents_client.messages.list(thread_id=thread.id)
print("\nConversation:")
print("-" * 50)
for msg in messages:
if msg.text_messages:
last_text = msg.text_messages[-1]
print(f"{msg.role.upper()}: {last_text.text.value}")
print("-" * 50)
Implementación en .NET
Nota Puede ejecutar este notebook
1. Instalar los paquetes requeridos
#r "nuget: Azure.AI.Agents.Persistent, 1.1.0-beta.4"
#r "nuget: Azure.Identity, 1.14.2"
2. Importar dependencias
using Azure.AI.Agents.Persistent;
using Azure.Identity;
3. Configurar ajustes
var projectEndpoint = "https://your-project-endpoint.services.ai.azure.com/api/projects/your-project";
var modelDeploymentName = "Your AOAI Model Deployment";
var mcpServerUrl = "https://learn.microsoft.com/api/mcp";
var mcpServerLabel = "mslearn";
PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());
4. Crear definición de herramienta MCP
MCPToolDefinition mcpTool = new(mcpServerLabel, mcpServerUrl);
5. Crear agente con herramientas MCP
PersistentAgent agent = await agentClient.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "my-learn-agent",
instructions: "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
tools: [mcpTool]
);
6. Ejemplo completo en .NET
// Create thread and message
PersistentAgentThread thread = await agentClient.Threads.CreateThreadAsync();
PersistentThreadMessage message = await agentClient.Messages.CreateMessageAsync(
thread.Id,
MessageRole.User,
"What's difference between Azure OpenAI and OpenAI?");
// Configure tool resources with headers
MCPToolResource mcpToolResource = new(mcpServerLabel);
mcpToolResource.UpdateHeader("SuperSecret", "123456");
ToolResources toolResources = mcpToolResource.ToToolResources();
// Create and handle run
ThreadRun run = await agentClient.Runs.CreateRunAsync(thread, agent, toolResources);
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress || run.Status == RunStatus.RequiresAction)
{
await Task.Delay(TimeSpan.FromMilliseconds(1000));
run = await agentClient.Runs.GetRunAsync(thread.Id, run.Id);
if (run.Status == RunStatus.RequiresAction && run.RequiredAction is SubmitToolApprovalAction toolApprovalAction)
{
var toolApprovals = new List<ToolApproval>();
foreach (var toolCall in toolApprovalAction.SubmitToolApproval.ToolCalls)
{
if (toolCall is RequiredMcpToolCall mcpToolCall)
{
Console.WriteLine($"Approving MCP tool call: {mcpToolCall.Name}");
toolApprovals.Add(new ToolApproval(mcpToolCall.Id, approve: true)
{
Headers = { ["SuperSecret"] = "123456" }
});
}
}
if (toolApprovals.Count > 0)
{
run = await agentClient.Runs.SubmitToolOutputsToRunAsync(thread.Id, run.Id, toolApprovals: toolApprovals);
}
}
}
// Display messages
using Azure;
AsyncPageable<PersistentThreadMessage> messages = agentClient.Messages.GetMessagesAsync(
threadId: thread.Id,
order: ListSortOrder.Ascending
);
await foreach (PersistentThreadMessage threadMessage in messages)
{
Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
foreach (MessageContent contentItem in threadMessage.ContentItems)
{
if (contentItem is MessageTextContent textItem)
{
Console.Write(textItem.Text);
}
else if (contentItem is MessageImageFileContent imageFileItem)
{
Console.Write($"<image from ID: {imageFileItem.FileId}>");
}
Console.WriteLine();
}
}
Opciones de configuración de herramientas MCP
Al configurar herramientas MCP para su agente, puede especificar varios parámetros importantes:
Configuración en Python
mcp_tool = McpTool(
server_label="unique_server_name", # Identificador para el servidor MCP
server_url="https://api.example.com/mcp", # Punto final del servidor MCP
allowed_tools=[], # Opcional: especificar herramientas permitidas
)
Configuración en .NET
MCPToolDefinition mcpTool = new(
"unique_server_name", // Server label
"https://api.example.com/mcp" // MCP server URL
);
Autenticación y encabezados
Ambas implementaciones soportan encabezados personalizados para autenticación:
Python
mcp_tool.update_headers("SuperSecret", "123456")
.NET
MCPToolResource mcpToolResource = new(mcpServerLabel);
mcpToolResource.UpdateHeader("SuperSecret", "123456");
Solución de problemas comunes
1. Problemas de conexión
- Verifique que la URL del servidor MCP sea accesible
- Revise las credenciales de autenticación
- Asegúrese de la conectividad de red
2. Fallos en llamadas a herramientas
- Revise los argumentos y formato de la herramienta
- Verifique los requisitos específicos del servidor
- Implemente manejo de errores adecuado
3. Problemas de rendimiento
- Optimice la frecuencia de llamadas a la herramienta
- Implemente caché donde sea apropiado
- Monitoree los tiempos de respuesta del servidor
Próximos pasos
Para mejorar aún más su integración MCP:
- Explore servidores MCP personalizados: Construya sus propios servidores MCP para fuentes de datos propietarias
- Implemente seguridad avanzada: Añada OAuth2 o mecanismos personalizados de autenticación
- Monitoreo y análisis: Implemente registros y monitoreo del uso de herramientas
- Escale su solución: Considere balanceo de carga y arquitecturas distribuidas de servidores MCP
Recursos adicionales
- Documentación de Microsoft Foundry
- Ejemplos del Protocolo de Contexto del Modelo
- Descripción general de Agentes de Microsoft Foundry
- Especificación MCP
Soporte
Para soporte adicional y preguntas:
- Revise la documentación de Microsoft Foundry
- Consulte los recursos comunitarios MCP
Qué sigue
Descargo de responsabilidad: Este documento ha sido traducido utilizando el servicio de traducción automática Co-op Translator. Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción.