Skip to main content

How to Test an Agent Locally with the Microsoft 365 Agents Playground

· 9 min read
Jagdish Kumawat
Founder @ Dewiride

You don't need Microsoft Teams, an Azure subscription or an app registration to talk to an agent you're building. The Microsoft 365 Agents Playground is a chat window that runs on your machine, pretends to be a channel such as Teams, and shows you every request that passes between it and your agent.

The Playground, formerly the Teams App Test Tool, is Microsoft's local test client for agents built with the Microsoft 365 Agents SDK, the Teams SDK or the Bot Framework. It's a small Node.js program: you start your agent, start the Playground with your agent's address, and chat with it in your browser. Microsoft labels it a preview.

Syntax​

Terminal
agentsplayground -e <endpoint> -c <channel> [options]
  • -e <endpoint> (--app-endpoint) is the address your agent receives activities on. If you leave it out, the Playground uses http://localhost:3978/api/messages.
  • -c <channel> (--channel-id) is the channel the Playground pretends to be: msteams, webchat, emulator, directline (another name for webchat) or agents.
  • [options] are optional settings, such as -p <port> for the Playground's own port (56150 by default). The full list is at the end of this post.

The Example​

The agent for this post is about as small as an agent gets: an ASP.NET Core app with the Microsoft 365 Agents SDK, listening on port 3978, that answers every message with You said: and the text. Its whole logic is one class:

DemoAgent.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;

namespace PlaygroundDemo;

public class DemoAgent : AgentApplication
{
public DemoAgent(AgentApplicationOptions options) : base(options)
{
OnActivity(ActivityTypes.Message, ReplyAsync);
}

private async Task ReplyAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
}
}

Any agent works the same way, in any language: the Playground only needs the address of its /api/messages endpoint.

Prerequisites​

  • Node.js, with npm, to install the Playground. Check with node --version; this post used Node.js 24.
  • An agent you can run locally, listening on a known port, with anonymous access allowed while you test. An Agents SDK agent running in the Development environment allows it by default.

Step 1: Install the Playground​

The Playground is an npm package. Install it globally, so the agentsplayground command works from any folder:

Terminal
npm install -g @microsoft/m365agentsplayground
Output
added 1 package in 2s

It's a single package with no install scripts, so npm 12's script approval doesn't get in the way. Check the version:

Terminal
agentsplayground --version
Output
0.2.30

The package also installs a second command, teamsapptester, from the Playground's days as the Teams App Test Tool.

Step 2: Start Your Agent​

Start your agent the way you normally do. For the .NET example, that's dotnet run in the project folder, and the line to look for is the address it listens on:

Output (excerpt)
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:3978
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.

Leave it running. The agent's endpoint is that address plus /api/messages.

Step 3: Start the Playground​

Open a second terminal and start the Playground with your agent's endpoint, as the emulator channel, a plain test channel:

Terminal 2
agentsplayground -e http://localhost:3978/api/messages -c emulator
Output
Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"channelId":"emulator","deliveryMode":"unspecified","eventsRecordingEnabled":"false","authenticationConfigured":"false"}}

Listening on 56150

The Playground runs its own small server on port 56150 and opens it in your browser. The Telemetry: line is one of the usage events the Playground collects for Microsoft; starting it with --disable-telemetry turns that collection off. It connects to your agent and sends it a conversationUpdate, the activity that says a conversation has started.

Type a message and press Enter:

The Microsoft 365 Agents Playground in the browser: a toolbar with Mock an Activity, Configure Authentication and Debug Options and the mock user Alex Wilber; a chat list with Personal Chat, Group Chat and the Teams channels General and Announcements; the personal chat with the message Hi, Playground! and the agent Test Bot's reply You said: Hi, Playground!; and on the right the Log Panel listing the conversationUpdate, the message and the reply

You're Alex Wilber, the Playground's made-up user, and your agent appears as Test Bot. The chat list on the left lets you try the agent in a personal chat, a group chat or a team's channels.

Step 4: Read the Log Panel​

The Log Panel on the right records every request. Microsoft 365 Agents Playground → User Application lines are activities sent to your agent, with the status code your agent answered: 202, accepted. User Application → Microsoft 365 Agents Playground lines are what your agent sent back, answered with 201, created.

Click a line to see the request in full. Request shows the JSON that was sent, and Response what came back:

