Compartir a través de

Probar agentes mediante el SDK de Microsoft Agent 365

Importante

Debe formar parte del programa de versión preliminar de 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.

Pruebe el agente localmente con el área de juegos de agentes antes de la implementación. En esta guía se describe la configuración del entorno de desarrollo, la configuración de la autenticación y la validación de la funcionalidad del agente con la herramienta de prueba del área de juegos.

Una vez que el agente funcione localmente, puede implementarlo y publicarlo para probarlo en aplicaciones de Microsoft 365, como Teams.

Requisitos previos

Antes de comenzar a probar el agente, asegúrese de que cumple los siguientes requisitos previos instalados:

Requisitos previos comunes

Requisitos previos específicos de idioma

Configurar el entorno de pruebas del agente

En esta sección se tratan las variables de entorno de configuración, la autenticación del entorno de desarrollo y la preparación de Agent 365 con tecnología para pruebas.

La configuración del entorno de pruebas del agente sigue un flujo de trabajo secuencial:

  1. Configurar el entorno : crear o actualizar el archivo de configuración del entorno

  2. Configuración de LLM: obtener la claves de API y configurar los ajustes de OpenAI o Azure OpenAI

  3. Configurar autenticación: configurar autenticación de agente

  4. Referencia de variables de entorno: configure las variables de entorno necesarias:

    1. Variables de autenticación
    2. Configuración de puntos de conexión MCP
    3. Variables de observabilidad
    4. Configuración del servidor de aplicaciones del agente

Después de completar estos pasos, está listo para empezar a probar el agente en el Área de juegos de agentes.

Paso 1: Configuración del entorno

Configure su archivo de configuración:

cp .env.template .env

Nota

Consulte los ejemplos del SDK de Microsoft Agent 365 para buscar plantillas de configuración que muestren los campos necesarios.

Paso 2: Configuración de LLM

Configure los ajustes de OpenAI o Azure OpenAI para pruebas locales. Agregue las claves de API y los puntos de conexión de servicio obtenidos de los requisitos previos al archivo de configuración junto con cualquier parámetros de modelo.

Agregue a su archivo .env:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Variables de entorno de LLM de Python

Variable Descripción Obligatorio Ejemplo
OPENAI_API_KEY Clave de API para OpenAI Service Para OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Clave de API para Azure OpenAI Service Para Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL de punto de conexión de Azure OpenAI Service Para Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nombre de implementación en Azure OpenAI Para Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Versión de API para Azure OpenAI Para Azure OpenAI 2024-02-15-preview

Paso 3: Configurar la autenticación para tu agente

Elige uno de los siguientes métodos de autenticación para tu agente:

Autenticación agente

Use el comando de la CLI a365 config display de A365 para recuperar las credenciales del plano técnico del agente.

a365 config display -g

Este comando muestra la configuración del plano técnico del agente. Copie los siguientes valores:

valor Descripción
agentBlueprintId Id. de cliente del agente
agentBlueprintClientSecret Secreto de cliente del agente
tenantId Su identificador de inquilino de Microsoft Entra

Use estos valores para configurar la autenticación de agente en su agente:

Agregue la siguiente configuración al archivo .env y reemplace los valores de marcador de posición por sus credenciales reales:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variable Descripción Obligatorio Ejemplo
USE_AGENTIC_AUTH Habilitar el modo de autenticación de agente Sí true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Id. de cliente del plano técnico de agente desde a365 config display -g Sí 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Id. de cliente de plano técnico de agente desde a365 config display -g Sí abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Id. de inquilino de Microsoft Entra desde a365 config display -g Sí adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Autenticación por token de portador

Para escenarios iniciales de desarrollo y pruebas cuando los usuarios del agente no estén disponibles, puedes usar la autenticación con token portador para probar tu agente.

Primero, usa a365 develop add-permissions para añadir los permisos necesarios del servidor MCP a tu aplicación:

a365 develop add-permissions

Luego, se utiliza a365 develop get-token para recuperar y configurar los tokens portadores:

a365 develop get-token

El get-token comando automáticamente:

  • Recupera los tokens portadores de todos los servidores MCP configurados en tu ToolingManifest.json archivo
  • Actualiza los archivos de configuración de tu proyecto con la BEARER_TOKEN variable de entorno

Nota

Las fichas de portador expiran tras aproximadamente 1 hora. Úsalo a365 develop get-token para refrescar fichas caducadas.

