8.2 Configure Adaptive Cards

8.2 Configure Adaptive Cards

Quick Answer: Use Ask with Adaptive Card for interactive forms with Action.Submit, author JSON (or Power Fx Formula cards) with input ids, let Copilot Studio map outputs to variables, and test on every target channel because schema and action support differ.

AB-620 expects you to configure adaptive cards as a first-class topic skill—not as decorative UI fluff. Cards collect structured data, reduce multi-turn chatter, and pair with flows, tools, and generative answers.

Two card surfaces in Copilot Studio

Microsoft’s rule of thumb: if the card is only meant to show information, put it on a Message node. The Ask with Adaptive Card node is for interactive cards that include at least one submit path so the conversation can continue with stored answers.

Schema versions and channel support

Adaptive Cards are platform-agnostic JSON, but hosts cap versions and actions:

Design for the strictest production channel, not only the Studio canvas. A card that works in test but fails Teams validation is a failed deployment.

Core JSON shape (conceptual):

{
  "$schema": "http://adaptivecards.microsoft.com/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [ /* TextBlocks, Inputs, Containers, ColumnSets */ ],
  "actions": [ { "type": "Action.Submit", "title": "Submit", "data": { } } ]
}

Inputs, validation, and output variables

Common input element types you will see in exam scenarios:

Each input needs a stable id. On successful submit, Copilot Studio creates output variables named from those ids (and types inferred from the card). If inference is wrong, open node Properties → Edit Schema and correct variable names/types manually.

Submit actions

Interactive cards require a submit action—commonly Action.Submit with a title users understand (“Submit,” “Confirm booking”). Best practices for multi-card conversations:

• Put a unique identifier in data (for example actionSubmitId) so the agent or custom client can tell which card was submitted when users click an older card still visible in history.
• Isolate handlers when consecutive cards appear; stale clicks on prior cards are a known UX risk.
• On custom web chat hosts, disable buttons after first click to prevent double submit.

Invalid responses and interruptions

While the agent waits for a card submission, free text is treated as invalid unless it interrupts to another topic.

Use interruptions carefully: a user typing “cancel” should reach Reset/End paths rather than three useless card retries.

JSON vs Power Fx Formula cards

Authoring options:

1. Built-in Adaptive Card designer (subset of full Adaptive Cards Designer features)
2. Card payload editor with raw JSON
3. Formula mode — converts JSON into a Power Fx object formula so you can bind Topic.*, Global.*, and (via prepared variables) system context

Binding dynamic values

Hard-coded titles are fine for static forms. Real agents need personalization:

• Switch Properties to Formula
• Replace static strings with references such as Topic.Title, Global.CustomerName, or concatenated text ("Hello " & Topic.FirstName)
• Pre-compute complex strings with Set a variable value if you need values that are awkward inside the card formula

Important: After deep formula editing, you may not freely flip back to the original JSON. Keep a JSON backup in comments or source control for iterative design.

Community and Q&A guidance also notes that not every system variable interpolates magically inside static JSON—copy needed values into topic/global variables first, then reference those in Formula mode.

When cards beat plain text

Cards also pair well with agent flows: collect fields → validate with Condition nodes → call flow → show confirmation card. That deterministic spine is classic AB-620 multi-step design.

Adding an Ask with Adaptive Card node

1. Add node → Ask with Adaptive Card.
2. … → Properties → Edit adaptive card.
3. Design elements or paste JSON; ensure ≥1 submit action.
4. Save; preview appears on the node; outputs auto-create.
5. Map outputs into later Condition, Set variable, Action (flow/tool), or Message nodes.
6. Configure reprompt/interrupt properties for production UX.
7. Test on every target channel (Teams, web, voice UI constraints if applicable).

Rename the node meaningfully (names can be long) so large topics stay readable.

Scenario walkthroughs

Scenario A — Device request form

Contoso IT topic collects device type, justification, and cost center on one card. Input.ChoiceSet for device, required Input.Text for justification, regex on cost center. Submit fills topic variables → Condition validates → agent flow creates ticket → Message Adaptive Card shows ticket number (display-only).

Scenario B — Generative answer + confirmation card

Generative answers node stores policy summary in Global.PolicyAnswer with Send a message cleared. Message node Formula card shows the summary text plus Action.Submit choices “That answered me” / “Talk to HR.” Outputs drive escalation branching. Teams testing verifies citation fields if compliance requires source links on the card.

Scenario C — Consecutive cards

Survey topic sends Card 1 then Card 2. Each Action.Submit includes distinct actionSubmitId. Without unique data, a late click on Card 1 can confuse state—exam-ready designers plan identifiers and client disablement.

Scenario D — Channel downgrade

Marketing wants schema 1.6 features. Contact center uses Omnichannel 1.5. Maker authors 1.5-safe cards, keeps decorative 1.6-only features out of production payload, and documents the host matrix.

Design quality checklist

1. Prefer 1.5 (or host-documented max) for multi-channel agents.
2. Every interactive card has a clear Submit (or equivalent) action.
3. Input ids are stable; schema edited if auto variables mis-type.
4. Required fields and regex match business rules—not only “nice to have.”
5. Formula mode used for personalization; secrets never embedded in card JSON.
6. Reprompt counts and interruption policy match escalation design.
7. Stale multi-card submits handled via unique data payloads.
8. Plain-text fallback exists when a channel strips cards.
9. Accessibility: labels on inputs, short titles, wrap text for mobile.
10. After flow/tool success, confirmation card or message uses the same variable vocabulary.

Exam traps

• Putting a non-interactive summary on Ask with Adaptive Card without submit (use Message instead).
• Assuming Studio test success equals Teams success.
• Forgetting that free text during card wait is invalid unless interruption fires.
• Hard-coding user-specific values instead of Power Fx bindings.
• Using cards for one binary question when a Question node is simpler—and vice versa for five-field forms.

Adaptive Cards turn Copilot Studio topics into structured micro-apps inside chat. On AB-620, show you can choose interactive vs display cards, respect channel schema, bind variables with Power Fx, and wire submit outputs into the rest of the agent.