Prueba agentes usando el Microsoft Agent 365 SDK

Prueba tu agente localmente usando Agents Playground antes de desplegar. Esta guía trata sobre cómo configurar tu entorno de desarrollo, configurar la autenticación y validar la funcionalidad de tu agente utilizando la herramienta de pruebas Agents Playground.

Una vez que el agente funcione localmente, puede seguir el ciclo de vida de desarrollo de Agent 365 para probar en aplicaciones Microsoft 365 como Teams, Word y Outlook.

Requisitos previos

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

Requisitos previos comunes

• Editor de código: cualquier editor de código que elija. se recomienda Visual Studio Code.
• Agents Playground: Instala Agents Playground utilizando uno de los siguientes métodos:
  • Windows: winget install agentsplayground
  • npm:
• A365 CLI: necesaria para la implementación y administración del agente. Instala la CLI del Agente 365.
• Acceso a la API de LLM: elija el servicio adecuado en función de la configuración del agente o del proveedor de modelos preferido:
  • Clave API de OpenAI: Obtén tu clave API de OpenAI.
  • Azure OpenAI: Crear e implementar un recurso de OpenAI Azure para obtener la clave de API y el punto de conexión.
• Configuración del portal para desarrolladores: Tras publicar tu agente, debes configurar el blueprint del agente en el Portal de Desarrolladores antes de crear instancias. Aprende cómo configurar el plan del agente en el Portal de Desarrolladores

Requisitos previos específicos de idioma

Configurar el entorno de pruebas del agente

Esta sección describe cómo establecer variables de entorno, autenticar tu entorno de desarrollo y preparar tu agente impulsado por Agent 365 para las pruebas.

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

1. Configura tu entorno - Crea o actualiza tu archivo de configuración de entorno.

2. configuración de LLM - Obtener claves de API y configurar OpenAI o configuraciones de OpenAI de Azure.

3. Configurar autenticación - Configurar autenticación agéntica.

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 Espacio para Pruebas de Agentes.

Paso 1: Configuración del entorno

Configure su archivo de configuración:

cp .env.template .env

cp .env.template .env

Paso 2: Configuración de LLM

Configurar la configuración de OpenAI o Azure OpenAI para pruebas en local. Añade tus claves API y puntos finales de servicio de los requisitos previos a tu archivo de configuración junto con cualquier parámetro de modelo.

# 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=

# 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=

{
  "AIServices": {
    "AzureOpenAI": {
      "DeploymentName": "", // Deployment (as opposed to model) name of the Azure OpenAI model
      "Endpoint": "", // Endpoint of the Azure OpenAI model deployment
      "ApiKey": "" // API Key of the Azure OpenAI model deployment
    },
    "OpenAI": {
      "ModelId": "", // Model ID of the OpenAI model
      "ApiKey": "" // API Key of the OpenAI model
    },
    "UseAzureOpenAI": true // Flag to use Azure OpenAI vs OpenAI
  }
}

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 : Úsalo para escenarios de producción cuando hay una identidad de usuario agente disponible.
• Autenticación OBO - Úsalo para escenarios de producción cuando necesitas permisos de usuario delegados sin una identidad agente de usuario.
• Autenticación de token portador - Úsalo solo para escenarios de desarrollo y pruebas iniciales antes de configurar la autenticación en producción.

Autenticación agentica

Utiliza el comando CLI Agent 365 para obtener tus credenciales de plano de agente.

a365 config display -g

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

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

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

USE_AGENTIC_AUTH=true
connections__service_connection__settings__clientId=<agentBlueprintId>
connections__service_connection__settings__clientSecret=<agentBlueprintClientSecret>
connections__service_connection__settings__tenantId=<your-tenant-id>

{
  "AgentBluePrint": {
    "Settings": {
      "ClientId": "<agentBlueprintId>",
      "ClientSecret": "<agentBlueprintClientSecret>",
      "TenantId": "<your-tenant-id>"
    }
  }
}

Autenticación OBO

La autenticación On-Behalf-Of (OBO) permite a tu agente acceder a las herramientas del servidor MCP utilizando permisos de usuario delegados sin requerir una identidad de usuario agente. En este flujo, el agente recibe el token delegado por el usuario y lo intercambia para realizar acciones en nombre del usuario.

La autenticación OBO es adecuada para escenarios de producción donde:

• Tu agente no tiene una identidad de usuario agente.
• Necesitas acceder a recursos con permisos específicos de cada usuario.
• Quieres que el agente actúe en nombre del usuario autenticado.

Para más detalles 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 SDK de agentes de Microsoft 365.

Autenticación por token de portador

Para escenarios iniciales de desarrollo y pruebas cuando la autenticación en producción no está configurada, usa la autenticación con token portador para probar tu agente. Este método utiliza autenticación interactiva del navegador para obtener un token de acceso delegado. Al usar este token, tu agente puede llamar a las herramientas del servidor MCP usando tus permisos de usuario. Este enfoque simula cómo un usuario agente accede a recursos en producción sin necesidad de una instancia real de agente.

Primero, usa para añadir los permisos necesarios del servidor MCP a tu aplicación:

a365 develop add-permissions

Luego, se utiliza para recuperar y configurar los tokens portadores:

a365 develop get-token

El comando realiza automáticamente:

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

Antes de ejecutar , configure el archivo de configuración del proyecto para que el comando sepa dónde guardar el token:

• .NET: agregue "BEARER_TOKEN": "" a environmentVariables en cada perfil de Properties/launchSettings.json. El comando solo actualiza los perfiles que ya tienen esta clave definida.
• Python/Node.js: cree un archivo .env con BEARER_TOKEN= antes de ejecutarlo. Si falta el archivo, el comando omite guardar y muestra instrucciones.

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: configuración necesaria para la autenticación de agente
• Configuración del punto de conexión de MCP: especifique el punto de conexión de la plataforma de Agent 365.
• Variables de observabilidad: habilite el registro y el seguimiento distribuido
• Configuración del servidor de aplicaciones del agente: configure el puerto donde se ejecuta el servidor del agente.

Variables de autenticación

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

# 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

# Agentic Authentication Options
agentic_type=agentic
agentic_altBlueprintConnectionName=service_connection
agentic_scopes=ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default

# Set service connection as default
connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

{
  "AgentApplication": {
    "StartTypingTimer": false,
    "RemoveRecipientMention": false,
    "NormalizeMentions": false,
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": {
            "Scopes": [
              "https://graph.microsoft.com/.default"
            ]
          }
        }
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]
}

Configuración de puntos de conexión MCP

Especifica el punto final de la plataforma Agent 365 al que se conecta tu agente. Cuando generes el manifiesto de herramientas que define los servidores de herramientas para tu agente, especifica el endpoint de la plataforma MCP. Este punto de conexión determina a qué entorno (preprod, test o producción) se conectan los servidores de herramientas de MCP para las capacidades de integración de Microsoft 365.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

{
  "profiles": {
    "Sample Agent": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MCP_PLATFORM_ENDPOINT": "<MCP endpoint>"
      },
      "applicationUrl": "https://localhost:64896;http://localhost:64897"
    }
  }
}

Variables de observabilidad

Configure estas variables necesarias para habilitar el registro y el seguimiento distribuido para el agente. Aprende más sobre las características de observabilidad y las mejores prácticas.

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 Python y a los agentes de JavaScript.

# Server Configuration
PORT=3978

# Server Configuration
PORT=3978

Instalar dependencias e inicio del servidor de aplicaciones del agente

Después de configurar tu entorno, instala las dependencias necesarias y inicia el servidor de aplicaciones del agente localmente para las pruebas.

Instalar dependencias

uv pip install -e .

python <main.py>

uv run python <main.py>

npm install

npm run dev

dotnet restore

dotnet build

dotnet run --launch-profile "Sample Agent with MCP Platform"

El servidor del agente ya se está ejecutando y está listo para recibir solicitudes desde el área de juegos de agentes o las aplicaciones de Microsoft 365.

Probar el agente en el área de juegos de agentes

Agents Playground es una herramienta de prueba 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 Test with Agents Playground.

Configurar Agents Playground para la autenticación agentica

Al usar autenticación agente, configura el archivo YAML de Agents Playground con los datos de tu agente:

1. Configura el archivo de configuración: Crea o actualiza el archivo en la carpeta donde ejecutas Agents Playground. Para instrucciones detalladas de configuración, consulta el contexto de Personalizar Teams.