Paso 4: Referencia a variables de entorno

Complete la configuración del entorno mediante la configuración de las siguientes variables de entorno necesarias:

Variables de autenticación

Configure las opciones del controlador de autenticación necesarias para que la autenticación agente funcione correctamente.

Agregue a su archivo .env:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Variable Descripción Obligatorio
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Tipo de controlador de autenticación Sí
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Ámbitos de autenticación para Microsoft Graph Sí
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nombre de conexión de plano técnico alternativo Sí
CONNECTIONSMAP_0_SERVICEURL Patrón de dirección URL de servicio para la asignación de conexiones Sí
CONNECTIONSMAP_0_CONNECTION Nombre de conexión para asignación Sí

Configuración de puntos de conexión MCP

La configuración del punto de conexión de MCP (Protocolo de contexto de modelo) es necesaria para especificar a qué punto de conexión de la plataforma de Agent 365 debe conectarse el agente. Al generar el manifiesto de herramientas que define los servidores de herramientas para el agente, debe especificar el punto de conexión de la plataforma MCP. Este punto de conexión determina a qué entorno (preproducción, prueba o producción) se conectan los servidores de herramientas MCP para las funcionalidades de integración de Microsoft 365.

Agregue a su archivo .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variable Descripción Obligatorio Valor predeterminado Ejemplo
MCP_PLATFORM_ENDPOINT Dirección URL del punto de conexión de la plataforma MCP (preproducción, prueba o producción) No Punto de conexión de producción

Importante: si no se especifica MCP_PLATFORM_ENDPOINT, el valor predeterminado es el punto de conexión de producción.

Variables de observabilidad

Configure estas variables necesarias para habilitar el registro y el seguimiento distribuido para el agente. Más información sobre las características de observabilidad y los procedimientos recomendados

Nota

La configuración de observabilidad es la misma en todos los idiomas.

Variable Descripción Valor predeterminado Ejemplo
ENABLE_A365_OBSERVABILITY Habilitar o deshabilitar la observabilidad false true
ENABLE_A365_OBSERVABILITY_EXPORTER Exportar seguimientos al servicio de observabilidad false true
OBSERVABILITY_SERVICE_NAME Nombre del servicio para seguimiento Nombre del agente my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Espacio de nombres de servicio agent365-samples my-company-agents

Configuración del servidor de aplicaciones del agente

Configure el puerto donde se ejecuta el servidor de aplicaciones del agente. Esta configuración es opcional y se aplica a agentes de Python y JavaScript.

Agregue a su archivo .env:

# Server Configuration
PORT=3978
Variable Descripción Obligatorio Valor predeterminado Ejemplo
PORT Número de puerto donde se ejecuta el servidor del agente No 3978 3978

Instalar dependencias e inicio del servidor de aplicaciones del agente

Una vez configurado el entorno, debe instalar las dependencias necesarias e iniciar el servidor de aplicaciones del agente localmente para realizar pruebas.

Instalar dependencias

uv pip install -e .

Este comando lee las dependencias del paquete definidas en pyproject.toml y las instala desde PyPI. Al crear una aplicación de agente desde cero, debe crear un archivo pyproject.toml para definir las dependencias. Los agentes de ejemplo del repositorio de ejemplos ya tienen definidos estos paquetes. Puede agregarlos o actualizarlos según sea necesario.

Inicie el servidor de aplicaciones del agente

python <main.py>

Reemplace <main.py> por el nombre del archivo de Python principal que contiene el punto de entrada de la aplicación de agente (por ejemplo, start_with_generic_host.py, app.py o main.py).

O usando uv:

uv run python <main.py>

El servidor del agente ahora debe estar en ejecución y listo para recibir solicitudes desde el área de juegos de agentes o aplicaciones de Microsoft 365.

Probar el agente en el área de juegos de agentes

Área de juegos de agentes es una herramienta de pruebas local que simula el entorno de Microsoft 365 sin necesidad de una configuración completa del inquilino. Es la forma más rápida de validar la lógica y las invocaciones de herramientas del agente. Para obtener más información, consulte Probar con el área de juegos de agentes.

Nota

Cuando usas autenticación agente, actualmente no se soporta la mensajería directa en Agents Playground. Debes probar a través de actividades personalizadas en su lugar. Consulta Probar con actividades de notificación para más detalles.

Abra un nuevo terminal (PowerShell en Windows) e inicie El área de juegos de agentes:

agentsplayground

