Test your agent locally in Microsoft 365 Agents Playground

2025-07-29

The details of how to test your agent locally depend on how you created your agent.

You can create an agent using the Microsoft 365 Agents SDK in three ways:

Clone from a sample and open in your IDE
Start with the Microsoft 365 Agents Toolkit in C#, JS, or Python using Visual Studio or Visual Studio Code
Use the CLI, as shown in the quickstart

Using the Microsoft 365 Agents Playground

You started your project with the toolkit

If you start with the toolkit, you have everything set up to test using the Agents Playground straight away. You can test in the Agents Playground either locally, or in Microsoft 365 Copilot or Microsoft Teams. This scenario is covered in the Visual Studio Code walkthrough and the Visual Studio walkthrough, respectively.

You started your project by cloning or CLI

If you start your project using the CLI or by cloning a sample and opening the sample in your IDE, you can use the local Agents Playground to test. The Agents Playground connects to your local code.

You can install the Agents Playground using one of the following methods:

winget install agentsplayground

curl -s https://raw.githubusercontent.com/OfficeDev/microsoft-365-agents-toolkit/dev/.github/scripts/install-agentsplayground-linux.sh | bash

Option 2: Install using npm

Install Node.js (if not already installed): Download and install the latest Node.js from nodejs.org.
Install the Agents Playground package:

For global installation (recommended):
```
npm install -g @microsoft/m365agentsplayground
```
For project-specific installation:
```
npm install -D @microsoft/m365agentsplayground
```

Once your quickstart agent is created or a sample is cloned from the repo, you can use it with the Agents Playground.
The Agents Playground supports both anonymous and authenticated modes. For anonymous testing, no additional configuration is required. If you want to test with authentication, you need to configure Microsoft Entra ID app registrations for both the Agents Playground (options are provided below) and your application. For information, see Provisioning an Azure Bot to use with Agents SDK.
Configure your ports correctly in your app. Choose an available port for your agent (default is 3978, but can be any available port).
Run your code.
Open the Agents Playground and start with your agent's endpoint:
```
agentsplayground -e "http://localhost:<your-agent-port>/api/messages" -c "emulator"
```
Configure authentication if required by your agent:
```
agentsplayground -e "http://localhost:<your-agent-port>/api/messages" -c "emulator" --client-id "your-client-id" --client-secret "your-client-secret" --tenant-id "your-tenant-id"
```
Key options:
- -e, --app-endpoint: Your agent's endpoint URL (e.g., http://localhost:3978/api/messages)
- -c, --channel-id: Channel type (e.g., emulator, webchat, msteams). Each channel provides different user experience and activity properties.
- --client-id: Client ID for authentication
- --client-secret: Client secret for authentication
- --tenant-id: Tenant ID for authentication
Use agentsplayground --help to see the full list of available options.

Alternatively, you can use environment variables instead of CLI options. If both specified, CLI option has higher priority.
```
export BOT_ENDPOINT="http://localhost:<your-agent-port>/api/messages"
export DEFAULT_CHANNEL_ID="emulator"
export AUTH_CLIENT_ID="your-client-id"
export AUTH_CLIENT_SECRET="your-client-secret"
export AUTH_TENANT_ID="your-tenant-id"
```
Once it is started, it should open as seen in the following image. You can ask questions and test your agent in the playground interface.

Wherever possible, we recommend that you start with the Microsoft 365 Agents Toolkit. The toolkit makes getting started, testing locally, and deploying easier and quicker. It abstracts much the manual setup of the Azure Bot Service and Azure App Registrations so you don't have to. By starting manually, you must perform these manual steps yourself.

Summary

You have successfully tested your Microsoft 365 Agents SDK locally using the Microsoft 365 Agents Playground when starting with a cloned sample from the GitHub repo or from the CLI.