Ask with Adaptive Cards

Article
07/12/2024

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.

Adaptive Cards enable you to add snippets of content to Copilot Studio copilots that can also be openly exchanged with other cloud apps and services. To provide rich conversation capability for your copilot, you can include text, graphics, and buttons, as a JSON representation. Because they're platform-agnostic, you can easily tailor Adaptive Cards to your needs.

You design Adaptive Cards using the Adaptive Cards Designer or author directly using JSON code. The Adaptive Card node allows you to send an Adaptive Card containing one or more submit buttons, and optionally, one or more form input fields. Copilot Studio then stores user responses in variables for use later in the conversation.

The node allows you to provide the JSON for the card you want to send to the user or provide a Power Fx formula to represent the card, allowing you to include dynamic information on the card. Other properties on the node allow you to control behavior, such as what to do when the user enters an invalid response and if the node can be interrupted.

The Adaptive Card node is used for interactive cards, where the user is expected to submit a response. Message and Question nodes can be used to present the user with a non-interactive card to display information to the user.

Prerequisites

Create and edit topics

Add an Adaptive Card node

Select Add node (+), then select Ask with Adaptive Card.
Select the More icon (…) of the node, and then select Properties.

The properties pane of the node appears.
In the Edit JSON section, enter the JSON for your card.

To open a larger view of the JSON editor, select the Expand icon.

Tip

Your card must contain at least one submit button, as it must be an interactive card that allows a user to submit information back to the copilot. If it doesn't and is only intended to show information to the copilot user, you should add your card as an attachment to a Message node.
After adding the JSON code for your card to the editor, select outside of the editor. The node is updated with a preview of your card. Copilot Studio automatically creates output variables based on the inputs detected within the card.

Tip

If the output variables generated for your card are incorrect, you can manually update the list of variables and their types by selecting the Edit Schema button underneath the JSON editor in the property pane. This example defines four string (Text) variables.
Your interactive Adaptive Card is now ready. When a user of your copilot uses a submit button on a card, the output variables are populated with their responses.

Other properties

Other properties allow you to control the behavior of the Adaptive Card node, such as:

How the copilot responds to an invalid response
If it can be interrupted

If the copilot is currently awaiting a submission from an Adaptive Card and the user sends a text message instead, this is considered to be an invalid response, unless the message triggers an interruption. In this case, the following properties determine the behavior.

How many reprompts: The number of times your copilot tries to get a valid submission from the card. Repeat up to 2 times is the default. You can also select Repeat once or Don't repeat. For each retry, the card is resent to the user.
Retry prompt: Use this property to define a message to be sent when a retry occurs, along with a repeat of the card. To define a retry message, select Customize, then enter the new prompt.
Allow switching to another topic: If checked (default), an incoming message from a user when the copilot is awaiting a card submission triggers an interruption and switch to another topic. If a topic switch occurs, the card is sent again to the user once the interrupting topic has completed.

Use Power Fx to make your card dynamic

You can use Power Fx to include dynamic information on your card by referencing one or more variables from your topic or copilot within the card.

Select the More icon (…) of the node, and then select Properties.

The properties pane for the node appears.
Select the Edit JSON button, then choose Formula. Selecting Formula automatically converts the JSON in the card into a Power Fx representation.

JSON example

Here's a JSON example of a card and the resulting Power Fx, where two variables Topic.Title and Topic.Subtitle are used instead of a hard-coded text.

  {
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [
        {
            "type": "ColumnSet",
            "columns": [
                {
                    "type": "Column",
                    "width": 2,
                    "items": [
                        {
                            "type": "TextBlock",
                            "text": "Tell us about yourself",
                            "weight": "Bolder",
                            "size": "Medium",
                            "wrap": true,
                            "style": "heading"
                        },
                        {
                            "type": "TextBlock",
                            "text": "We just need a few more details to get you booked for the trip of a lifetime!",
                            "isSubtle": true,
                            "wrap": true
                        },
                        {
                            "type": "Input.Text",
                            "id": "myName",
                            "label": "Your name (Last, First)",
                            "isRequired": true,
                            "regex": "^[A-Z][a-z]+, [A-Z][a-z]+$",
                            "errorMessage": "Please enter your name in the specified format"
                        }
                    ]
                }
            ]
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit"
        }
    ]
  }

Power Fx

  {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "ColumnSet",
      "columns": [
        {
          "type": "Column",
          "width": "2",
          "items": [
            {
              "type": "TextBlock",
              "text": "Topic.Title",
              "weight": "Bolder",
              "size": "Medium",
              "wrap": true,
              "style": "heading"
            },
            {
              "type": "TextBlock",
              "text": "Topic.Subtitle",
              "isSubtle": true,
              "wrap": true
            },
            {
              "type": "Input.Text",
              "id": "myName",
              "label": "Your name (Last, First)",
              "isRequired": true,
              "regex": "^[A-Z][a-z]+, [A-Z][a-z]+$",
              "errorMessage": "Please enter your name in the specified format"
            }
          ]
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Submit"
    }
  ]
}

Share via