Designing Adaptive Cards For Agents

So, you have caught the bug and have been building Copilot Studio agents. From topics, to variable management, Power Automate flows or event agent flows, you are enjoying it all. You have even ventured into new UI horizons by either using native formatting options or HTML. And yet, something is missing. You are eager for more.

Ready to enter the next level of your Copilot Studio game? Because using Adaptive Cards may be just it.

In a nutshell, here is what they can do for YOU and YOUR USERS’ experience.

• 🎨 Rich UI: Enable visually appealing and interactive content in chats (e.g., text, images, buttons, forms).

• 🔄 Dynamic Content: Easily populate cards with data at runtime for personalized experiences.

• 🤖 Better Engagement: Improve user interaction and decision-making with structured responses.

• 🧩 Platform Agnostic: Work consistently across Microsoft Teams, Outlook, and other channels or cloud services.

• ⚙️ Low-Code Friendly: Design and update cards easily with JSON, without deep coding skills.

Don’t let Adaptive Cards be your weakness! Whether you are just starting off or are more advanced in your path, I wanted to share some resources that helped me along the way, some tough-earned lessons turned into practical tips and tricks!

• Getting started: There are of course Microsoft Learn resources to get you started.

• The documentation hub: Your one-stop Microsoft shop for all the related documentation to Adaptive Cards. Truly a treasure trove, as it explains a lot of the key components to explore, as well as advanced ones, and all the JSON terms behind them.

• GitHub samples and more: You can find here a lot of great assets, including a series of samples created to get you started across layouts and devices.

No matter how you look at it, when it comes to Adaptive Cards, it is a bit of an advanced feature considering JSON is involved. That does not mean it is only for developers, but it does mean it is worth familiarizing yourself with some of the tips and tricks in configuring those little UI gems.

If you are a pro at this, you may go straight into your code editor in your Copilot Studio agent and start creating your card. Sure, level 10 of UI Jumanji was meant for you. But what if, you cannot or do not want to start there?

Enter the amazing Adaptive Card Designer site! This website will allow you to drag and drop components to create your card, plus configure in as much of a low-code way as possible, your components. To make things even better, it will allow you to visualize and preview your card, WHILST creating the full JSON for it. Winner winner chicken dinner!

As you enter the site mentioned above, you will get presented with a blank adaptive card to start with.

Here are some of the key areas to be familiar with in your Adaptive Card journey, as numbered in the screenshot shown above, can help you with the following:

1. These are the elements you can drag and drop into your card. Keep scrolling as they is plenty more!

2. This is the area where you drag and drop, to help you visualize your mock up. Of course, once you are done, you can also click Preview on the top right.

3. As you start adding elements to your card, the component/ solution tree if you may will appear here in a but of a hierarchical order. It may even resemble a little bit what you are used to seeing in the Power Apps maker portal!

4. Once you have started adding component elements, you can configure each of their properties in this area. This is the more low-code way, but there are still some pro-dev caveats to bear in mind here too! (More on this further down).

5. Finally, your card’s JSON snippet will appear here. Not only does this mean it auto-populates, but it doubles up as a live code-editor. This is very useful, as you may occasionally prefer amending things there directly. I sue found it helpful at times when I knew exactly what I wanted to configure after a few iterations of cards. Or even better, when you have your favorite layout ready to paste from another card!

Just like in a jungle mission, having a strategy in place is crucial. Starting with a mock up, even if it is in Power Point. Let’s have a look at what an example card will look like.

So how does this look? This is a nice Adaptive Card to upsell an extra service as part of a hotel booking agent.

But what components do you have to use to bring this to life.

In the Adaptive Card designer, the structure will look like the below, and see how the respective numbering applies:

1)      This is a text block component dragged as our first element to the top. You first add the actual text in the Text field in the TextBlock section, which reads Fancy a welcome basket?. As this is needed as a heading to stand out, the Base Style will be set to Heading and the Size to Large. These can be found in the Style section. Remember, you can make it your own by changing a few other details.

2)      This is a text block component dragged as he second element from the top. You will add the actual text in the Text field in the TextBlock section, which reads We can arrange for a personalised luxury basket to wait in your room on arrival. 

Since this is needed as the main body and you do not need it to stand out in any special way, no other aspects have been customized.

3)      This is an Image component dragged to the middle as the hero image.

To populate this, you can add the URL of where this image is hosted.

Whether it is in your own SharePoint instance, or elsewhere, you are the adventurer here! Do not forget though your accessibility-friendly tag in the Alternate text field.

4)      This is where things start getting interactive with your Adaptive Card. As much fun as it is to see cool images and text, Adaptive Cards are a great way to interact with users and drive their preferences into actions. In this case, you can upsell a hotel service as part of the booking process. Should the user want to purchase this extra service, their booking and thus total price will update accordingly. The CRM app will automatically be notified through some extra configuration and you have zero extra manual effort from either the user or Customer Service representatives.

To build it, go back to the Adaptive Card root at the top of the Card Structure area, and scroll to the bottom of the Element Properties. After selecting Add an action, select Action.Submit.

After that, you can start configuring your primary action button. First up, add the Title of the button as Yes, add it. To make it stand out, select Primary in the Mode field, and Positive in Style. This turns the button blue. (Destructive in Style would turn it red). To personalize things further, you can add an icon for the action button by clicking on the three-dot ellipsis. If you are looking for something specific, you can search through the Search the icon catalog feature.

The final piece of the puzzle is mapping the button to actionable data. To do that, you will select a variable name e.g. in this case welcomeBasketChoice and the value when this button is selected as Yes. This is all captured in the Data field. The way to do it is {“ variable name”:”value”} and replacing what is in bold accordingly.

5)      Just like we did earlier, time to set up our secondary action button. To build it, you go back again to the Adaptive Card root at the top of the Card Structure area, and scroll to the bottom of the Element Properties. After selecting Add an action again, select Action.Submit.

After that, you can start configuring the button. First up, add the Title of the button as Not now. To make it a proper secondary action button, select Primary in the Mode field, and Default in Style. This turns the button white. To personalize things further, remember to add an icon by clicking on the three-dot ellipsis. If you are looking for something specific, you can always search through the Search the icon catalog feature.

The final piece of the puzzle is mapping the button to actionable data. You have already selected a variable name as welcomeBasketChoice, so time to select the value when the button is clicked. In this case, it is No. This is all captured in the Data field. As a reminder, the way to do it is {“ variable name”:”value”} and replacing what is in bold accordingly.

After all this hard word, wouldn’t you want to preview what your Adaptive Card looks like? Even better, would you not want to test-drive it for different device sizes? Look no further, if you click on Preview all this is available at a glance.

After you are done, you can copy the code into your agent by clicking on Copy card payload. Et voila!

If you want to play around with the JSON of this Adaptive Card, here you go.

You can, at any point, amend the Card payload editor with your own JSON edits. Live code editing, at its best! And you get to see the element properties update as you along.