Skip to main content

How to Handle Adaptive Card Submit Actions in the Microsoft 365 Agents SDK in C#

· 7 min read
Jagdish Kumawat
Founder @ Dewiride

When someone selects an Action.Submit button on an Adaptive Card, the card's inputs come back to your agent. In the Microsoft 365 Agents SDK, a route for the button's verb hands them to your handler, ready to read into a C# record.

Syntax​

C#
AdaptiveCards.OnActionSubmit(verb, handler);

private async Task handler(ITurnContext turnContext, ITurnState turnState, object data, CancellationToken cancellationToken)
  • AdaptiveCards is a property of every AgentApplication, with the routes for card actions.
  • verb is the text the button carries in the verb field of its data. The route matches it exactly, case included. Instead of a string, you can pass a Regex to match several verbs, or a route selector of your own.
  • handler is your method, with the four parameters shown.
  • data is what the card sent: the value of every input, under each input's id, plus the fields of the button's data. Read it into a type of your own with ProtocolJsonSerializer.ToObject<T>(data).

The route matches a message that has no text and a value whose verb is the one you registered. That's exactly what a chat app sends when someone selects an Action.Submit button.

The Example​

The agent for this post answers rate with a one-question card: How was lunch today?, with three choices and a Send button. It thanks the person for their rating. The card is small, so it lives in the code as a C# raw string literal, the JSON between two """ marks:

The rating card
{
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "Input.ChoiceSet",
"id": "rating",
"label": "How was lunch today?",
"style": "expanded",
"isRequired": true,
"errorMessage": "Pick one.",
"choices": [
{ "title": "Great", "value": "Great" },
{ "title": "Fine", "value": "Fine" },
{ "title": "Not good", "value": "Not good" }
]
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Send",
"data": { "verb": "rateLunch" }
}
]
}
  • The input's id is rating, so its value comes back as rating.
  • The button's data is an object with a verb, rateLunch. That's the value the route will match.

The agent is one class in an ASP.NET Core project with the Agents SDK, hosted with AddAgent<LunchRatingAgent>() and listening on port 3978.

Prerequisites​

  • The Microsoft 365 Agents Playground, to chat with the agent on your own machine. agentsplayground --version should print 0.2.30; if the command isn't found, install it with npm install -g @microsoft/m365agentsplayground.

Step 1: Send the Card and Route Its Button​

LunchRatingAgent.cs
using System.Text.Json.Nodes;
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;
using Microsoft.Agents.Core.Serialization;

namespace LunchRating;

public class LunchRatingAgent : AgentApplication
{
private const string RatingCardJson = """
{
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "Input.ChoiceSet",
"id": "rating",
"label": "How was lunch today?",
"style": "expanded",
"isRequired": true,
"errorMessage": "Pick one.",
"choices": [
{ "title": "Great", "value": "Great" },
{ "title": "Fine", "value": "Fine" },
{ "title": "Not good", "value": "Not good" }
]
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Send",
"data": { "verb": "rateLunch" }
}
]
}
""";

public LunchRatingAgent(AgentApplicationOptions options) : base(options)
{
OnMessage("rate", SendRatingCardAsync);
AdaptiveCards.OnActionSubmit("rateLunch", RateLunchAsync);
}

private async Task SendRatingCardAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
Attachment card = new()
{
ContentType = ContentTypes.AdaptiveCard,
Content = JsonNode.Parse(RatingCardJson)
};

await turnContext.SendActivityAsync(MessageFactory.Attachment(card), cancellationToken);
}

private async Task RateLunchAsync(ITurnContext turnContext, ITurnState turnState, object data, CancellationToken cancellationToken)
{
LunchRatingValues values = ProtocolJsonSerializer.ToObject<LunchRatingValues>(data);

await turnContext.SendActivityAsync($"Thanks! You rated today's lunch: **{values.Rating}**.", cancellationToken: cancellationToken);
}
}

public record LunchRatingValues(string? Rating);

LunchRatingAgent.cs in a macOS-style editor window: the constructor registers the rate message route and AdaptiveCards.OnActionSubmit for the rateLunch verb, and RateLunchAsync reads the submitted data into a LunchRatingValues record and thanks the person for their rating

  • AdaptiveCards.OnActionSubmit("rateLunch", RateLunchAsync) sends every submit whose verb is rateLunch to RateLunchAsync.
  • LunchRatingValues is a record with a property for each value the agent wants. The SDK's JSON settings ignore the case of names, so the card's rating fills Rating. The verb in data has no property here, so the record simply leaves it out.
  • string?: every value a card sends is text, so read them as strings, and allow null, because a card leaves out inputs that were empty and not required.

Step 2: Try It​

Run the agent with dotnet run, then start the Agents Playground in a second terminal:

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

Send rate, and pick Great:

The Agents Playground chat: the message rate, answered by a card with the question How was lunch today? and the choices Great, Fine and Not good, with Great selected, and a Send button

Then select Send:

The chat after Send: the card is empty again, and the agent answered Thanks! You rated today's lunch: Great.

The submit reached RateLunchAsync, and the rating came through. The Playground clears a card's inputs after it sends them, which is why the choice is empty again. Your submit doesn't appear in the chat as a message; the Playground's Log Panel lists it as a message entry.

Common Mistakes​

MistakeWhat happensDo this instead
Leaving out data, or making it a plain stringNo verb arrives, so the route never matchesGive the button "data": { "verb": "..." }
A verb that differs in case between the card and the routeNo match: the comparison is exactUse the same text in both places
A catch-all message route registered before this one, without RouteRank.LastThe catch-all takes the submit, because a submit is a message tooRank the catch-all RouteRank.Last
Reading a check box into a boolThe turn fails with Cannot get the value of a token type 'String' as a booleanRead it as a string

Troubleshooting​

SymptomLikely causeFix
Selecting the button does nothingA required input is empty; the card shows its error messageFill it in
Another route answers the buttonThe verb doesn't match, or a catch-all ran firstCompare the verb in the card and the route, and rank the catch-all last
A property of your record is always nullIts name doesn't match the input's id, or the input was emptyMatch the names, and handle null
Cannot get the value of a token type 'String' as a booleanA card value read into a boolFixed: Cannot get the value of a token type 'String' as a boolean

FAQ​

Can I use an attribute instead of OnActionSubmit?​

Yes. [ActionSubmitRoute("rateLunch")] on the handler method registers the same route. Both are in the SDK; pick the style your other routes use.

Can one handler serve several buttons?​

Yes: register it for each verb, or pass a Regex that matches all of them, and tell them apart by the verb value in data.

My cards use a field other than verb. Can the route read that instead?​

Yes, it's a setting: How to Change the Field That Routes Adaptive Card Submits in the Microsoft 365 Agents SDK in C#.

Conclusion​

Give every Action.Submit button an object in its data with a verb, register AdaptiveCards.OnActionSubmit for that verb, and read the handler's data into a record of nullable strings with ProtocolJsonSerializer.ToObject<T>. The SDK does the matching, and your handler gets exactly what the card sent.

Additional Resources​