2. Actualiza la configuración del bot: Añade los siguientes datos del bot a tu archivo, reemplazando los valores provisionales por tus credenciales reales de agente:

   bot:
     id: <your-agent-email>@<your-tenant>.onmicrosoft.com
     name: <Your Agent Name>
     role: agenticUser
     agenticUserId: <your-agentic-user-id>
     agenticAppId: <your-agentic-app-id>
   

   Propiedad	Descripción	Obligatorio
   id	La dirección de correo electrónico de usuario de tu agente en el formato	Sí
   name	Nombre visual para tu usuario agente	Sí
   role	Debe estar configurado en [valor] para la autenticación agencial	Sí
   agenticUserId	El ID del objeto del usuario agente. Busque este valor en el centro de administración de Microsoft Entra en la página de perfil del usuario del agente.	Sí
   agenticAppId	El ID de agente del usuario asignado. Busque este valor en el centro de administración de Microsoft Entra en la página de perfil del usuario del agente.	Sí

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 la solicitud del sistema y las capacidades de tu agente. Esta respuesta confirma que:

• Tu agente está funcionando correctamente.
• El agente puede procesar mensajes y responder.
• La comunicación entre el Agente Playground y tu agente está funcionando.

Invocaciones de la herramienta de prueba

Después de configurar tus servidores de herramientas MCP en (ver Herramientas para instrucciones de configuración), prueba las invocaciones de herramientas usando ejemplos como estos:

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

List all tools I have access to

Luego, prueba invocaciones específicas de herramientas:

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 usando el servidor Mail MCP y confirma que el mensaje se ha enviado.

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:

• En la ventana de chat, puede ver las respuestas del agente y las interacciones con herramientas.
• El panel de registro: vea 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, prueba los escenarios de notificación utilizando los disparadores de notificación integrados en Agents Playground.

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

• Configura los servidores de herramienta MCP necesarios en tu sistema. Más información acerca de las herramientas
• Activa las notificaciones para tu agente. Aprende cómo configurar notificaciones
• Configura el archivo con los detalles de autenticación de agente de tu agente, tal como se describe en Configure Agents Playground para la autenticación de agente.

Notificaciones de correo electrónico de prueba

Para probar la gestión de notificaciones por correo electrónico:

1. Empieza tu Patio de Agentes y Agentes.
2. En el Playground de Agentes, ve a Mock una actividad que activa la notificación ActivityTrigger.
3. Seleccione Enviar correo electrónico.
4. En el cuadro de diálogo de payload, actualiza los detalles del correo simulado, como el nombre del remitente y el contenido del cuerpo del correo, según sea necesario.
5. Seleccione Enviar actividad.
6. Consulta el resultado tanto en la conversación del chat como en el panel de registros.

El agente recibe una notificación simulada por correo electrónico y la procesa según tu lógica de gestión de notificaciones. Para más detalles sobre la estructura de la carga útil de notificación por correo electrónico, consulte Carga útil de notificación por correo electrónico.

Notificaciones de mención de prueba de Word

Para probar las notificaciones de mención en documentos de Word:

1. Empieza tu Patio de Agentes y Agentes.
2. En el Playground de Agentes, ve a Mock una actividad que activa la notificación ActivityTrigger.
3. Seleccione Mention en Word.
4. En el cuadro de diálogo de payload, actualiza los detalles de los comentarios simulados como el id del documento y el texto del comentario según sea necesario.
5. Seleccione Enviar actividad.
6. Consulta el resultado tanto en la conversación del chat como en el panel de registros.

El agente recibe una notificación simulada de mención de Word y responde según tu lógica de manejo de notificaciones. Para obtener más información sobre la estructura de carga de notificación de comentarios de Word, consulte Document comment notification payload.

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 configurado, aparecen trazas en tiempo real en la consola que muestran:

• Trazas 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 te ayudan a depurar problemas, entender el comportamiento del agente y optimizar el rendimiento.

Pasos siguientes

Después de probar correctamente el agente localmente, está listo para implementarlo en Azure y publicarlo en Microsoft 365.

Siga el ciclo de vida de desarrollo de Agent 365 para probar en aplicaciones de Microsoft 365 como Teams, Word y Outlook.

Solución de problemas

Esta sección ofrece soluciones a problemas comunes que puedas encontrar al evaluar a tu agente localmente.

Problemas de conexión y entorno

