Agregar y administrar herramientas

El módulo Herramientas ayuda a los desarrolladores a detectar, configurar e integrar servidores del Protocolo de contexto de modelo (MCP) en flujos de trabajo del agente de IA. Los servidores MCP exponen funcionalidades externas como herramientas que los agentes de IA pueden invocar. Para obtener información general sobre los servidores de herramientas disponibles, consulte Servidores de herramientas de Agent 365.

Información general

La integración de herramientas de Agent 365 sigue este flujo de trabajo:

1. Configuración de servidores MCP: usar la CLI de Agent 365 para detectar y agregar servidores MCP
2. Generar manifiesto: la CLI crea ToolingManifest.json en la carpeta del proyecto con configuraciones de los servidores.
3. Aplicar permisos al plano técnico: un administrador global concede permisos OAuth2 al plano técnico del agente ejecutando a365 setup all (primera configuración) o a365 setup permissions mcp (si el plano técnico ya existe). En cualquier caso, el comando lee ToolingManifest.json y requiere el consentimiento del administrador. Este paso siempre está separado de agregar servidores al manifiesto.
4. Integrar en código : cargar el manifiesto y registrar herramientas con el orquestador.
5. Invocar herramientas: el agente llama a las herramientas durante la ejecución para realizar operaciones.

Requisitos previos

Antes de configurar servidores MCP, asegúrese de tener:

• CLI de Agent 365 instalada y configurada
• SDK de .NET 8.0 o superior: Descargar
• Privilegios del Administrador global en su inquilino de Microsoft 365

Configuración de la identidad del agente

Si usa la autenticación de agente, complete el proceso de registro de agente para crear la identidad de agente antes de configurar los servidores MCP. Este proceso crea el id. de agente de Entra y el usuario de agente que permite al agente autenticar y acceder a las herramientas de MCP.

Configuración de autenticación OBO

Si utiliza la autenticación En nombre de (OBO) en lugar de la autenticación de agente, su agente puede acceder a las herramientas MCP con permisos de usuario delegados sin una identidad de usuario agente. En el flujo OBO, el agente intercambia el token delegado de un usuario para realizar acciones en nombre del usuario.

Para obtener más información sobre cómo funciona el flujo OBO, consulte Flujos de autenticación. Para un ejemplo completo de implementación, consulte el ejemplo de autorización OBO en el SDK de agentes de Microsoft 365.

Configurar entidad de servicio

Ejecute este script de configuración única para crear la entidad de servicio para las herramientas de Agent 365 en su inquilino.

1. Descargue el script New-Agent365ToolsServicePrincipalProdPublic.ps1

2. Abra PowerShell como administrador y vaya hasta el directorio de scripts.

3. Ejecute el script.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Inicie sesión con sus credenciales de Azure cuando se le solicite.

Después de la finalización, el inquilino está listo para el desarrollo del agente y la configuración del servidor MCP.

Configuración de servidores MCP

Use la CLI de Agent 365 para detectar, agregar y administrar servidores MCP para el agente. Para obtener una lista completa de los servidores MCP disponibles y sus funcionalidades, consulte el catálogo de servidores MCP.

Descubrir servidores disponibles

Muestre todos los servidores MCP que puede configurar:

a365 develop list-available

Agregar servidores MCP

Agregar uno o varios servidores MCP a la configuración del agente:

a365 develop add-mcp-servers mcp_MailTools

Enumerar servidores configurados

Ver los servidores MCP configurados actualmente:

a365 develop list-configured

Quitar servidores MCP

Quitar un servidor MCP de la configuración:

a365 develop remove-mcp-servers mcp_MailTools

Para obtener la referencia completa de la CLI, consulte comando de desarrollo de a365.

Usar el servidor de herramientas simuladas para pruebas

Para pruebas y desarrollo, use el servidor simulado de CLI de Agent 365 en lugar de conectarse a servidores MCP reales. El servidor simulado reproduce las interacciones del servidor MCP, por lo que puede probar su agente localmente sin dependencias externas, como la autenticación.

El servidor simulado ofrece los siguientes beneficios para el desarrollo y pruebas locales:

• Desarrollo sin conexión: Prueba tu agente sin conectividad a internet ni dependencias externas.
• Pruebas consistentes: Recibe respuestas predecibles para probar casos límite.
• Depuración: vea todas las solicitudes y respuestas en tiempo real
• Iteración rápida: No es necesario esperar llamadas externas a la API ni configurar entornos de prueba complejos.

Inicie el servidor simulado de herramientas usando el comando a365 develop start-mock-tooling-server.

Aprende a instalar y configurar el servidor simulado de herramientas.

Descripción del manifiesto de herramientas

Al ejecutar a365 develop add-mcp-servers, la CLI genera un archivo ToolingManifest.json que contiene la configuración de todos los servidores MCP. El runtime del agente usa este manifiesto para comprender qué servidores están disponibles y cómo autenticarse con ellos.

Estructura del manifiesto

Ejemplo ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Parámetros de manifiesto

Cada entrada del servidor MCP contiene:

Integrar herramientas en su agente

Después de generar el manifiesto de herramientas, integre los servidores MCP configurados en el código del agente. En esta sección se describe el paso de inspección opcional y los pasos de integración obligatorios.

Enumerar servidores de herramientas (opcional)

Use el servicio de configuración del servidor de herramientas para detectar qué servidores de herramientas están disponibles para el agente desde el manifiesto de herramientas. Este método le permite:

