Debug message extension app in Microsoft 365 Agents Playground

You can debug bot-based message extension capabilities such as search commands, action commands, and link unfurling using Agents Playground (previously known as Teams App Test Tool) within a simulated environment. Test tool helps you to identify and resolve issues before deploying the extension to a live environment.

Agents Playground enhances the functionality of bot-based message extensions, which are built on top of Bot Framework. When a message extension is activated, Agents Playground sends an invoke request to the app. The app then processes this request and returns an invoke response, which Agents Playground renders and displays.

Note

The user experience to trigger message extension in Agents Playground is different from Teams, as the goal of Agents Playground is to test and debug the app logic and make the flow simple.

Prerequisites

Ensure that you install the following tools to build and deploy your bot in Agents Playground:

	Install	For using...
	Microsoft 365 Agents Toolkit	A Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest release version.
	Node.js	Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type.
	Visual Studio Code	JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use the latest version.

Build and run the sample app

1. Go to the sample.

2. Clone the repository to test the sample app.

   git clone https://github.com/OfficeDev/microsoft-365-agents-toolkit-samples.git
   

3. Go to Visual Studio Code.

4. Select File > Open Folder.

5. Go to the location where you cloned teamsFx-samples repo and select the test-tool-sample-app folder.

6. Select Select Folder.

   

7. From the left pane, select Microsoft 365 Agents Toolkit.

8. From the left pane, select Run and Debug (Ctrl+Shift+D) and select Debug in Microsoft 365 Agents Playground (Preview) in dropdown list.

9. Agents Playground opens the bot in a webpage.

   

10. In the message compose area, type help. Agents Playground displays all the message extension commands in the sample app.

    

11. Select the + icon to display the type of message extension:

    • Search Command

    • Action Command

    • Link Unfurling

    

12. Select the type of message extension you want to debug.

13. Based on the option selected in the earlier step, select the following tab:

    Search Command

    To test a Search Command in Agents Playground, follow these steps:

    1. Enter the keywords you wish to search for into the message extension.

    2. Agents Playground sends a composeExtension/query invoke request.

       

    3. Search results are displayed.

    4. To review the details of the request and the results, check the Log Panel.

    For scenarios that require more advanced configurations:

    1. Select the + icon in the message compose area.

    2. Select Search Command.

    3. Select Specify Command ID or Parameter.

    4. Update the values for Command ID and Parameter name.

       

    5. When the message extension is triggered, it retrieves these predefined values from the context.

    Note

    It's not mandatory to include the command ID or parameter name to test your message extension. Add them if you require to test the functionality.

    Action Command

    You can test an Action Command in Agents Playground in the following ways:

    + icon

    1. Select the + icon in the message compose area.

    2. Select Action Command.

       

    ... icon

    1. Above the message, select the ... option.

    2. Select Action Command.

       

I ran into an issue

You can create a dialog with an Action Command in two ways:

• Adaptive Cards

• Static list of parameters

  

Create dialog with Adaptive Cards

In the action-based message extension dialog, select Adaptive Cards. Agents Playground dynamically retrieves the dialog from the message extension. It sends a composeExtension/fetchTask invoke request and then displays the Adaptive Card based on the response received from the app.

Create dialog with static list of parameters

In the action-based message extension dialog, select Static list of parameters. Agents Playground renders the parameters you provided into a dialog. For more information on parameters, see composeExtensions.commands.

The following code is a sample of the static list of parameters in JSON format:

[{
  "name": "title",
  "title": "Card title",
  "description": "Title for the card",
  "inputType": "text"
},
{
  "name": "subTitle",
  "title": "Subtitle",
  "description": "Subtitle for the card",
  "inputType": "text"
},
{
  "name": "text",
  "title": "Text",
  "description": "Text for the card",
  "inputType": "textarea"
}]

Static list of parameters are available under the composeExtensions property in app manifest. For example, see manifest.json.

Submit form inside the dialog

After you've created a dialog using Adaptive Cards or a static list of parameters and select submit, Agents Playground sends an invoke request with name of composeExtension/submitAction.

Based on the invoke response from the message extension, Agents Playground performs one of the following actions:

• Renders an Adaptive Card from the invoke response and inserts it into the message compose area.

• Renders an Adaptive Card from the invoke response inside the dialog. This is useful when the form is extensive and needs to be divided into multiple cards.

• Displays a plain text message from the invoke response inside the dialog.

Note

It's not mandatory to include the command ID to test your message extension. Add them if you require to test the functionality.

Link Unfurling

To test an Link Unfurling in Agents Playground, follow these steps:

1. Select the + icon in the message compose area.

2. Select Link Unfurling.

   

   A Enter a URL dialog appears.

3. In the Enter an URL dialog, enter a URL of your choice.

4. Select Send to Conversation.

   

   Agents Playground triggers a composeExtension/queryLink invoke request with the URL to the message extension. You can review the Adaptive Card that Agents Playground renders based on the invoke response from the app.

Note

The user experience for testing link unfurling in Agents Playground differs from that in Teams, however you can still test or debug the app logic with Agents Playground in a simple way.

I ran into an issue

Limitations

The following table lists the features for each message extension type that aren't supported:

Message extension type	Features not supported
Search Command	Triggering from command box. Grid layout for search results. Sending the composeExtension/selectItem invoke activity when an item from the search results is selected. Pagination for additional search results.
Action Command	Triggering from command box. Creating a dialog with embedded web view. Rendering the botMessagePreview invoke activity.
Link Unfurling	Rendering the preview card from the invoke response. Sending invoke activity of composeExtension/anonymousQueryLink for zero install case.

Message extension Agents Playground FAQ

How can I use `commandId` or `parameters.name` properties for a Search Command in Agents Playground?

When you use the search box in a search-based message extension in Teams, your app receives an invoke activity that includes two parameters. Sometimes, your app might need to use activity.value.commandId or activity.value.parameters[0].name to manage different search command behaviors in the activity handler for the composeExtension/query invoke activity, such as the handleTeamsMessagingExtensionQuery method in the Bot Framework SDK for JavaScript. However, your app doesn't need it because Teams only supports a single search command and you can leave them empty.

If your app uses these two parameters, you can provide additional inputs by selecting Specify Command ID or Parameter and updating the required values. Agents Playground includes these parameters in the invoke activity payload during a search. If you don't specify them, the payload avoids these parameters.

In Teams, the parameters are available in the app manifest. Since Agents Playground doesn't process the manifest, you need to input the parameters manually.

How can I use `commandId` property for an Action Command in Agents Playground?

In Teams, dialogs are triggered from action commands and your app receives a composeExtension/fetchTask or composeExtension/submitAction invoke activity. This activity includes the activity.value.commandId parameter. However, your app uses this parameter to differentiate between commands within the activity handler for these invoke activities, such as the handleTeamsMessagingExtensionFetchTask or handleTeamsMessagingExtensionSubmitAction methods in the Bot Framework SDK for JavaScript.

To test various action commands, you must enter the Command ID in the respective field. If you don't update, the command IDs aren't included in the activity payload.

In Teams, commands are available in the app manifest. Since Agents Playground doesn't process the manifest, you need to input the commands manually.

How does a static list of parameters work in Agents Playground?

The static list of parameters is the simple method to create dialogs for action commands, however you can't format the static list.

When you create a dialog using a static list of parameters, the message extension receives a composeExtension/submitAction invoke activity upon the user’s submission of the dialog.

In Teams, the parameters are available in the app manifest. Since Agents Playground doesn't process the manifest, you need to input the parameters manually.

See also

• Respond to user requests
• Create and send dialogs
• Respond to the dialog submit action
• ComposeExtensions.commands