The Log Panel with the line message 202 Hi, Playground! selected, and below it the Request tab showing the message activity's JSON: type message, the text Hi, Playground!, its id, from with id user-id-0, name Alex Wilber and an aadObjectId, the timestamp and the local timestamp

This is the fastest way to see exactly what your agent received and what it answered, field by field.

Step 5: Test as Teams or Web Chat​

Channels send different activities, so test with the one your agent will meet. Stop the Playground with Ctrl+C and start it again with another -c value; your agent can keep running.

Terminal 2
agentsplayground -e http://localhost:3978/api/messages -c msteams

As Teams, the window looks the same, but the activities change. When it connects, the Playground also sends an installationUpdate, the way Teams tells an agent it was installed:

The Log Panel in Teams mode: conversationUpdate 202, then installationUpdate 202 selected, then the message and the reply; the Request tab shows the installationUpdate activity's JSON with its type, id, from, timestamp, serviceUrl and a personal conversation

Terminal 2
agentsplayground -e http://localhost:3978/api/messages -c webchat

As Web Chat, the whole window changes to a Web Chat conversation, the kind you'd embed in a website:

The Playground as Web Chat: no chat list and no user picture, just the conversation, with the message Hi, Playground! on the right, the reply You said: Hi, Playground! on the left, and a Type your message box at the bottom, beside the same Log Panel

Useful Options​

agentsplayground --help lists every option. These are the ones you'll reach for most when testing a local agent:

OptionWhat it does
-p, --portThe Playground's own port. Default 56150, or a random one if that's taken
--conversation-idA fixed conversation id instead of a new one each time; in Teams mode, for the personal chat
--delivery-modeSets the activities' deliveryMode to default or expectReplies
--disable-telemetryStops sending usage data to Microsoft
--hostThe address the Playground listens on. Default 127.0.0.1; anything else exposes it to your network
--client-id, --client-secret, --tenant-idCredentials, for testing an agent that requires authentication

The --target option starts it against a Direct Line or Copilot Studio conversation instead of a local endpoint.

Stop and Clean Up​

Press Ctrl+C in the Playground's terminal and in your agent's. The Playground writes its own log to a devTools folder, as m365agentsplayground.log, in the folder you started it from; delete the folder when you no longer need it. To remove the Playground itself, run npm uninstall -g @microsoft/m365agentsplayground.

Common Mistakes​

MistakeWhat happensDo this instead
Leaving out /api/messages in -eThe Playground can't deliver activities to the agentGive the full endpoint: http://localhost:3978/api/messages
Starting the Playground before the agentIt can't connectStart the agent first, then the Playground
Testing only in the emulator channelCode that reads Teams-specific fields never runsTest with -c msteams or -c webchat too
Exposing the Playground with --host 0.0.0.0Anyone on your network can reach itKeep the default 127.0.0.1

Troubleshooting​

SymptomLikely causeFix
agentsplayground: command not foundIt isn't installed, or npm's global folder isn't on your PATHInstall it again and open a new terminal
The Playground doesn't connectThe agent isn't running, or listens on another portCheck the agent's Now listening on line and match -e to it
The Playground starts on a different portPort 56150 was in useUse the port it prints, or free 56150

FAQ​

Does the Playground send anything to Teams or the cloud?​

Your messages don't: the Playground plays the channel's part itself, at http://localhost:56150/_connector. It does collect usage data for Microsoft, unless you start it with --disable-telemetry.

What can't the Playground test?​

It renders Adaptive Cards, but no other card types. Microsoft lists typing indicators, dialogs, single sign-on, tabs, meetings and the mobile experience among what it can't emulate, and it shows a warning in the conversation and the Log Panel when your agent uses something it doesn't support. Test those in the Teams client.

Is the Playground enough before going to production?​

No. Microsoft recommends testing your agent in the Teams client before you move it to production. The Playground is for the fast inner loop: change code, restart, chat.

Can I change the made-up user or team?​

Yes. A .m365agentsplayground.yml file in the folder you start the Playground from customizes its mock users, chats and teams. Microsoft's documentation describes the format.

Conclusion​

Install the Playground with npm install -g @microsoft/m365agentsplayground, start your agent, and run agentsplayground -e <your endpoint> -c <channel>. You get a chat with your agent in your browser, a Log Panel with every request in full, and the Teams, Web Chat and emulator channels to test against, all without an account or a cloud resource.

Additional Resources​