Skip to main content

How to Send an Adaptive Card in the Microsoft 365 Agents SDK in C#

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

An Adaptive Card shows information in a chat as a neat little layout instead of a wall of text, and the chat app draws it in its own style. In the Microsoft 365 Agents SDK, sending one takes an attachment with the right content type and one call to SendActivityAsync.

Syntax​

C#
Attachment card = new()
{
ContentType = ContentTypes.AdaptiveCard,
Content = cardJson
};

await turnContext.SendActivityAsync(MessageFactory.Attachment(card), cancellationToken);
  • Attachment is the SDK's class for anything attached to a message: a file, a card, an image.
  • ContentType says what the attachment is. ContentTypes.AdaptiveCard is the content type for Adaptive Cards, application/vnd.microsoft.card.adaptive.
  • cardJson is the card itself. Give it the card's JSON as a JsonNode, for example JsonNode.Parse(text) for JSON you've read from a file. Microsoft's example in the Agents SDK documentation assigns the JSON text directly, which the SDK also sends as JSON.
  • MessageFactory.Attachment(card) builds a message activity that carries the attachment.
  • turnContext and cancellationToken are the ones your route handler receives.

The Example​

The agent for this post answers menu with a card that shows today's lunch: a title and three dishes. The card lives in a JSON file of its own, Cards/MenuCard.json:

Cards/MenuCard.json
{
"type": "AdaptiveCard",
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"text": "Today's lunch",
"size": "Large",
"weight": "Bolder"
},
{
"type": "FactSet",
"facts": [
{ "title": "Soup", "value": "Tomato and basil" },
{ "title": "Main", "value": "Vegetable lasagne" },
{ "title": "Dessert", "value": "Apple crumble" }
]
}
]
}
  • version is the version of the card format. 1.5 is the highest that Microsoft Teams and Microsoft 365 Copilot Chat support, according to Microsoft's design guidance for agents.
  • body is what the card shows, from top to bottom: a large bold TextBlock for the title, then a FactSet, which lays out title and value pairs in two columns.

The agent is one class in an ASP.NET Core project with the Agents SDK, hosted with AddAgent<LunchMenuAgent>() 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: Put the Card in the Project​

Create a folder called Cards in the project folder and save the JSON above in it as MenuCard.json.

ASP.NET Core projects copy .json files into the build output every time they build, so the card ends up next to the agent's compiled files, in bin/Debug/net10.0/Cards, without any change to the project file.

Step 2: Send It from a Route​

LunchMenuAgent.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;

namespace LunchMenu;

public class LunchMenuAgent : AgentApplication
{
private static readonly string MenuCardJson =
File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Cards", "MenuCard.json"));

public LunchMenuAgent(AgentApplicationOptions options) : base(options)
{
OnMessage("menu", SendMenuAsync);
}

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

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

LunchMenuAgent.cs in a macOS-style editor window: the card file is read once into MenuCardJson, the menu route calls SendMenuAsync, and SendMenuAsync wraps the parsed JSON in an Attachment with ContentTypes.AdaptiveCard and sends it with MessageFactory.Attachment

  • MenuCardJson reads the file once, the first time the class is used. The SDK creates a new agent object for every message, so reading the file in a static field saves reading it again each time. AppContext.BaseDirectory is the folder that holds the agent's compiled files.
  • JsonNode.Parse(MenuCardJson) turns the text into JSON. It does that on every send, so each message gets its own copy of the card.
  • OnMessage("menu", SendMenuAsync) sends the card whenever someone types menu.

Step 3: 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 menu:

The Agents Playground chat: the message menu, answered by a card titled Today's lunch listing Soup Tomato and basil, Main Vegetable lasagne and Dessert Apple crumble

The Playground drew the JSON as a card: the title large and bold, and the facts in two neat columns. To change the menu, change the file and restart the agent; the code stays the same.

Common Mistakes​

MistakeWhat happensDo this instead
Typing the content type by handOne wrong character and the attachment is no longer an Adaptive CardUse the ContentTypes.AdaptiveCard constant
Using a version higher than the host supportsThe host may not draw parts of the cardUse 1.5 for Teams and Microsoft 365 Copilot Chat
Reading the file from a relative pathIt depends on the folder the agent was started fromCombine AppContext.BaseDirectory with the file's path

Troubleshooting​

SymptomLikely causeFix
The agent doesn't answer menuNo route for it, or the agent isn't runningCheck the route and the agent's terminal
The turn fails with an exception about the JSONThe card file isn't valid JSONCheck the file; a designer or editor with $schema support shows the error

FAQ​

Can I send text and a card in one message?​

Yes. MessageFactory.Attachment takes the message text as its second parameter: MessageFactory.Attachment(card, "Here's today's lunch:").

Can I send more than one card in one message?​

Yes. MessageFactory.Attachment also accepts a list of attachments, and MessageFactory.Carousel sends a list with the carousel layout, which chat apps that support it show side by side.

How do I design a card without writing the JSON by hand?​

Use the Adaptive Cards Designer: How to Design an Adaptive Card with the Adaptive Cards Designer.

Conclusion​

To send an Adaptive Card, put its JSON in an Attachment with the content type ContentTypes.AdaptiveCard, wrap it in a message with MessageFactory.Attachment, and send it with SendActivityAsync. Keeping each card in a JSON file of its own lets you change what it shows without touching the code.

Additional Resources​