Este comando abre un navegador web con la interfaz de Agents Playground. La herramienta muestra una interfaz de chat en la que puede enviar mensajes al agente.

Prueba básica

Comience comprobando que el agente está configurado correctamente. Enviar un mensaje al agente:

What can you do?

El agente responde con las instrucciones con las que está configurado, basándose en el sistema y las capacidades de tu agente. Esta respuesta confirma que:

  • El agente se está ejecutando correctamente
  • El agente puede procesar mensajes y responder
  • La comunicación entre el área de juegos de agentes y el agente funciona

Invocaciones de la herramienta de prueba

Después de configurar los servidores de herramientas de MCP en toolingManifest.json (consulte Herramientas para obtener instrucciones de configuración), las invocaciones de herramientas de prueba con ejemplos como estos:

En primer lugar, compruebe qué herramientas están disponibles:

List all tools I have access to

A continuación, pruebe invocaciones de herramientas específicas:

Herramientas de correo

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Respuesta esperada: el agente envía un correo electrónico mediante el servidor MCP de correo y confirma que se envió el mensaje.

Herramientas de calendario

List my calendar events for today

Respuesta esperada: El agente recupera y muestra los eventos del calendario correspondientes al día actual.

Herramientas de SharePoint

List all SharePoint sites I have access to

Respuesta esperada: el agente consulta SharePoint y devuelve una lista de sitios a los que tiene acceso.

Puede ver las invocaciones de herramientas en:

  • La ventana de chat: vea la respuesta del agente y las llamadas a herramientas.
  • El panel: consulte información detallada de la actividad, incluidos los parámetros y respuestas de la herramienta.

Probar con actividades de notificación

Durante el desarrollo local, puede probar escenarios de notificación simulando actividades personalizadas en el Área de juegos de agentes. Esta simulación te permite verificar el manejo de notificaciones de tu agente antes de desplegarlo en producción.

Antes de probar las actividades de notificación, asegúrese de que:

Las notificaciones requieren tanto una configuración adecuada de las herramientas como una configuración adecuada de las notificaciones funcionen correctamente. Puede probar escenarios como notificaciones por correo electrónico o comentarios de Word mediante la característica de actividad personalizada.

Para enviar actividades personalizadas:

  1. Iniciar el agente en el Área de juegos de agentes
  2. En el Área de juegos de agentes, vaya a Simular una actividad>Actividad personalizada
  3. Copie el conversationId de la actividad (el id. de conversación cambia cada vez que se reinicia el Área de juegos de agentes)
  4. Pegue el JSON de la actividad personalizada y actualice el campo personal-chat-id con el id. de conversación que ha copiado. Consulte el ejemplo de notificación por correo electrónico
  5. Seleccione Enviar actividad
  6. Ver el resultado en la conversación de chat y en el panel de registro

Notificación por correo electrónico

Esta configuración simula un correo electrónico enviado al agente. Reemplazar los valores de marcador de posición por los detalles de agente reales:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Ver registros de observabilidad

Para ver los registros de observabilidad durante el desarrollo local, instrumente el agente con código de observabilidad (consulte Observabilidad para ejemplos de código) y configure las variables de entorno tal como se describe en Variables de observabilidad. Una vez configurados, los seguimientos en tiempo real aparecen en la consola que muestra:

  • Seguimientos de invocación de agente
  • Detalles de ejecución de herramienta
  • Llamadas de inferencia de LLM
  • Mensajes de entrada y salida
  • Uso de tokens
  • Tiempos de respuesta
  • Información de error

Estos registros ayudan a depurar problemas, comprender el comportamiento del agente y optimizar el rendimiento.

Solución de problemas

En esta sección se proporcionan soluciones a problemas comunes que pueden surgir al probar el agente localmente.

Problemas de conexión y de entorno

Estos problemas se relacionan con la conectividad de red, los conflictos de puertos y los problemas de configuración del entorno que pueden impedir que el agente se comunique correctamente.

Problemas de conexión del Área de juegos de agentes

Síntoma: el Área de juegos de agentes no se puede conectar al agente

Soluciones:

  • Comprobar que se está ejecutando el servidor del agente
  • Comprobar que los números de puerto coincidan entre el agente y el Área de juegos de agentes
  • Asegúrese de que no haya reglas de firewall que bloqueen las conexiones locales
  • Intente reiniciar tanto el agente como el Área de juegos de agentes

Versión del Área de juegos de agentes obsoleta

