Microsoft 365 Agents Playground

Agents Playground permet de déboguer facilement des applications basées sur un bot ou un agent. Vous pouvez discuter avec votre bot et voir ses messages et cartes adaptatives tels qu’ils apparaissent dans différents canaux. Vous n’avez pas besoin d’un compte de développeur Microsoft 365, d’un tunneling ou d’une inscription d’application cliente et d’application réelle pour utiliser Agents Playground.

L’image suivante montre un exemple d’application affichant une carte adaptative avec une liste de commandes dans Agents Playground. Il fournit également une description des commandes afin que vous puissiez tester votre application sans rechercher manuellement dans votre code :

Voici les avantages d’Agents Playground :

• Environnement de bac à sable : l’environnement de bac à sable d’Agents Playground émule le comportement, l’apparence et l’expérience utilisateur du vrai.

• Tunneling : un service de tunnel externe n’est pas nécessaire, car Agents Playground s’exécute sur un serveur local avec lequel votre bot peut communiquer.

• Réduire les dépendances de compte : le locataire Microsoft 365 Developer et les autorisations de chargement de l’application ne sont pas nécessaires pour déboguer l’application.

• Itérations rapides de boucle interne : optimise le processus de modification de la conception de l’application et de la logique d’application sans avoir à redéployer l’application dans le cloud.

• Données et activités fictives : Agents Playground facilite le test de scénarios complexes tels que l’envoi d’un message de bienvenue lorsqu’un nouveau membre rejoint le canal, à l’aide de données fictives et de déclencheurs d’activité.

• Fiable : Agents Playground est fiable, car la carte adaptative de l’application utilise la même technologie de rendu que dans Teams ou WebChat.

• Intégration avec des applications existantes : Agents Playground s’intègre facilement aux applications existantes créées avec le SDK Agent ou le SDK Teams.

• Prise en charge de différentes étendues : Agent Playground prend en charge les tests dans les étendues de conversation personnelle, d’équipe et de groupe.

Configuration requise

Veillez à installer les outils suivants pour générer et déployer vos applications dans Agents Playground :

Comprendre le terrain de jeu des agents

Agents Playground est un package npm qui a une commande CLI appelée teamsapptester. Lorsque vous exécutez teamsapptester start, il ouvre une application web sur votre ordinateur local qui émule le client Teams ou WebChat et le service Bot Framework. Cette application web n’a pas besoin de ressources cloud, car elle utilise des données fictives pour simuler les informations contextuelles.

Pour utiliser une application sur Agents Playground, vous devez fournir :

• Point de terminaison de message : un point de terminaison de message est l’URL qui lie Agents Playground à votre application. Vous pouvez mettre à jour le point de terminaison avec la BOT_ENDPOINT variable d’environnement, démarrer Agents Playground avec l’option --app-endpointou simplement utiliser la valeur par défaut de http://localhost:3978/api/messages.
• Fichier de configuration (facultatif) : un fichier de configuration informe Agents Playground de vos informations contextuelles personnalisées dans Teams. Le fichier est nommé .m365agentsplayground.yml dans le dossier racine du projet. Si Teams ne trouve pas ce fichier, il utilise la configuration par défaut. Pour plus d’informations, consultez Personnaliser le contexte Teams.

Expérience Agents Playground dans le Kit de ressources Agents

Agents Playground offre une expérience de débogage plus rapide pour les applications par rapport à l’environnement réel.

Déclencheurs d’activité

Vous pouvez simuler une activité dans Agents Playground à l’aide de déclencheurs d’activité. Il existe deux types de déclencheurs d’activité :

1. Déclencheurs d’activité prédéfinis
2. Déclencheurs d’activité personnalisés

Déclencheurs d’activité prédéfinis

Agents Playground fournit des déclencheurs d’activité prédéfinis pour tester les fonctionnalités de votre application.

Les déclencheurs d’activité prédéfinis sont disponibles dans le menu Simuler une activité dans Agents Playground.

Pour simuler une activité Ajouter un utilisateur , procédez comme suit :

1. Dans Agents Playground, accédez à Simuler une activité et sélectionnez Ajouter un utilisateur.

   

   Une fenêtre contextuelle s’affiche pour afficher un aperçu du gestionnaire d’activités.

2. Sélectionnez Envoyer l’activité.

   

   L’application envoie une réponse.

   

Déclencheurs d’activité personnalisés