• Consulte todos los servidores MCP configurados desde el archivo ToolingManifest.json.
• Recupere metadatos y funcionalidades del servidor.
• Compruebe la disponibilidad del servidor antes del registro.

El método para enumerar los servidores de herramientas está disponible en los paquetes principales de herramientas:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

Registrar herramientas con el orquestador

Use el método de extensión específico del marco para registrar todos los servidores MCP con el marco de orquestación:

• AddToolServersToAgentAsync (.NET)
• add_tool_servers_to_agent (Python)
• addToolServersToAgent (Node.js)

Estos métodos:

• Registrar todas las herramientas de servidores MCP configurados con el orquestador
• Configurar detalles de autenticación y conexión automáticamente
• Hacer que las herramientas estén disponibles inmediatamente para que el agente invoque

Elegir la extensión de orquestador

El módulo Herramientas de Agent 365 proporciona paquetes de extensión dedicados para diferentes marcos de orquestación:

Para obtener ejemplos detallados de implementación, consulte Ejemplos de Agent 365.

Ejemplos de implementación

En los ejemplos siguientes se muestra cómo integrar las herramientas de Agent 365 con diferentes marcos de orquestación.

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

const toolService = new McpToolRegistrationService();

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

private readonly IMcpToolRegistrationService _toolsService;

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

Para obtener ejemplos de trabajo completos, consulte el repositorio de ejemplos de Agent 365.

Otras formas de acceder a los servidores MCP de Agent 365

Además del SDK de Agent 365, puede acceder a los servidores MCP de Agent 365 a través de otras experiencias de desarrollo:

• Visual Studio Code: conéctese directamente a los servidores MCP para flujos de trabajo personalizados de desarrollo.
• Microsoft Copilot Studio: integrar servidores MCP en flujos conversacionales utilizando una experiencia con poco código.
• Fundición de IA de Azure: utilice servidores MCP con soporte total para el SDK y capacidades avanzadas de orquestación.

Para una descripción general completa de los servidores MCP disponibles y las opciones de integración en estas plataformas, consulte Introducción a los servidores de herramientas de Agent 365.

Servidor MCP Bring your own (BYO)

La característica de servidor MCP Bring Your Own (BYO) permite registrar sus propios servidores MCP externos en Microsoft Agent 365 para que puedan ser gobernados, aprobados y supervisados de manera centralizada en el Centro de administración de Microsoft 365. Enruta estos servidores a través de la puerta de enlace de herramientas de Agent 365, dando a los administradores control sobre la aprobación, el acceso y las directivas, mientras permite a los equipos de seguridad rastrear el uso mediante telemetría. Como desarrollador, puedes registrar su servidor MCP usando la CLI de Agent 365; luego, su administrador revisa y aprueba el registro y concede permisos. El servidor aprobado puede entonces utilizarse en las herramientas cliente compatibles, con una supervisión continua que garantiza el cumplimiento y la visibilidad en todas las integraciones.

Para obtener instrucciones completas, consulte Servidor MCP Bring your own (BYO).

Probar el agente

Después de integrar las herramientas de MCP en el agente, pruebe las invocaciones de herramientas para asegurarse de que funcionan correctamente y gestionen diferentes escenarios. Siga la guía de pruebas para configurar su entorno. Luego, concéntrese principalmente en la sección Invocaciones de la herramienta de prueba para validar que sus herramientas MCP funcionan como se espera. También consulte el servidor de herramientas simulado para probar la conexión al servidor MCP y las invocaciones de herramientas sin gestionar la autenticación.

Agregar observabilidad

Agregue observabilidad a su agente para supervisar y realizar un seguimiento de las invocaciones de herramientas MCP. Al agregar capacidades de observabilidad, puede supervisar el rendimiento, depurar problemas y comprender los patrones de uso de las herramientas. Más información acerca de la implementación del seguimiento y la supervisión.

Solución de problemas

Esta sección muestra los problemas comunes al configurar y usar servidores y herramientas MCP.

Problemas de servidores MCP y de herramientas

Síntomas:

• Errores en las llamadas a herramientas
• Errores de "Servidor MCP no encontrado".
• Errores de permisos denegados al utilizar herramientas.

Causa principal:

• El servidor MCP no está configurado.
• Faltan permisos.
• La entidad de servicio no está configurada.
• Confusión entre servidores simulados y de producción.

Soluciones: pruebe las siguientes soluciones para abordar el problema.

• Comprobar que los servidores MCP estén configurados

  Muestre los servidores configurados y agregue los que faltan.

  # List configured servers
  a365 develop list-configured
  
  # If empty, add required servers (example: Mail MCP server)
  a365 develop add-mcp-servers mcp_MailTools
  

• Comprobar si existe la entidad de servicio

  Asegúrese de que se crea la entidad de servicio requerida para herramientas.

  # Run the one-time setup script
  # https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
  

• Para el desarrollo y las pruebas tempranas, utilice servidores simulados

  Use el servidor de herramientas simuladas para el desarrollo local y las pruebas tempranos si quieres probar el resto de su agente sin componentes de herramientas de producción.

  # Start mock tooling server
  a365 develop start-mock-tooling-server
  
  # Update your .env
  MCP_PLATFORM_ENDPOINT=http://localhost:5309
  

  Aprenda sobre el servidor de herramientas de simulación.

• Comprobar permisos en el Centro de administración

  Comprobar que su agente tiene los permisos necesarios de MCP.

  • Compruebe que los permisos de la API del plano técnico de agente en Azure Portal muestren todos los permisos del servidor MCP.

  Comprobación:

  # Test a tool call in Agents Playground
  # Should execute without permission errors