Microsoft 365 Agents Playground

Agents Playground macht das Debuggen von Bot- oder Agent-basierten Apps mühelos. Sie können mit Ihrem Bot chatten und seine Nachrichten und adaptive Karten anzeigen, wie sie in verschiedenen Kanälen angezeigt werden. Sie benötigen kein Microsoft 365-Entwicklerkonto, Tunneling oder eine echte Client-App- und Anwendungsregistrierung, um Agents Playground verwenden zu können.

Die folgende Abbildung zeigt eine Beispiel-App, die eine adaptive Karte mit einer Liste von Befehlen im Agents Playground anzeigt. Es enthält auch eine Beschreibung der Befehle, damit Sie Ihre App testen können, ohne ihren Code manuell zu durchsuchen:

Im Folgenden sind die Vorteile von Agents Playground aufgeführt:

• Sandboxumgebung: Die Sandboxumgebung von Agents Playground emuliert das Verhalten, das Aussehen und die Benutzererfahrung des echten Agents.

• Tunneling: Ein externer Tunneldienst ist nicht erforderlich, da Agents Playground auf einem lokalen Server ausgeführt wird, mit dem Ihr Bot kommunizieren kann.

• Reduzieren von Kontoabhängigkeiten: Der Microsoft 365-Entwicklermandant und die App-Uploadberechtigungen sind zum Debuggen der Anwendung nicht erforderlich.

• Schnelle Iterationen in inneren Schleifen: Optimiert den Prozess der Änderung des App-Entwurfs und der Anwendungslogik, ohne die Anwendung erneut in der Cloud bereitstellen zu müssen.

• Modelldaten und Aktivitäten: Agents Playground erleichtert das Testen komplexer Szenarien, z. B. das Senden einer Begrüßungsnachricht, wenn ein neues Mitglied dem Kanal beitritt, mithilfe von Pseudodaten und Aktivitätstriggern.

• Zuverlässig: Agents Playground ist zuverlässig, da die adaptive Karte der Anwendung dieselbe Renderingtechnologie wie in Teams oder WebChat verwendet.

• Integration in vorhandene Anwendungen: Agents Playground lässt sich mühelos in vorhandene Anwendungen integrieren, die mit dem Agent SDK oder Teams SDK erstellt wurden.

• Unterstützung für verschiedene Bereiche: Agents Playground unterstützt Tests in persönlichen, Team- und Gruppenchatbereichen.

Voraussetzungen

Stellen Sie sicher, dass Sie die folgenden Tools zum Erstellen und Bereitstellen Ihrer Anwendungen in Agents Playground installieren:

Grundlegendes zu Agents Playground

Agents Playground ist ein npm-Paket mit einem CLI-Befehl namens teamsapptester. Wenn Sie ausführen teamsapptester start, wird eine Web-App auf Ihrem lokalen Computer geöffnet, die den Teams- oder WebChat-Client und den Bot Framework-Dienst emuliert. Diese Web-App benötigt keine Cloudressourcen, da sie simulierte Daten verwendet, um die Kontextinformationen zu simulieren.

Um eine Anwendung im Agents Playground verwenden zu können, müssen Sie Folgendes bereitstellen:

• Nachrichtenendpunkt: Ein Nachrichtenendpunkt ist die URL, die Agents Playground und Ihre Anwendung verknüpft. Sie können den Endpunkt mit der Umgebungsvariablen BOT_ENDPOINT aktualisieren, Agents Playground mit der Option --app-endpointstarten oder einfach den Standardwert von http://localhost:3978/api/messagesverwenden.
• Konfigurationsdatei (optional): Eine Konfigurationsdatei informiert Agents Playground über Ihre angepassten Kontextinformationen in Teams. Die Datei hat den Namen .m365agentsplayground.yml im Stammordner des Projekts. Wenn Teams diese Datei nicht finden kann, wird die Standardkonfiguration verwendet. Weitere Informationen finden Sie unter Anpassen des Teams-Kontexts.

Agents Playground-Erfahrung im Agents Toolkit

Agents Playground bietet eine schnellere Debugerfahrung für Anwendungen im Vergleich zur realen Umgebung.

Aktivitätstrigger

Sie können eine Aktivität im Agents Playground mithilfe von Aktivitätstriggern simulieren. Es gibt zwei Arten von Aktivitätstriggern:

1. Vordefinierte Aktivitätstrigger
2. Benutzerdefinierte Aktivitätstrigger

Vordefinierte Aktivitätstrigger

Agents Playground bietet vordefinierte Aktivitätstrigger zum Testen der Funktionen Ihrer App.

Vordefinierte Aktivitätstrigger sind im Menü Aktivität simulieren im Agents Playground verfügbar.

Führen Sie die folgenden Schritte aus, um eine Benutzer hinzufügen-Aktivität zu simulieren:

1. Wechseln Sie in Agents Playground zu Aktivität simulieren , und wählen Sie Benutzer hinzufügen aus.

   

   Ein Popupfenster wird angezeigt, um eine Vorschau des Aktivitätshandlers anzuzeigen.