Síntoma: errores inesperados o características que faltan en el Área de juegos de agentes

Solución: desinstalar y reinstalar el Área de juegos de agentes:

winget uninstall agentsplayground
winget install agentsplayground

Conflictos de puertos

Síntoma: error que indica que ya se está usando el puerto

Solución:

  • Detener cualquier otra instancia del agente
  • Cambiar el puerto en su configuración
  • Finalizar procesos mediante el puerto:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

No se puede agregar DeveloperMCPServer

Síntoma: error al intentar agregar DeveloperMCPServer en VS Code

Solución: cierre y vuelva a abrir Visual Studio Code y, a continuación, vuelva a intentar agregar el servidor.

Problemas de autenticación.

Estos problemas se producen cuando el agente no se puede autenticar adecuadamente con los servicios de Microsoft 365 o cuando las credenciales han expirado o están mal configuradas.

Token de portador expirado

Síntoma: errores de autenticación o respuestas no autorizadas 401

Solución: los tokens de portador expiran después de aproximadamente 1 hora. Adquiera un nuevo token y actualice la configuración.

Errores de autenticación de agente en Python

Síntoma: error al adquirir el token de instancia de agente

Solución: compruebe la configuración ALT_BLUEPRINT_NAME en .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Problemas con las herramientas y las notificaciones

Estos problemas implican problemas con las invocaciones de herramientas, las interacciones del servidor MCP y la entrega de notificaciones.

Correo electrónico no recibido

Síntoma: el agente indica que se ha enviado el correo electrónico, pero usted no lo ha recibido

Soluciones:

  • Revisar su carpeta de correo no deseado
  • La entrega de correo electrónico puede retrasarse unos minutos: espere hasta 5 minutos.
  • Comprobar que la dirección de correo electrónico del destinatario sea correcta
  • Comprobar los registros del agente para detectar errores durante el envío de correo electrónico

Las respuestas de comentarios de Word no funcionan

Problema conocido: el servicio de notificaciones no puede responder directamente a los comentarios de Word. Se está desarrollando esta funcionalidad.

Los mensajes no llegan al agente

Síntoma: Los mensajes enviados al agente en Teams no son recibidos por tu solicitud de agente

Causas posibles:

  • Agente blueprint no configurado en el Portal de Desarrolladores
  • Problemas con Azure Web App (fallos de despliegue, aplicación que no se ejecuta, errores de configuración)
  • Instancia de agente no creada correctamente en Teams

Soluciones:

  1. Verificar configuración del Portal de Desarrolladores:

    Asegúrate de haber completado la configuración del blueprint del agente en el Portal de Desarrolladores. Consulta Configurar el plano del agente en el Portal de Desarrolladores para pasos detallados.

  2. Comprobar el estado de Azure Web App:

    Si tu agente está desplegado en Azure, verifica que la aplicación web funcione correctamente:

    1. Navigate to Azure Portal
    2. Ve a tu recurso de aplicación web
    3. Consultael estado> (debería mostrar "En marcha")
    4. Comprueba el flujo de registro en Monitorización para detectar errores en tiempo de ejecución
    5. Revisa los registros del Centro de Despliegue para verificar que el despliegue ha tenido éxito
    6. Verificar configuración>La configuración de la aplicación contiene todas las variables de entorno requeridas

  3. Verificar la creación de instancias del agente:

    Asegúrate de haber creado correctamente la instancia del agente en Microsoft Teams:

    1. Open Microsoft Teams
    2. Ve a Apps y busca a tu agente
    3. Verifica que el agente aparezca en los resultados de búsqueda
    4. Si no se encuentra, verifica que esté publicada en Microsoft 365 Admin Center - Agentes
    5. Crea una nueva instancia seleccionando Añadir a tu agente
    6. Para instrucciones detalladas, véase Agentes a bordo

Obtener ayuda

Si encuentra problemas que no se tratan en esta sección de solución de problemas, explore estos recursos:

Repositorios del SDK de Microsoft Agent 365

Más soporte técnico

Pasos siguientes

Después de probar con éxito tu agente localmente, estás listo para desplegarlo en Azure y publicarlo en Microsoft 365:

  • Despliega y publica agentes: Aprende cómo desplegar tu agente en Azure Web App y publicarlo en Microsoft Admin Center, poniéndolo a disposición de tu organización para descubrir y crear instancias de agentes en Microsoft 365.
  • Last updated on