Microsoft 365 Agents Playground

Agent Playground permet de déboguer des applications basées sur des robots ou des agents sans effort. Vous pouvez discuter avec votre bot et voir ses messages et ses cartes adaptatives au fur et à mesure qu’ils apparaissent dans différents canaux. Vous n’avez pas besoin d’un compte de développeur Microsoft 365, de tunneling ou d’une application client réelle et d’une inscription d’application 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 votre code :

Voici les avantages d’Agents Playground :

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

• 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 : les autorisations de client Microsoft 365 Developer et de chargement de l’application ne sont pas nécessaires pour déboguer l’application.

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

• Données et activités fictives : Agents Playground permet de tester facilement des scénarios complexes tels que l’envoi d’un message de bienvenue lorsqu’un nouveau membre rejoint le canal, en utilisant des données fictives et des 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 sans effort aux applications existantes construites avec le SDK d’agent ou le SDK Teams.

• Prise en charge de différentes étendues : Le terrain de jeu des agents prend en charge les tests dans les étendues de conversation personnelle, d’équipe et de groupe.

Configuration requise

Veillez à installer les outils suivants pour créer et déployer vos applications dans Agents Playground :

Comprendre le terrain de jeu des agents

Agents Playground est un package npm doté d’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 besoin d’aucune ressource 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 relie Agents Playground et votre application. Vous pouvez mettre à jour le point de terminaison avec la variable d’environnement, démarrer le terrain de jeu des agents avec l’option BOT_ENDPOINT--app-endpoint, ou 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, voir personnaliser le contexte Teams.

Expérience du terrain de jeu des agents dans le kit de ressources des 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

Le terrain de jeu des agents fournit des déclencheurs d’activité prédéfinis pour tester les fonctionnalités de votre application.

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

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

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

   

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

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 les déclencheurs d’activité tels que reactionsAdded, afin de répondre aux exigences de votre application de robot. 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. Ajouter 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 le terrain de jeu des agents pour l’authentification

Lors du débogage d’une application qui nécessite une authentification, vous pouvez configurer l’ID client et le secret client Microsoft Entra, avec un ID client facultatif. Si vous avez créé votre bot à l’aide d’Azure AI Bot Service, les informations d’identification sont disponibles dans l’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 exécutée localement, puis exécuter l’application dans le Playground des agents. Si l’application ne requiert pas 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 de l’authentification par défaut.

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

Interface côté client

Après le démarrage d’Agents Playground, vous pouvez toujours configurer l’authentification via l’interface client comme suit :

1. Sélectionnez Configurer l’authentification.

   

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

   

Le panneau du 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

Lorsque vous exécutez le terrain de jeu des agents en tant qu’outil autonome, Microsoft Teams (msteams) est utilisé comme canal par défaut. Lorsque le terrain de jeu est lancé via Microsoft 365 Agents Toolkit, le canal par défaut est emulator. Vous pouvez modifier le canal en définissant la variable d’environnement DEFAULT_CHANNEL_ID 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 : 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 canaux etwebchat, un client correspondant s’affiche et le directline rendu de la carte 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 les API ou méthodes Bot Framework du SDK Agents ou Teams, telles que TeamsInfo.getTeamMembers.

Configuration par défaut

Agent Playground contient un fichier de configuration intégré dans le dossier racine du projet.

# yaml-language-server: $schema=https://aka.ms/teams-app-test-tool-config/0.1.1/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.1"
tenantId: 00000000-0000-0000-0000-0000000000001
bot:
  id: 00000000-0000-0000-0000-00000000000011
  name: Test Bot
  agenticAppId: 00000000-0000-0000-0000-000000000100
  agenticUserId: agentic-user-id
  tenantId: 00000000-0000-0000-0000-000000000001
  role: agenticUser
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

Personnalisation du 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. Prenons l’exemple d’un bot de notification Azure DevOps installé dans une équipe qui récupère les bogues inactifs à partir d’Azure DevOps. Il identifie les propriétaires des bogues inactifs, récupère leurs adresses e-mail et envoie des notifications quotidiennes à leurs chats personnels.

Pour tester de manière exhaustive 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. Créez un fichier nommé .m365agentsplayground.yml dans le dossier racine du projet.

2. Copiez la configuration de données fictives par défaut et collez-la dans le .m365agentsplayground.yml fichier.

3. Accédez à la users section et mettez à jour le name, userPrincipleNameet 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
   

4. 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 :

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

Limitations

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

• Agents Playground prend uniquement en charge les cartes adaptatives. Les autres types de carte ne sont pas pris en charge.

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

  • Recherche de saisie semi-automatique
  • mention de l’utilisateur
  • Vue de la scène
  • Cartes pleine chasse

• Agent 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 le terrain de jeu des agents	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
  Onglet, 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 que vous disposez d’une application existante créée à l’aide d’Agents Toolkit. 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. Aller dans 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 une clé et un point de terminaison Azure 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 de gauche, sélectionnez Exécuter et déboguer (Ctrl+Shift+D) et sélectionnez Déboguer dans le terrain de jeu des agents Microsoft 365 dans la liste déroulante.

    

Agents Playground débogue votre bot existant avec succès.

Désactivation de la collecte de données

Si vous décidez que vous ne souhaitez 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 robot conversationnel IA à l’aide d’Agents Playground.

Voir aussi

• Vue d’ensemble de Microsoft 365 Agents Toolkit
• Installer Microsoft 365 Agents Toolkit
• Créer des bots pour Teams
• Teams SDK
• Carte adaptative