Skip to main content

How to Send a Custom Activity from the Microsoft 365 Agents Playground

· 7 min read
Jagdish Kumawat
Founder @ Dewiride

Some activities never come from typing: a web page telling your agent the user switched to dark mode, a thumbs-up on a reply. The Microsoft 365 Agents Playground can send them anyway. Its Custom activity option lets you write any activity as JSON and deliver it to your agent, so you can test the code that handles it on your own machine.

The Example​

The agent for this post handles one event, an activity a client sends to tell the agent something happened. Events carry a name, which says what happened, and a value, with whatever data goes with it. This agent listens for an event named themeChanged and answers with what it received:

ThemeAgent.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;

namespace EventDemo;

public class ThemeAgent : AgentApplication
{
public ThemeAgent(AgentApplicationOptions options) : base(options)
{
OnEvent("themeChanged", OnThemeChangedAsync);
}

private async Task OnThemeChangedAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
await turnContext.SendActivityAsync($"Got the {turnContext.Activity.Name} event with this value: {turnContext.Activity.Value}", cancellationToken: cancellationToken);
}
}

OnEvent("themeChanged", ...) registers a handler for events with that name; the handler reads the event's Name and Value from turnContext.Activity. A chat box can't send this event, which is why the Playground's custom activity is the way to test it.

Prerequisites​

  • The Microsoft 365 Agents Playground, installed and able to reach your agent. agentsplayground --version should print 0.2.30.
  • An agent running locally, listening on a known port; this one listens on http://localhost:3978.

Step 1: Start the Agent and the Playground​

Start your agent, then start the Playground with its endpoint:

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

The Playground opens in your browser and connects to the agent. Microsoft notes that Custom activity is there even in channels where a predefined trigger isn't; this post uses emulator.

Step 2: Open Custom Activity​

Select Mock an Activity in the Playground's toolbar. The menu lists the activities it can send for you. In the emulator channel, that's adding or removing a user or an application, and Custom activity:

The Mock an Activity menu in the emulator channel: Trigger Conversation Update Activity with Add user, Add application, Remove user and Remove application, and Trigger Custom Activity with Custom activity

As Teams (-c msteams), the menu has more: installing and uninstalling the app, and channel and team events. Select Custom activity.

Step 3: Write the Activity​

The Custom activity dialog opens with a JSON activity that's already addressed to your agent: an id, a timestamp, the channelId, the serviceUrl replies go to, the recipient (your agent), the conversation and the from (the Playground's made-up user). Its last line is a placeholder:

The last line of the prefilled activity
"type": "<custom-activity-type>"

Replace that line with the type you want and the fields it needs. For the example's event:

Replace the type line with these three
"type": "event",
"name": "themeChanged",
"value": { "theme": "dark" }
  • "type": "event" makes it an event activity.
  • "name" is the name your agent's OnEvent route listens for.
  • "value" is the event's data; any JSON works, and here it's an object with one property.

Leave the prefilled fields as they are: they make sure the activity reaches your agent in the current conversation.

The Custom activity dialog: a JSON editor with the prefilled serviceUrl, recipient Test Bot, conversation and from fields, and the new lines type event, name themeChanged and value theme dark, above the Send activity and Cancel buttons

Step 4: Send It and Check the Result​

Select Send activity. The agent's OnEvent route runs, and its answer appears in the chat:

The agent Test Bot's reply in the Playground chat: Got the themeChanged event with this value: theme dark, written as JSON

To see exactly what was sent, click the new event 202 line in the Log Panel. Its Request tab shows the whole activity:

The Log Panel with the line event 202 selected, and the Request tab showing the event activity's JSON with its id, timestamp, channelId emulator, serviceUrl and recipient

The event activity (Log Panel, Request tab)
{
"id": "872524ff-0fb5-4cf6-b119-6aa4c7b46f80",
"timestamp": "2026-11-21T05:20:53.074Z",
"channelId": "emulator",
"serviceUrl": "http://localhost:56150/_connector",
"recipient": {
"id": "00000000-0000-0000-0000-00000000000011",
"name": "Test Bot"
},
"conversation": {
"id": "f6820baa-06b0-4171-878d-7c5dd6db1a6e",
"conversationType": "personal",
"tenantId": "00000000-0000-0000-0000-0000000000001"
},
"from": {
"id": "user-id-0",
"aadObjectId": "00000000-0000-0000-0000-0000000000020"
},
"type": "event",
"name": "themeChanged",
"value": {
"theme": "dark"
}
}

The prefilled fields and your three lines, exactly as you wrote them. 202 next to it means your agent accepted the activity.

Other Activities to Send​

The same dialog sends any activity type. Microsoft's own example sends a reaction: replace the type line with "type": "messageReaction", a reactionsAdded list such as [{ "type": "like" }], and a replyToId with the id of the agent message being reacted to, which you can copy from the Response tab of that message's line in the Log Panel. Whatever you send, your agent needs a route that matches it, or nothing answers.

Common Mistakes​

MistakeWhat happensDo this instead
Deleting or changing the prefilled fieldsYour agent sees a different sender, recipient or conversation than the chat you're testingChange only the type line and add your own fields
Leaving a comma after the last field, or none between fieldsThe dialog's JSON is invalidSeparate fields with commas, with none after the last one
A name that differs from your route'sThe agent receives the event but no route runsUse exactly the name in OnEvent, letter for letter
Using invoke for a one-way signalInvokes expect an answer in the response to the request itselfUse event, which the protocol designed for signals

Troubleshooting​

SymptomLikely causeFix
No answer, and the Log Panel shows event 202The agent accepted the event, but no route matched itCheck the event's name against your OnEvent route
The answer shows the value as JSON, such as {"theme":"dark"}Activity.Value holds the JSON from the activityDeserialize it to your own type when you need its properties

FAQ​

Do I need to fill in the id and timestamp myself?​

No. The dialog prefills them along with the rest of the addressing; you only change the type and add the fields that type needs.

Can I send the same custom activity again?​

Open Custom activity again and write it again. Each send is a new activity with its own id.

Does this work for agents not built with the Agents SDK?​

Yes. The Playground delivers the activity to whatever endpoint you gave it, so any agent that speaks the Activity Protocol receives it.

Conclusion​

To test code for activities a chat box can't produce, open Mock an Activity → Custom activity in the Agents Playground, replace the "type": "<custom-activity-type>" line with your activity's type and fields, and select Send activity. The Log Panel's Request tab then shows exactly what your agent received.

Additional Resources​