Estos problemas están relacionados con la conectividad de red, conflictos de puertos y problemas de configuración del entorno que pueden impedir que tu agente se comunique correctamente.

Problemas de conexión con Agents Playground

Síntoma: El Playground de los agentes no puede conectarse con tu agente.

Soluciones:

• Verifica que tu servidor agente esté funcionando.
• Comprueba que los números de puerto coincidan entre tu agente y Agents Playground.
• Asegúrate de que no haya reglas de cortafuegos que bloqueen las conexiones locales.
• Prueba a reiniciar tanto el Patio de Juegos del Agente como el del Agente.

Versión del Área de juegos de agentes obsoleta

Síntoma: Errores inesperados o funciones ausentes en Agents Playground.

Solución: Desinstalar y reinstalar Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Conflictos de puertos

Síntoma: El puerto indicador de error ya está en uso.

Solución:

• Detén cualquier otra instancia de tu agente.
• Cambia el puerto en tu configuración.
• Elimina cualquier proceso que use el puerto.

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

No se puede agregar DeveloperMCPServer

Síntoma: Error al intentar añadir DeveloperMCPServer en VS Code.

Solution: cierre y vuelva a abrir Visual Studio Code y vuelva a intentar agregar el servidor.

Autenticación y problemas de token

Estos problemas se producen cuando el agente no se puede autenticar correctamente con Microsoft 365 servicios o cuando las credenciales expiran o están mal configuradas.

Síntomas:

• Errores no autorizados 401
• Mensajes de "Token de portador expirado"
• Fallos de autenticación agéntica

Causa principal:

• Los tokens caducan tras aproximadamente una hora
• Configuración incorrecta de autenticación
• Falta o credenciales no válidas

Soluciones:

• Para el vencimiento del token de portador

  Actualiza tu token y actualiza tus variables de entorno.

  # Get a new token
  a365 develop get-token
  
  # Update your .env file with the new token
  

• Para errores de autenticación agente (Python)

  Revisa tu expediente:

  # Should be (with underscore):
  AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION
  
  # Not:
  AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection
  

• Por falta de credenciales

  Confirma que las credenciales requeridas estén presentes antes de hacer la prueba.

  Asegúrese de que contenga:

  • Claves y secretos API
  • Id. de inquilino
  • Id. de cliente
  • ID de plan maestro (si se utiliza autenticación de agente)

  Comprobación:

  Prueba con una solicitud sencilla en Agents Playground. Deberías recibir una respuesta sin errores 401.

• Problemas con herramientas y notificaciones

  Estos problemas implican incidencias con la invocación de herramientas, interacciones con servidores MCP y 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:

• Revisa tu carpeta de Correo no deseado o Spam.
• La entrega del correo electrónico puede retrasarse unos minutos. Espera hasta cinco minutos.
• Verifica que la dirección de correo electrónico del destinatario sea correcta.
• Revisa los registros de los agentes para detectar errores durante el envío de correos.

Respuestas a comentarios de Word que no funcionan

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

Los mensajes no llegan al agente

Síntoma: Tu aplicación de agente no recibe mensajes que se envían al agente en Teams.

Causas posibles:

• El Portal para desarrolladores no está configurado con el blueprint del agente.
• Azure problemas de aplicación web (errores de implementación, aplicación no en ejecución, errores de configuración).
• La instancia del agente no se crea correctamente en Teams.

Soluciones:

• Verificar configuración del Portal de Desarrolladores:

  Asegúrate de completar la configuración del plano del agente en el Portal de Desarrolladores. Aprende a configurar el plano del agente en el Portal de Desarrolladores.

• Verificar la salud de la aplicación web de Azure:

  Si implementa el agente en Azure, compruebe que la aplicación web se está ejecutando correctamente:

  1. Vaya al portal Azure.
  2. Ve a tu recurso de aplicación web.
  3. Consulta el estado de OverviewStatus (debería mostrar "En funcionamiento").
  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 que la configuración de la aplicación contiene todas las variables de entorno requeridas.

• Verificar la creación de instancias del agente:

  Asegúrese de crear correctamente la instancia del agente en Microsoft Teams:

  1. Abra 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, compruebe que está publicado en Microsoft 365 centro de administración: Agentes.
  5. Crea una nueva instancia seleccionando Añadir a tu agente.
  6. Para instrucciones detalladas, véase Agentes a bordo.