Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Nota:
El área de juegos para agentes de Microsoft 365 (anteriormente conocida como Herramienta de prueba de aplicaciones de Teams) está disponible en la versión preliminar más reciente de Microsoft 365 Agents Toolkit (anteriormente conocido como Kit de herramientas de Teams). Asegúrese de instalar la versión preliminar más reciente de Agents Toolkit.
Agents Playground facilita la depuración de aplicaciones basadas en agentes o bots. Puede chatear con el bot y ver sus mensajes y tarjetas adaptables a medida que aparecen en diferentes canales. No necesita una cuenta de desarrollador de Microsoft 365, una tunelización o un registro real de aplicaciones y aplicaciones cliente para usar el área de juegos de agentes.
En la imagen siguiente se muestra una aplicación de ejemplo que muestra una tarjeta adaptable con una lista de comandos en el área de juegos de agentes. También proporciona una descripción de los comandos para que pueda probar la aplicación sin buscar manualmente el código:
A continuación se muestran las ventajas de Agents Playground:
Entorno de espacio aislado: el entorno de espacio aislado de Agents Playground emula el comportamiento, la apariencia y la experiencia del usuario del entorno real.
Tunelización: no es necesario un servicio de túnel externo, ya que Agents Playground se ejecuta en un servidor local con el que el bot puede comunicarse.
Reducir las dependencias de la cuenta: el inquilino del desarrollador de Microsoft 365 y los permisos de carga de aplicaciones no son necesarios para depurar la aplicación.
Iteraciones rápidas de bucle interno: optimiza el proceso de realizar cambios en el diseño de la aplicación y la lógica de la aplicación sin tener que volver a implementar la aplicación en la nube.
Datos ficticios y actividades: Agents Playground facilita la prueba de escenarios complejos, como el envío de un mensaje de bienvenida cuando un nuevo miembro se une al canal, mediante datos ficticios y desencadenadores de actividad.
Confiable: El área de juegos de agentes es confiable, ya que la tarjeta adaptable de la aplicación usa la misma tecnología de representación que en Teams o WebChat.
Integración con aplicaciones existentes: Agents Playground se integra sin esfuerzo con las aplicaciones existentes creadas con sdk de agente o biblioteca de inteligencia artificial de Teams.
Compatibilidad con diferentes ámbitos: Agents Playground admite pruebas en ámbitos de chat personales, de equipo y de grupo.
Requisitos previos
Asegúrese de instalar las siguientes herramientas para compilar e implementar las aplicaciones en Agents Playground:
| Instalar | Para usar... | |
|---|---|---|
| Kit de herramientas de agentes | Extensión de Microsoft Visual Studio Code que crea un scaffolding de proyecto para la aplicación. Use la versión preliminar más reciente. | |
| Node.js | Entorno de tiempo de ejecución de JavaScript de back-end. Para obtener más información, vea Node.js tabla de compatibilidad de versiones para el tipo de proyecto. | |
| Visual Studio Code | Entornos de compilación de JavaScript, TypeScript o SharePoint Framework (SPFx). Use la versión más reciente. |
Descripción del área de juegos de agentes
Agents Playground es un paquete npm que tiene un comando de la CLI denominado teamsapptester. Al ejecutar teamsapptester start, se abre una aplicación web en el equipo local que emula el cliente de Teams o WebChat y el servicio Bot Framework. Esta aplicación web no necesita ningún recurso en la nube, ya que usa datos ficticios para simular la información contextual.
Para usar una aplicación en Agents Playground, debe proporcionar lo siguiente:
- Punto de conexión de mensaje: un punto de conexión de mensaje es la dirección URL que vincula el área de juegos de agentes y la aplicación. Puede actualizar el punto de conexión con la
BOT_ENDPOINTvariable de entorno, iniciar Agents Playground con la opción--app-endpointo simplemente usar el valor predeterminado dehttp://localhost:3978/api/messages. - Archivo de configuración (opcional): un archivo de configuración informa a Agents Playground sobre la información contextual personalizada en Teams. El archivo se denomina .m365agentsplayground.yml en la carpeta raíz del proyecto. Si Teams no encuentra este archivo, usa la configuración predeterminada. Para obtener más información, consulte Personalización del contexto de Teams.
Experiencia de Agents Playground en Agents Toolkit
Agents Playground ofrece una experiencia de depuración más rápida para las aplicaciones en comparación con el entorno real.
Abrir Visual Studio Code.
Seleccione el icono microsoft 365 Agents Toolkit
en la barra de actividad de Visual Studio Code.Seleccione Crear una aplicación de Teams de agente o aplicación>.
Seleccione Agente para Teams.
Seleccione Agente básico para Teams. Si necesita una funcionalidad diferente para el agente, elija una opción diferente.
Seleccione Azure OpenAI y escriba la clave de servicio. Si usa OpenAI, elija otra opción.
Seleccione JavaScript.
Seleccione Carpeta predeterminada.
Para cambiar la ubicación predeterminada, siga estos pasos:
Seleccione Examinar.
Seleccione la ubicación del área de trabajo del proyecto.
Seleccione Seleccionar carpeta.
Escriba un nombre adecuado para la aplicación y, a continuación, seleccione la tecla Entrar .
Aparece un cuadro de diálogo en el que debe elegir sí o no para confiar en los autores de los archivos de esta carpeta.
En el panel izquierdo, seleccione Ejecutar y depurar (
Ctrl+Shift+D) y seleccione Depurar en el área de juegos de agentes de Microsoft 365 (versión preliminar) en la lista desplegable.
Agents Playground abre la aplicación en una página web.
Desencadenadores de actividad
Puede simular una actividad en el área de juegos de agentes mediante desencadenadores de actividad. Hay dos tipos de desencadenadores de actividad:
Desencadenadores de actividad predefinidos
Agents Playground proporciona desencadenadores de actividad predefinidos para probar las funcionalidades de la aplicación.
| Categoría | Actividad | Controlador |
|---|---|---|
| Actividad de actualización de instalación del desencadenador | Instalación de la aplicación Desinstalación de la aplicación |
onInstallationUpdate onInstallationUpdateAdded onInstallationUpdate onInstallationUpdateRemove |
| Desencadenar actividad de actualización de conversación | Agregar usuario Agregar aplicación Agregar canal |
onMembersAddedonTeamsMembersAddedEvent onTeamsChannelRenamedEvent |
| Quitar usuario Quitar aplicación Quitar canal Quitar equipo |
onMembersRemoved onTeamsMembersRemovedEvent onMembersRemoved onTeamsMembersRemovedEvent onTeamsChannelDeletedEvent onTeamsTeamDeletedEvent |
|
| Cambiar el nombre del canal Cambiar el nombre del equipo |
onTeamsChannelRenamedEvent onTeamsTeamRenamedEvent |
Nota:
Todos los tipos de actividades no están disponibles en todos los ámbitos. Por ejemplo, no puede agregar ni quitar un canal en un chat personal o un chat de grupo.
Los desencadenadores de actividad predefinidos están disponibles en el menú Simular una actividad en el área de juegos de agentes.
Para simular una actividad Agregar usuario , siga estos pasos:
En El área de juegos de agentes, vaya a Simular una actividad y seleccione Agregar usuario.
Aparece una ventana emergente para obtener una vista previa del controlador de actividad.
Seleccione Enviar actividad.
La aplicación envía una respuesta.
Desencadenadores de actividad personalizados
Puede usar la actividad Personalizada para personalizar desencadenadores de actividad como, reactionsAdded, para ajustarse a los requisitos de la aplicación de bot. El área de juegos de agentes rellena automáticamente las propiedades necesarias de la actividad. También puede modificar el tipo de actividad y agregar más propiedades.
Seleccione Simular unaactividad personalizada de actividad>.
Agregue
messageReactionpara personalizar la actividad en la propiedadtypee invocar la actividad personalizada.{ "type": "messageReaction", "reactionsAdded": [ { "type": "like" } ], "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47" }Seleccione Enviar actividad.
El bot envía un
onReactionsAddedcontrolador en respuesta.
Configuración del área de juegos de agentes para la autenticación
Al depurar una aplicación que requiere autenticación, puede configurar el identificador de cliente Microsoft Entra y el secreto de cliente, con un identificador de inquilino opcional. Si ha creado el bot mediante la Bot Service de Azure AI, las credenciales estarán disponibles en el App Service del bot en Configuración>. Si no está seguro de los valores, puede quitarlos del archivo de configuración de la aplicación en ejecución local y, a continuación, ejecutar la aplicación en el área de juegos de agentes. Si la aplicación no requiere que se ejecuten estas opciones, no es necesario configurarlas.
Variable de entorno/línea de comandos
Antes de iniciar el área de juegos de agentes, puede establecer las siguientes variables de entorno: AUTH_CLIENT_ID, AUTH_CLIENT_SECRETy AUTH_TENANT_ID. Estos valores se usan para la configuración de autenticación predeterminada.
Al ejecutar Agents Playground desde la línea de comandos, también puede usar las opciones : --client-id, --client-secrety --tenant-id. Estas opciones invalidan la configuración predeterminada de la variable de entorno.
Interfaz del lado cliente
Una vez que se haya iniciado Agents Playground, puede configurar la autenticación a través de la interfaz de cliente de la siguiente manera:
Seleccione Configurar autenticación.
Rellene los campos del formulario y seleccione Guardar.
El panel de registro muestra el mensaje si la configuración se ha establecido correctamente.
Lógica de autenticación
Agents Playground adquiere un token JWT mediante la configuración de autenticación proporcionada e lo incluye en el encabezado Authorization al comunicarse con la aplicación. El token JWT del encabezado de respuesta de la aplicación también es validado por Agents Playground. Para obtener más información sobre el proceso de autenticación, consulte Autenticación con Bot Connector API.
Compatibilidad con varios canales
Teams es el canal predeterminado que se usa para depurar la aplicación, pero también se admiten otros canales. Para cambiar el canal, establezca la DEFAULT_CHANNEL_ID variable de entorno o use la --channel-id opción al iniciar El área de juegos de agentes desde la línea de comandos.
Actualmente, los identificadores de canal aceptados son: msteams, directline, webchaty emulator. Al establecer un identificador de canal, las propiedades de los mensajes enviados a la aplicación cambian en consecuencia para simular un entorno real. Para los directline canales y webchat , se muestra un cliente correspondiente y la representación de tarjetas difiere de la del canal de Teams.
Personalización del contexto de Teams
El archivo de configuración de la carpeta raíz del proyecto permite personalizar la información de contexto de Teams, como chats, equipos y usuarios. Proporciona datos ficticios para probar las API o métodos de Bot Framework desde el SDK del agente o la biblioteca de inteligencia artificial de Teams, como TeamsInfo.getTeamMembers.
Configuración predeterminada
El área de juegos de agentes contiene un archivo de configuración integrado en la carpeta raíz del proyecto.
# yaml-language-server: $schema=https://aka.ms/teams-app-test-tool-config/0.1.0/config.schema.json
# Visit https://aka.ms/teams-app-test-tool-config-guide for more details on this file.
# This configuration file customizes the Teams context information like chats, teams, and users.
# It contains mock data for testing Bot Framework APIs or Bot Builder SDK methods such as TeamsInfo.getTeamMembers().
# You can customize this file to change API response if your bot code uses these APIs.
version: "0.1.0"
tenantId: 00000000-0000-0000-0000-0000000000001
bot:
id: 00000000-0000-0000-0000-00000000000011
name: Test Bot
currentUser:
id: user-id-0
name: Alex Wilber
userPrincipleName: alexw@example.com
aadObjectId: 00000000-0000-0000-0000-0000000000020
givenName: Alex
surname: Wilber
email: alexw@example.com
users:
- id: user-id-1
name: Megan Bowen
userPrincipleName: meganb@example.com
aadObjectId: 00000000-0000-0000-0000-0000000000021
givenName: Megan
surname: Bowen
email: meganb@example.com
- id: user-id-2
name: Adele Vance
userPrincipleName: adelev@example.com
aadObjectId: 00000000-0000-0000-0000-0000000000022
givenName: Adele
surname: Vance
email: adelev@example.com
- id: user-id-3
name: Isaiah Langer
userPrincipleName: isaiah@example.com
aadObjectId: 00000000-0000-0000-0000-0000000000023
givenName: Isaiah
surname: Langer
email: isaiahl@example.com
- id: user-id-4
name: Patti Fernandez
userPrincipleName: pattif@example.com
aadObjectId: 00000000-0000-0000-0000-0000000000024
givenName: Patti
surname: Fernandez
email: pattif@example.com
- id: user-id-5
name: Lynne Robbins
userPrincipleName: lynner@example.com
aadObjectId: 00000000-0000-0000-0000-0000000000025
givenName: Lynne
surname: Robbins
email: lynner@example.com
personalChat:
id: personal-chat-id
groupChat:
id: group-chat-id
name: Group Chat
team:
id: team-id
name: My Team
aadGroupId: 00000000-0000-0000-0000-000000000031
channels:
- id: channel-announcements-id
name: Announcements
Actualización del archivo de configuración
Si el código del bot usa las API de Bot Framework, puede modificar el archivo de configuración para personalizar las respuestas de la API. Por ejemplo, considere la posibilidad de instalar un bot de notificación de Azure DevOps en un equipo que capture errores inactivos de Azure DevOps. Identifica a los propietarios de los errores inactivos, recupera sus direcciones de correo electrónico y envía notificaciones diarias a sus chats personales.
Para probar exhaustivamente este bot en Agents Playground, asegúrese de actualizar el archivo de configuración con las direcciones de correo electrónico correctas de los propietarios de errores inactivos.
Vaya al
.m365agentsplayground.ymlarchivo de la carpeta raíz del proyecto.Vaya a la
userssección y actualice ,nameuserPrincipleNameyemaildel usuario necesario.users: - id: user-id-1 name: Megan Bowen userPrincipleName: meganb@example.com aadObjectId: 00000000-0000-0000-0000-0000000000021 givenName: Megan surname: Bowen email: some-real-user@real-domain.onmicrosoft.comGuarde el archivo y seleccione F5 para depurar en el área de juegos de agentes.
Nota:
Al editar el archivo de configuración en Visual Studio Code, Intellisense actualiza automáticamente los nombres de propiedad y le advierte si escribe valores no válidos.
Es importante comprender que la actualización del archivo de configuración tiene tres impactos importantes:
- Afecta a las respuestas devueltas por las API de Bot Framework Connector. Por ejemplo,
TeamsInfo.getPagedMembers(). - Modifica los detalles de la carga de actividad. Por ejemplo,
activity.recipient. - Influye en la interfaz de usuario de Agents Playground. Por ejemplo, nombres de chat de grupo.
Limitaciones
Las características de bot o agente habilitadas a través del manifiesto de aplicación de Teams no están disponibles, ya que Agents Playground no lo procesa.
El área de juegos de agentes no admite todos los tipos de tarjetas excepto las tarjetas adaptables.
Agents Playground no admite las siguientes características de tarjeta adaptable:
Agents Playground no admite las siguientes experiencias:
- Móvil
- Reunión
Agents Playground puede emular las siguientes experiencias:
Características Depuración en el área de juegos de agentes Depurar la aplicación localmente Envío y recepción de mensajes básicos Disponible Disponible API de Bot Framework (TeamsInfo.getPagedMembers()...) Disponible (responder con datos ficticios) Disponible Envío de eventos de Teams Disponible (actividad simulada) Disponible Indicador de escritura Not Available Disponible Pestaña, Extensión de mensaje, Diálogos (denominados módulos de tareas en TeamsJS v1.x), Inicio de sesión único (SSO) y Tarjetas no adaptables Not Available Disponible
Depuración de una aplicación existente con Agents Playground
Asegúrese de que tiene una aplicación existente creada mediante Agents Toolkit. Para depurar la aplicación con Agents Playground, siga estos pasos:
Abra la carpeta del proyecto del bot existente en Agents Toolkit.
Vaya a EXPLORER.vscode>.
Seleccione launch.json y agregue el código siguiente al final del archivo:
// .vscode/launch.json { ... "compounds": [ ... { "name": "Debug in Microsoft 365 Agents Playground", "configurations": [ "Attach to Local Service" ], "preLaunchTask": "Start App in Microsoft 365 Agents Playground", "presentation": { "group": "1-local", "order": 1 }, "stopAll": true }, ] }Vaya a tasks.json y agregue el código siguiente al final del archivo:
{ "label": "Start Microsoft 365 Agents Playground", "type": "shell", "command": "npm run dev:teamsfx:launch-playground", "isBackground": true, "options": { "env": { "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin:${env:PATH}" } }, "windows": { "options": { "env": { "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin;${env:PATH}" } } }, "problemMatcher": { "pattern": [ { "regexp": "^.*$", "file": 0, "location": 1, "message": 2 } ], "background": { "activeOnStart": true, "beginsPattern": ".*", "endsPattern": "Listening on" } }, "presentation": { "panel": "dedicated", "reveal": "silent" } }, ], }En EXPLORER, cree un archivo .localConfigs.playground y agregue el código siguiente:
// .localConfigs.playground # A gitignored place holder file for local runtime configurations when debug in Agents Playground BOT_ID= BOT_PASSWORD= TEAMSFX_NOTIFICATION_STORE_FILENAME=.notification.playgroundstore.jsonVaya a EXPLORADOR>env.
Cree un archivo .env.playground y agregue el código siguiente:
// .env.playground # This file includes environment variables that can be committed to git. It's gitignored by default because it represents your local development environment # Built-in environment variables TEAMSFX_ENV=playground # Environment variables used by Agents Playground TEAMSAPPTESTER_PORT=56150Si tiene variables de entorno personalizadas, establezca sus valores en .env.playground o .env.playground.user.
Agregue una clave OpenAI o una clave y un punto de conexión de Azure OpenAI en .env.playground.user.
# SECRET_OPENAI_API_KEY=*********** SECRET_AZURE_OPENAI_API_KEY=*********** SECRET_AZURE_OPENAI_ENDPOINT=<https://your-openai-service-name.openai.azure.com/>Vaya a package.json y agregue el código siguiente en la
scriptspropiedad :"scripts": { ... "dev:teamsfx:playground": "env-cmd --silent -f .localConfigs.playgroundnd npm run dev", "dev:teamsfx:launch-playground": "env-cmd --silent -f env/.env.playground teamsapptester start", ... },En el panel izquierdo, seleccione Ejecutar y depurar (
Ctrl+Shift+D) y seleccione Depurar en el área de juegos de agentes de Microsoft 365 en la lista desplegable.
Agents Playground depura correctamente el bot existente.
Deshabilitación de la recopilación de datos
Si decide que no quiere permitir que Agents Playground recopile datos de uso, puede deshabilitar fácilmente la recopilación de datos agregando la opción --disable-telemetry al iniciar Agents Playground a través de la línea de comandos.
Preguntas más frecuentes
¿Cómo puedo probar mi aplicación si Agents Playground no admite sus características?
Siempre puede usar el cliente de Teams para probar las características que Agents Playground no admite. Seleccione la opción Depurar en Teams (Edge) o Depurar en Teams (Chrome) para probar la aplicación en el cliente de Teams.
¿Cómo sabría si Agents Playground no admite características en mi aplicación?
Agents Playground muestra un mensaje de advertencia en el panel de conversación y registro cuando detecta características no admitidas.
¿Microsoft recomienda usar solo Agents Playground para probar aplicaciones?
No. Siempre recomendamos a los usuarios que prueben sus aplicaciones en el cliente de Teams antes de mover la aplicación al entorno de producción.
Ejemplo de código
| Ejemplo de nombre | Descripción | Node.js |
|---|---|---|
| Aplicación de ejemplo del área de juegos de agentes | Una aplicación de ejemplo para explorar el área de juegos de agentes. | View |
Guía paso a paso
Siga la guía paso a paso para depurar un bot de chat de inteligencia artificial mediante Agents Playground.
Vea también
Colaborar con nosotros en GitHub
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.