2. Wählen Sie Aktivität senden aus.

   

   Die App sendet eine Antwort.

   

Benutzerdefinierte Aktivitätstrigger

Sie können die benutzerdefinierte Aktivität verwenden, reactionsAddedum Aktivitätstrigger wie , an die Anforderungen Ihrer Bot-App anzupassen. Agents Playground füllt automatisch die erforderlichen Eigenschaften der Aktivität auf. Sie können auch den Aktivitätstyp ändern und weitere Eigenschaften hinzufügen.

1. Wählen SieBenutzerdefinierte Aktivität>simulieren aus.

   

2. Fügen Sie hinzu messageReaction , um die Aktivität unter der -Eigenschaft type anzupassen und die benutzerdefinierte Aktivität aufzurufen.

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

3. Wählen Sie Aktivität senden aus.

   

   Der Bot sendet als Antwort einen onReactionsAdded Handler.

   

Konfigurieren des Agents Playground für die Authentifizierung

Beim Debuggen einer Anwendung, die eine Authentifizierung erfordert, können Sie die Microsoft Entra Client-ID und den geheimen Clientschlüssel mit einer optionalen Mandanten-ID konfigurieren. Wenn Sie Ihren Bot mit dem Azure KI-Bot Service erstellt haben, sind die Anmeldeinformationen im App Service des Bots unter Einstellungenkonfiguration> verfügbar. Wenn Sie sich der Werte nicht sicher sind, können Sie sie aus der Konfigurationsdatei der lokal ausgeführten Anwendung entfernen und die Anwendung dann im Agents Playground ausführen. Wenn die Anwendung diese Einstellungen nicht zum Ausführen benötigt, müssen Sie sie nicht konfigurieren.

Umgebungsvariable/Befehlszeile

Vor dem Starten von Agents Playground können Sie die folgenden Umgebungsvariablen festlegen: AUTH_CLIENT_ID, AUTH_CLIENT_SECRETund AUTH_TENANT_ID. Diese Werte werden für die Standardauthentifizierungskonfiguration verwendet.

Wenn Sie Agents Playground über die Befehlszeile ausführen, können Sie auch die Optionen --client-id, --client-secretund --tenant-idverwenden. Diese Optionen setzen die Standardeinstellungen der Umgebungsvariablen außer Kraft.

Clientseitige Schnittstelle

Nachdem Agents Playground gestartet wurde, können Sie die Authentifizierung weiterhin über die Clientschnittstelle wie folgt konfigurieren:

1. Wählen Sie Authentifizierung konfigurieren aus.

   

2. Füllen Sie die Felder im Formular aus, und wählen Sie Speichern aus.

   

Im Protokollbereich wird die Meldung angezeigt, wenn die Konfiguration erfolgreich festgelegt wurde.

Authentifizierungslogik

Agents Playground ruft ein JWT-Token mithilfe der bereitgestellten Authentifizierungseinstellungen ab und schließt es bei der Kommunikation mit der Anwendung in den Autorisierungsheader ein. Das JWT-Token im Antwortheader der Anwendung wird auch von Agents Playground überprüft. Weitere Informationen zum Authentifizierungsprozess finden Sie unter Authentifizierung mit der Bot Connector-API.

Unterstützung für mehrere Kanäle

Teams ist der Standardkanal, der zum Debuggen Ihrer Anwendung verwendet wird, aber auch andere Kanäle werden unterstützt. Sie können den Kanal ändern, indem Sie die Umgebungsvariable DEFAULT_CHANNEL_ID festlegen oder die --channel-id Option verwenden, wenn Sie Agents Playground über die Befehlszeile starten.

Derzeit sind die akzeptierten Kanal-IDs: msteams, directline, webchatund emulator. Wenn Sie eine Kanal-ID festlegen, ändern sich die Eigenschaften der an die Anwendung gesendeten Nachrichten entsprechend, um eine reale Umgebung zu simulieren. Für die directline Kanäle und webchat wird ein entsprechender Client angezeigt, und Karte Rendering unterscheidet sich von dem des Teams-Kanals.

Anpassen des Teams-Kontexts

Mit der Konfigurationsdatei im Stammordner des Projekts können Sie Teams-Kontextinformationen wie Chats, Teams und Benutzer anpassen. Es stellt Modelldaten zum Testen von Bot Framework-APIs oder -Methoden aus dem Agent SDK oder Teams SDK bereit, z TeamsInfo.getTeamMembers. B. .

Standardkonfiguration

# 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

Aktualisieren der Konfigurationsdatei

Wenn Ihr Botcode Bot Framework-APIs verwendet, können Sie die Konfigurationsdatei ändern, um die API-Antworten anzupassen. Betrachten Sie beispielsweise einen Azure DevOps-Benachrichtigungsbot, der in einem Team installiert ist und inaktive Fehler aus Azure DevOps abruft. Es identifiziert die Besitzer der inaktiven Fehler, ruft ihre E-Mail-Adressen ab und sendet tägliche Benachrichtigungen an ihre persönlichen Chats.

