Comparteix a través de

Agregar y administrar herramientas

Importante

Debe formar parte del programa de versión preliminar Frontier para obtener acceso anticipado a Microsoft Agent 365. Frontier le conecta directamente con las innovaciones de inteligencia artificial más recientes de Microsoft. Las versiones preliminares de Frontier están sujetas a los términos de vista previa existentes en tus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

El módulo de Herramientas ayuda a los desarrolladores a descubrir, configurar e integrar servidores del Protocolo de Contexto de Modelo (MCP) en los flujos de trabajo de agentes 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.

Muestra el flujo de solicitud y respuesta

Información general

La integración de herramientas del Agente 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 servidor.
  3. Aplicar permisos al plano técnico : un administrador global concede permisos de OAuth2 al plano técnico del agente mediante la ejecución a365 setup all (configuración por primera vez) 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 es independiente de agregar servidores al manifiesto.
  4. Integración en código : carga del manifiesto y registro de 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 posterior: Download
  • Privilegios de administrador global en la entidad 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 aplicación y el usuario agente que permiten a tu agente autenticarse y acceder a las herramientas MCP.

Configuración de autenticación OBO

Si usas autenticación On-Behalf-Of (OBO) en lugar de autenticación agente, tu agente puede acceder a las herramientas MCP usando permisos de usuario delegados sin una identidad de usuario agente. En el flujo OBO, el agente intercambia el token delegado por un usuario para realizar acciones en nombre del usuario.

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

Configurar entidad de servicio

Ejecuta este script de configuración de un solo uso para crear el principio de servicio para las herramientas de Agent 365 en tu tenant.

Importante

Esta operación única por inquilino requiere privilegios de Administrador Global.

  1. Descarga el New-Agent365ToolsServicePrincipalProdPublic.ps1 script.

  2. Abre PowerShell como Administrador y ve al directorio de scripts.

  3. Ejecute el script.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

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

Una vez completado, su entorno 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

Enumera todos los servidores MCP que puedas 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

Importante

Este comando solo actualiza ToolingManifest.json en la carpeta de tu proyecto; no concede permisos al esquema. La forma en que se aplican los permisos depende de dónde se encuentra en el proceso de configuración:

  • Antes de la instalación inicial: ejecute a365 develop add-mcp-servers primero y, a continuación, continúe con a365 setup all. El setup all comando incluye el paso de permisos de MCP como parte de la creación del plano técnico.
  • Después de que el blueprint ya exista: un administrador global debe ejecutarlo a365 setup permissions mcp por separado. El administrador a365.config.json debe tener deploymentProjectPath apuntando a la carpeta del proyecto que contiene el objeto actualizado ToolingManifest.json. Hasta que se complete este paso, los nuevos permisos de servidor MCP no estarán visibles en el plano técnico.

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 la referencia completa de la CLI, véase a365 develop command.

Utiliza el servidor de herramientas simuladas para pruebas

Para pruebas y desarrollo, utiliza el servidor de herramientas de simulacro CLI Agent 365 en lugar de conectarte a servidores MCP reales. El servidor simulado simula interacciones con el servidor MCP, por lo que puedes probar tu agente localmente sin dependencias externas como la autenticación.

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

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

Inicia el servidor de herramientas simuladas usando el a365 develop start-mock-tooling-server comando.

Aprende a configurar y configurar el servidor de herramientas de simulacros.

Nota

Las siguientes secciones para configurar manifiestos e integrar herramientas en tu agente funcionan de la misma manera, tanto si usas el servidor de herramientas simuladas como servidores MCP reales. Configura tu MCP_PLATFORM_ENDPOINT variable de entorno para que apunte al servidor de simulación (por ejemplo: http://localhost:5309) en lugar del endpoint de producción.

Entender el 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:

Parámetro Descripción
mcpServerName Nombre visible del servidor MCP.
mcpServerUniqueName Identificador único de la instancia del servidor MCP.
de ámbito de Ámbito de OAuth necesario para acceder a las funcionalidades del servidor MCP (por ejemplo, McpServers.Mail.All para las operaciones de correo). El add-mcp-servers comando recupera este valor del catálogo del servidor MCP.
audiencia El Microsoft Entra ID URI que identifica el recurso de API de destino. El add-mcp-servers comando recupera este valor del catálogo del servidor MCP.

Nota

La CLI de Agent 365 rellena automáticamente los valores scope y audience cuando añades un servidor MCP. Estos valores proceden del catálogo de servidores MCP y definen los permisos necesarios para acceder a cada servidor MCP.

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.

Servidores de herramientas de listas (opcional)

Propina

Este paso es opcional. Use el servicio de configuración del servidor de herramientas para inspeccionar los servidores de herramientas disponibles desde el manifiesto de herramientas antes de agregarlos al orquestador.

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:

  • Consulta todos los servidores MCP configurados desde el ToolingManifest.json archivo.
  • Recuperar los metadatos y capacidades del servidor.
  • Verifica la disponibilidad del servidor antes de registrarte.

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)

Parámetros:

Parámetro Tipo Descripción Valor esperado Obligatorio/Opcional
agentic_app_id str Identificador único de la instancia de la aplicación de agente Cadena de ID válida de aplicación de agente Obligatorio
auth_token str Token de portador para la autenticación mediante la puerta de enlace del servidor MCP Token de portador de OAuth válido Obligatorio