Vous pouvez utiliser l’activité personnalisée pour personnaliser des déclencheurs d’activité tels que , reactionsAddedafin de répondre aux exigences de votre application bot. Agents Playground remplit automatiquement les propriétés requises de l’activité. Vous pouvez également modifier le type d’activité et ajouter d’autres propriétés.

1. Sélectionnez Simuler une activité>Activité personnalisée.

   

2. Ajoutez messageReaction pour personnaliser l’activité sous la propriété type et appeler l’activité personnalisée.

   {
     "type": "messageReaction",
     "reactionsAdded": [
       {
         "type": "like"
       }
     ],
     "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
   }
   

3. Sélectionnez Envoyer l’activité.

   

   Le bot envoie un onReactionsAdded gestionnaire en réponse.

   

Configurer Agents Playground pour l’authentification

Lors du débogage d’une application qui nécessite une authentification, vous pouvez configurer l’ID client et la clé secrète client Microsoft Entra, avec un ID de locataire facultatif. Si vous avez créé votre bot à l’aide du Bot Service Azure AI, les informations d’identification sont disponibles dans le App Service du bot sous Configuration des paramètres>. Si vous n’êtes pas sûr des valeurs, vous pouvez les supprimer du fichier de configuration de l’application en cours d’exécution localement, puis exécuter l’application dans agent Playground. Si l’application ne nécessite pas l’exécution de ces paramètres, vous n’avez pas besoin de les configurer.

Variable d’environnement / Ligne de commande

Avant de démarrer Agents Playground, vous pouvez définir les variables d’environnement suivantes : AUTH_CLIENT_ID, AUTH_CLIENT_SECRETet AUTH_TENANT_ID. Ces valeurs sont utilisées pour la configuration d’authentification par défaut.

Lorsque vous exécutez Agents Playground à partir de la ligne de commande, vous pouvez également utiliser les options : --client-id, --client-secretet --tenant-id. Ces options remplacent les paramètres de variable d’environnement par défaut.

Interface côté client

Une fois agents Playground démarré, vous pouvez toujours configurer l’authentification via l’interface cliente comme suit :

1. Sélectionnez Configurer l’authentification.

   

2. Renseignez les champs du formulaire et sélectionnez Enregistrer.

   

Le panneau journal affiche le message si la configuration est correctement définie.

Logique d’authentification

Agents Playground acquiert un jeton JWT à l’aide des paramètres d’authentification fournis et l’inclut dans l’en-tête Authorization lors de la communication avec l’application. Le jeton JWT dans l’en-tête de réponse de l’application est également validé par Agents Playground. Pour plus d’informations sur le processus d’authentification, consultez Authentification avec l’API Bot Connector.

Prise en charge de plusieurs canaux

Teams est le canal par défaut utilisé pour le débogage de votre application, mais d’autres canaux sont également pris en charge. Vous pouvez modifier le canal en définissant la DEFAULT_CHANNEL_ID variable d’environnement ou en utilisant l’option --channel-id lors du démarrage d’Agents Playground à partir de la ligne de commande.

Actuellement, les ID de canal acceptés sont les suivants : msteams, directline, webchatet emulator. Lorsque vous définissez un ID de canal, les propriétés des messages envoyés à l’application changent en conséquence pour simuler un environnement réel. Pour les directline canaux et webchat , un client correspondant s’affiche et carte rendu diffère de celui du canal Teams.

Personnaliser le contexte Teams

Le fichier de configuration dans le dossier racine du projet vous permet de personnaliser les informations de contexte Teams telles que les conversations, les équipes et les utilisateurs. Il fournit des données fictives pour tester des API bot Framework ou des méthodes à partir du Kit de développement logiciel (SDK) Agent ou du KIT de développement logiciel (SDK) Teams, comme TeamsInfo.getTeamMembers.

Configuration par défaut

# 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

Mettre à jour le fichier de configuration

Si votre code de bot utilise des API Bot Framework, vous pouvez modifier le fichier de configuration pour personnaliser les réponses de l’API. Par exemple, prenons l’exemple d’un bot de notification DevOps Azure installé dans une équipe qui extrait les bogues inactifs de Azure DevOps. Il identifie les propriétaires des bogues inactifs, récupère leurs adresses e-mail et envoie des notifications quotidiennes à leurs conversations personnelles.

Pour tester complètement ce bot dans Agents Playground, veillez à mettre à jour le fichier de configuration avec les adresses e-mail correctes des propriétaires de bogues inactifs.

