Local testing with the Microsoft 365 Agents Playground
The in-process DevTools plugin is deprecated and its npm package is marked so. A freshly scaffolded project does not use it: new App() has no plugins, one server on port 3978, and no second port. The local test tool is now the Microsoft 365 Agents Playground — a separate CLI that sends real HTTP requests to /api/messages, so you can chat with the bot and mock activities without a tunnel, a bot registration or a Teams client.
If an older project still lists the DevTools plugin, remove it from the App options and drop the package from package.json.
1. Install
npm install -g @microsoft/m365agentsplayground # provides the `agentsplayground` command
It installs globally, not as a project dependency. A standalone binary exists too (winget install agentsplayground).
2. Let the bot accept its requests
The Playground does not send a Bot Framework token. The SDK rejects unauthenticated requests by default (it logs No credentials configured … All incoming requests will be rejected), so a local run needs an explicit opt-in. The safest place is the environment of your local shell or .env, not the code:
# .env — local development only, never in a deployed environment
DANGEROUSLY_ALLOW_UNAUTHENTICATED_REQUESTS=true
The option form exists too:
import { App } from '@microsoft/teams.apps';
const app = new App({
dangerouslyAllowUnauthenticatedRequests: process.env.NODE_ENV === 'development',
});
- The flag disables inbound token validation even when credentials are configured, and the SDK logs a warning saying so. That is the point of the long name — never ship it enabled.
skipAuthis a deprecated alias of the same option; the quickstart pages still show it.- Do not open the port to the network while the flag is on.
3. Run
Start the bot (npm run dev, port 3978), then in a second terminal:
agentsplayground -e http://localhost:3978/api/messages -c emulator
The UI is at http://localhost:56150. Flags:
| Flag | Meaning |
|---|---|
-e, --app-endpoint |
The bot's messaging endpoint |
-c, --channel-id |
emulator, webchat, msteams, directline or agents — msteams mimics Teams payloads most closely |
--client-id, --client-secret, --tenant-id |
Credentials, when the bot validates tokens |
-p, --port |
Port of the Playground UI (default 56150) |
agentsplayground --help lists the rest.
4. What to use it for
| You want to | Use |
|---|---|
| Chat with the bot | The compose box; personal chat, group chat and channel views in the sidebar |
| Test a membership change, reaction, invoke or other non-message activity | Mock an Activity menu |
| See the HTTP exchange | The Log Panel (top right): request and response bodies |
| See your own logging | The bot's terminal: log.info(...), and LOG_LEVEL=debug for SDK debug lines |
| Check a card renders | Send it from a handler; design in the Adaptive Card Designer first |
Replacing the old tool: the DevTools "Activities" view maps to the Log Panel, "Chat" to the compose box, "Cards" to the Designer plus a send from the bot.
5. What it cannot do
- Sign-in and SSO. Those flows need the Bot Framework token service and the Teams client. Test
addOAuthFlowhandlers in Teams (authentication). - Teams-only UI. Tabs, dialogs, message-extension menus and the AI label are Teams client features; the Playground shows the raw payloads, not the rendering.
- Auth. It proves your handlers, not your credentials, endpoint or manifest. For those use
teams app doctor(cli-recipes) and a test in Teams.
6. The path to Teams
When the handlers behave, register the bot and test in the client: teams app create --name … --endpoint https://<tunnel-host>/api/messages --env .env, a tunnel to port 3978, then the install link from teams app get <id> --install-link. Turn the unauthenticated flag off before this step. The standard flow is in the vendored official guide teams-sdk-teams-dev.
Common pitfalls
- The bot answers
401or logs "All incoming requests will be rejected" — neither credentials nor the opt-in flag are set. - Nothing happens in the Playground — the endpoint must be the full
/api/messagesURL, and the bot must be running on that port. - Streaming behaves differently than in Teams — the 1:1-only rule and the two-minute window belong to the Teams service; judge streaming in Teams.
- A deployed bot accepts anything — the flag leaked into a deployed environment. Remove it and check the host's environment variables.