Return rich responses with Adaptive Cards

2 minutes

When an agent uses an action with an API plugin to return a response, it takes the information from the API and processes it using the language model. The language model returns a human-friendly response that matches the agent's instructions. Building responses dynamically based on either the predefined, or the user's instructions, makes the agent highly flexible. You can, for example, ask it to provide the information as a bulleted list or a table. This flexibility comes, however, at a price: the agent might not always understand what's the best way to present the information.

Because APIs typically return structured data, you might want to control how the agent presents the information to the user. To control how the agent presents data from the API, define an Adaptive Card template in the API plugin.

To define the Adaptive Card template that the agent should use to display the data from the API, use the static_template property in the response semantics portion of the API plugin definition. The following snippet shows an example Adaptive Card template:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "Image",
          "url": "${image_url}",
          "size": "large"
        },
        {
          "type": "TextBlock",
          "text": "${name}",
          "weight": "Bolder"
        },
        {
          "type": "TextBlock",
          "text": "${description}",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "Allergens: ${if(count(allergens) > 0, join(allergens, ', '), 'none')}",
          "weight": "Lighter"
        },
        {
          "type": "TextBlock",
          "text": "**Price:** €${formatNumber(price, 2)}",
          "weight": "Lighter",
          "spacing": "None"
        }
      ]
    }
  ]
}

Notice the ${…} expressions which refer to the properties in API response, and which are a part of Adaptive Card templating. At runtime, the agent takes the data that the function returns and overlays it on top of the template you provide, creating an Adaptive Card filled with data.

When your API returns multiple items, the agent uses the Adaptive Card to show a single item. Users see the card by hovering over a citation:

Important

When building Adaptive Cards for functions, keep in mind that they always show a single item. It might feel counterintuitive at first to build a card for a single item when implementing functions that return multiple items. Remember that the agent constructs the response to the user using an LLM, but still wants to offer the ability to show a richer preview of each item, which is why you need to provide it with a template for a single item rather than the whole API response.

When the API returns a single item, the agent might include the card directly in its response:

Tip

When building Adaptive Cards for use with functions, you'll find it the most convenient to build each card template in a separate file. Using the Adaptive Card Previewer Microsoft 365 Agents Toolkit extension, you can create a data file and preview your card directly in Visual Studio Code. When your card is ready, copy its contents to the API plugin definition file.

Return rich responses with Adaptive Cards

Feedback