1. Accédez au .m365agentsplayground.yml fichier dans le dossier racine du projet.

2. Accédez à la users section et mettez à jour , nameuserPrincipleNameet email de l’utilisateur requis.

   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.com
   

3. Enregistrez le fichier et sélectionnez F5 pour déboguer dans Agents Playground.

Il est important de comprendre que la mise à jour du fichier de configuration a trois impacts majeurs :

• Cela affecte les réponses retournées par les API Bot Framework Connector. Par exemple : TeamsInfo.getPagedMembers().
• Il modifie les détails de la charge utile de l’activité. Par exemple : activity.recipient.
• Elle influence l’interface utilisateur dans Agents Playground. Par exemple, les noms de conversation de groupe.

Limitations

• Les fonctionnalités de bot ou d’agent activées via le manifeste de l’application Teams ne sont pas disponibles, car Agents Playground ne les traite pas.

• Agents Playground ne prend pas en charge tous les types de cartes à l’exception des cartes adaptatives.

• Agents Playground ne prend pas en charge les fonctionnalités de carte adaptative suivantes :

  • Recherche en tête de frappe
  • Mention de l’utilisateur
  • Stageview
  • Pleine largeur

• Agents Playground ne prend pas en charge les expériences suivantes :

  • Mobile
  • Réunion

• Agents Playground peut émuler les expériences suivantes :

  Fonctionnalités	Déboguer dans Agents Playground	Déboguer votre application localement
  Envoi/réception de messages de base	Disponible	Disponible
  API Bot Framework (TeamsInfo.getPagedMembers()...)	Disponible (répondre avec des données fictives)	Disponible
  Envoi d’événements Teams	Disponible (activité fictive)	Disponible
  Indicateur de saisie	Non disponible	Disponible
  Tab, Extension de message, Boîtes de dialogue (appelées modules de tâche dans TeamsJS v1.x), Authentification unique (SSO) et cartes non adaptatives	Non disponible	Disponible

Déboguer une application existante avec Agents Playground

Vérifiez qu’une application existante a été créée à l’aide du Kit de ressources Agents. Pour déboguer votre application avec Agents Playground, procédez comme suit :

1. Ouvrez le dossier de projet du bot existant dans Agents Toolkit.

2. Accédez à EXPLORER.vscode>.

3. Sélectionnez launch.json et ajoutez le code suivant à la fin du fichier :

   // .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 
           }, 
       ] 
   } 
   

4. Accédez à tasks.json et ajoutez le code suivant à la fin du fichier :

       { 
         "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" 
         } 
       }, 
     ],
   }
   

5. Sous EXPLORER, créez un fichier .localConfigs.playground et ajoutez le code suivant :

   // .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.json
   

6. Accédez à EXPLORER>env.

7. Créez un fichier .env.playground et ajoutez le code suivant :

   // .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=56150
   

8. Si vous avez des variables d’environnement personnalisées, définissez leurs valeurs dans .env.playground ou .env.playground.user.

9. Ajoutez une clé OpenAI ou Azure clé et point de terminaison OpenAI dans .env.playground.user.

   # SECRET_OPENAI_API_KEY=***********
   SECRET_AZURE_OPENAI_API_KEY=***********
   SECRET_AZURE_OPENAI_ENDPOINT=<https://your-openai-service-name.openai.azure.com/>
   

10. Accédez à package.json et ajoutez le code suivant sous la scripts propriété :

    "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", 
        ... 
    },
    

11. Dans le volet gauche, sélectionnez Exécuter et déboguer (Ctrl+Shift+D), puis sélectionnez Déboguer dans Le terrain de jeu des agents Microsoft 365 dans la liste déroulante.

    

Agents Playground débogue correctement votre bot existant.

Désactivation de la collecte de données

Si vous décidez de ne pas autoriser Agents Playground à collecter des données d’utilisation, vous pouvez facilement désactiver la collecte de données en ajoutant une option --disable-telemetry lors du démarrage d’Agents Playground via la ligne de commande.

FAQ

Exemple de code

Guide pas à pas

Suivez le guide pas à pas pour déboguer un bot conversationnel IA à l’aide d’Agents Playground.

Voir aussi

• Vue d’ensemble du kit de ressources Microsoft 365 Agents
• Installer microsoft 365 Agents Toolkit
• Créer des bots pour Teams
• Kit de développement logiciel (SDK) Teams
• Carte adaptative
• Kit de développement logiciel (SDK) Agents