Um diesen Bot im Agents Playground umfassend zu testen, müssen Sie die Konfigurationsdatei mit den richtigen E-Mail-Adressen der inaktiven Fehlerbesitzer aktualisieren.

1. Wechseln Sie zur .m365agentsplayground.yml Datei im Stammordner des Projekts.

2. Wechseln Sie zum users Abschnitt, userPrincipleNameund aktualisieren Sie , nameund email des erforderlichen Benutzers.

   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. Speichern Sie die Datei, und wählen Sie F5 aus, um im Agents Playground zu debuggen.

Es ist wichtig zu verstehen, dass das Aktualisieren der Konfigurationsdatei drei wesentliche Auswirkungen hat:

• Dies wirkt sich auf die Von Bot Framework Connector-APIs zurückgegebenen Antworten aus. Beispiel: TeamsInfo.getPagedMembers().
• Es ändert die Details in der Aktivitätsnutzlast. Beispiel: activity.recipient.
• Es wirkt sich auf die Benutzeroberfläche in Agents Playground aus. Beispiel: Gruppenchatnamen.

Begrenzungen

• Bot- oder Agent-Features, die über das Teams-App-Manifest aktiviert werden, sind nicht verfügbar, da Agents Playground sie nicht verarbeitet.

• Agents Playground unterstützt nicht alle Arten von Karten mit Ausnahme von adaptiven Karten.

• Agents Playground unterstützt die folgenden Features für adaptive Karten nicht:

  • Typeahead-Suche
  • benutzer Erwähnung
  • Stageview
  • Volle Breite

• Agents Playground unterstützt die folgenden Funktionen nicht:

  • Mobil
  • Besprechung

• Agents Playground kann die folgenden Erfahrungen emulieren:

  Features	Debuggen in Agents Playground	Lokales Debuggen Ihrer App
  Grundlegendes Senden/Empfangen von Nachrichten	Verfügbar	Verfügbar
  Bot Framework-APIs (TeamsInfo.getPagedMembers()...)	Verfügbar (Antworten mit simulierten Daten)	Verfügbar
  Senden von Teams-Ereignissen	Verfügbar (Pseudoaktivität)	Verfügbar
  Eingabeindikator	Nicht verfügbar	Verfügbar
  Registerkarte, Nachrichtenerweiterung, Dialoge (in TeamsJS v1.x als Aufgabenmodule bezeichnet), Einmaliges Anmelden (Single Sign-On, SSO) und nicht adaptive Karten	Nicht verfügbar	Verfügbar

Debuggen einer vorhandenen App mit Agents Playground

Stellen Sie sicher, dass Sie eine vorhandene App mit dem Agents-Toolkit erstellt haben. Führen Sie die folgenden Schritte aus, um Ihre App mit Agents Playground zu debuggen:

1. Öffnen Sie den Projektordner des vorhandenen Bots im Agents Toolkit.

2. Wechseln Sie zu EXPLORER.vscode>.

3. Wählen Sie launch.json aus, und fügen Sie den folgenden Code am Ende der Datei hinzu:

   // .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. Wechseln Sie zu tasks.json , und fügen Sie den folgenden Code am Ende der Datei hinzu:

       { 
         "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. Erstellen Sie unter EXPLORER eine .localConfigs.playground-Datei , und fügen Sie den folgenden Code hinzu:

   // .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. Wechseln Sie zu EXPLORER>env.

7. Erstellen Sie eine .env.playground-Datei , und fügen Sie den folgenden Code hinzu:

   // .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. Wenn Sie über benutzerdefinierte Umgebungsvariablen verfügen, legen Sie deren Werte in .env.playground oder .env.playground.user fest.

9. Fügen Sie entweder einen OpenAI-Schlüssel oder Azure OpenAI-Schlüssel und -Endpunkt in .env.playground.user hinzu.

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

10. Wechseln Sie zu package.json , und fügen Sie den folgenden Code unter der scripts -Eigenschaft hinzu:

    "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. Wählen Sie im linken Bereich Ausführen und Debuggen (Ctrl+Shift+D) und in der Dropdownliste Microsoft 365 Agents Playground die Option Debuggen aus.

    

Agents Playground debuggt erfolgreich Ihren vorhandenen Bot.

Deaktivieren der Datensammlung

Wenn Sie nicht zulassen möchten, dass Agents Playground Nutzungsdaten sammelt, können Sie die Datensammlung einfach deaktivieren, indem Sie die Option --disable-telemetry hinzufügen, wenn Agents Playground über die Befehlszeile gestartet wird.

Häufig gestellte Fragen

Codebeispiel

Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung zum Debuggen eines KI-Chatbots mithilfe von Agents Playground.

Siehe auch

• Übersicht über das Microsoft 365-Agents-Toolkit
• Installieren des Microsoft 365 Agents Toolkits
• Erstellen von Bots für Teams
• Teams SDK
• Adaptive Karte
• Agents SDK