Paquete: microsoft_agents_a365.tooling

Registrar herramientas en 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:

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

Elija la extensión del orquestador

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

Nota

Al ejecutar a365 develop add-mcp-servers, la CLI recupera automáticamente los ámbitos de OAuth y los valores de audiencia del catálogo de servidores MCP y los escribe en ToolingManifest.json. Los métodos de extensión usan estos valores para configurar la autenticación en tiempo de ejecución; no se requiere ninguna configuración manual en el código del agente. Sin embargo, un administrador global todavía debe conceder estos permisos al plano técnico del agente antes de que el agente pueda usarlos en producción: a través a365 setup all de (configuración por primera vez) o a365 setup permissions mcp (si el plano técnico ya existe).

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

Ejemplos de implementación

Los siguientes ejemplos muestran cómo integrar las herramientas Agent 365 con diferentes frameworks de orquestación.

Python con OpenAI

En este ejemplo se muestra cómo integrar herramientas de MCP con OpenAI en una aplicación de Python.

1. Agregar declaraciones de importación

Agregue las importaciones necesarias para acceder al módulo Herramientas y las extensiones de OpenAI:

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

2. Inicializar servicios de herramientas de desarrollo

Cree instancias de los servicios de configuración y registro de herramientas:

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

3. Registrar herramientas de MCP con el agente de OpenAI

Use el método add_tool_servers_to_agent para registrar todas las herramientas de MCP configuradas con el agente de OpenAI. Este método gestiona escenarios de autenticación tanto de agente como de no agente:

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}")

Parámetros de métodos

La tabla siguiente describe los parámetros para usar con add_tool_servers_to_agent.

Parámetro Descripción
agent Instancia del agente de OpenAI con la que se registrarán las herramientas.
agentic_app_id Identificador único para el agente (ID de la aplicación agentic).
auth Contexto de autorización para el usuario.
context Contexto de turno de conversación actual del SDK de agentes. Proporciona identidad de usuario, metadatos de conversación y contexto de autenticación para el registro seguro de herramientas.
auth_token (Opcional) Token de portador para escenarios de autenticación no de agente.

4. Llamada durante la inicialización

Asegúrese de llamar al método de configuración durante la inicialización antes de ejecutar el agente:

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

El método add_tool_servers_to_agent se realiza automáticamente:

  • Carga todos los servidores MCP desde el archivo ToolingManifest.json.
  • Registra sus herramientas con el agente de OpenAI.
  • Configura la autenticación según la configuración del manifiesto.
  • Pon a disposición las herramientas que tu agente puede utilizar.

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

Otras formas de acceder a servidores MCP de Agent 365

Además del SDK Agent 365, puedes 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 de desarrollo personalizados.
  • Microsoft Copilot Studio: integre servidores MCP en flujos conversacionales mediante una experiencia de código bajo.
  • Azure AI Foundry: use servidores MCP con compatibilidad completa con el SDK y funcionalidades avanzadas de orquestación.

Para una visión completa de los servidores MCP disponibles y las opciones de integración en estas plataformas, consulte la visión general de los servidores de herramientas del Agente 365.

Probar el agente

Después de integrar las herramientas MCP en tu agente, prueba las invocaciones de herramientas para asegurarte de que funcionan correctamente y manejan diferentes escenarios. Sigue la guía de pruebas para configurar tu entorno. Luego, céntrate principalmente en la sección de invocaciones de herramientas de prueba para validar que tus herramientas MCP funcionan como se espera. Además, echa un vistazo al servidor de herramientas simuladas para probar la conexión del servidor MCP y las invocaciones de herramientas sin necesidad de autenticación.

Agregar observabilidad

Añade observabilidad a tu agente para monitorizar y rastrear las invocaciones de la herramienta MCP de tu agente. Al añadir capacidades de observabilidad, puedes seguir el rendimiento, depurar problemas y entender patrones de uso de herramientas. Infórmate más sobre cómo implementar el rastreo y el seguimiento.

Solución de problemas

Esta sección enumera los problemas comunes cuando configuras y usas servidores y herramientas MCP.

Propina

La Guía de Resolución de Problemas del Agente 365 contiene recomendaciones de alto nivel para la solución de problemas, mejores prácticas y enlaces a contenido de solución de problemas para cada parte del ciclo de vida del desarrollo del Agente 365.

Problemas de servidores y herramientas MCP

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.
  • El service principal no está configurado.
  • Confusión entre servidores simulados y de producción.

Soluciones: Prueba las siguientes soluciones para abordar el problema.

  • Verifica que los servidores MCP estén configurados

    Haz una lista de servidores configurados y añade los que falten.

    # 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 el principal del servicio

    Asegúrate de que se crea el principio de servicio necesario para las 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 iniciales, utiliza servidores simulados

    Usa el servidor de herramientas simuladas para el desarrollo local temprano y las pruebas si quieres probar el resto de tu 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

    Aprende sobre el servidor de herramientas de simulación.

  • Verifica permisos en el centro de administración

    Confirma que tu agente tiene los permisos MCP necesarios.

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

    Comprobación:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on