Ask with Adaptive Cards

2025-05-01

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

With an Adaptive Card node, your agent can show an Adaptive Card containing one or more submit buttons, and optionally, one or more form input fields. Your agent stores user input in variables for use later in the conversation.

Note

Copilot Studio supports the Adaptive Cards schema versions 1.6 and earlier. However, the appropriate schema version depends on the targeted host app:

The Bot Framework Web Chat component (that is, the default website integration pattern) supports version 1.6 but doesn't support Action.Execute
The live chat widget (used for Dynamics 365 Omnichannel for Customer Service) is limited to version 1.5
Teams is also limited to version 1.5

In addition, Copilot Studio only renders version-1.6 cards in the test chat, not on the canvas.

For more information about the Adaptive Cards schema, see Schema Explorer.

Copilot Studio includes a built-in Adaptive card designer, which offers the most useful features form the Adaptive Cards Designer.

Alternatively, you can:

Use a JSON representation for the card you want to show to the user.
Use a Power Fx formula to include dynamic information on the card.

You can also control the behavior of the card, such as what to do when the user enters an invalid response or if the node can be interrupted.

The Adaptive Card node is meant 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.

Tip

Rename nodes to make them easier to identify. Select the node's name field to update the name directly, or select the More icon (…) of the node and select Rename from the menu. You can also rename nodes in the code editor.

It's not possible to rename Trigger nodes and Go to step nodes.

Node names can be up to 500 characters in length.

Add an Adaptive Card node

Select the Add node icon below the node under which you want to add an Adaptive Card node, then select Ask with Adaptive Card.
Select the More icon (…) of the node, and then select Properties.
In the Adaptive Card node properties panel, select Edit adaptive card. The Adaptive card designer panel opens.
Add the desired elements for your card and configure their properties. Alternatively, in the Card payload editor pane, replace the default payload with the JSON literal for your card.

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 agent. If it doesn't and is only intended to show information, you should add your Adaptive Card to a Message node.
When you're done with the initial design, select Save and close the designer panel. A preview of your card appears on the node. Copilot Studio automatically creates output variables based on the inputs specified in the code.

Tip

If the output variables generated for your card are incorrect, you can manually update the list of variables and their types by selecting Edit Schema in the Adaptive Card node properties panel.

Your interactive Adaptive Card is now ready. When a user of your agent selects a submit button on a card, the output variables are populated with the information the user provided in their interaction with the card.

Other properties

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

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

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

How many reprompts: The number of times your agent 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 selected (default), an incoming message from a user when the agent is awaiting a card submission triggers an interruption and switches 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 a Power Fx formula to include dynamic information on your card by referencing variables from your topic or agent.

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

In the Adaptive Card Node properties panel, switch to Formula, Selecting Formula automatically converts the JSON representation of your card into a Power Fx formula.

Screenshot of the option to switch to a Power Fx formula instead of JSON on the Adaptive Card node properties panel.

For example, start with the following JSON literal for a card:

{
  "$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"
    }
  ]
}

Here's the resulting Power Fx formula, using two variables Topic.Title and Topic.Subtitle instead of the hard-coded text from the JSON literal. (This example assumes the variables are defined in your topic.)

{
  '$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"
    }
  ]
}

Important

Once you begin editing in the formula panel, you can't go back to the original JSON code. To allow iterative design and changes, we recommend saving a copy of the original JSON in your own notes, or as a comment in the node. This precaution allows you to revert changes, if needed.

Share via

Ask with Adaptive Cards

Add an Adaptive Card node

Other properties

Use Power Fx to make your card dynamic

Feedback

Additional resources