When NOT to Use Adaptive Cards in Microsoft Copilot Studio
Letting the LLM Interpret REST API Responses Instead of Building the UI Yourself
Introduction
Adaptive Cards are one of the most useful presentation mechanisms available when building Microsoft Copilot Studio agents.
They allow developers to transform data into structured visual interfaces containing elements such as:
- Text
- Tables
- Fact sets
- Images
- Buttons
- Links
- Input controls
- Selection controls
- Actions
However, the fact that Adaptive Cards are available does not mean that every structured response returned by an API should become an Adaptive Card.
This is especially important when building agents that consume REST APIs.
Consider a football Agent connected to an external API.
A user asks:
“Who does Arsenal play next?”
The architecture could be implemented as:
User
↓
Agent
↓
REST API
↓
JSON
↓
Adaptive Card
↓
User
But another architecture is possible:
User
↓
Agent
↓
REST API
↓
JSON
↓
LLM
↓
Natural-language answer
↓
User
The second architecture is often simpler and, more importantly, can make better use of the fundamental capability of an Agent:
reasoning over structured information and generating an appropriate conversational response.
The architectural question therefore should not be:
“Can I display this with an Adaptive Card?”
It should be:
“Does this interaction actually require a predefined UI?”
1. Adaptive Cards Are a Presentation Layer
The first important distinction is understanding what an Adaptive Card actually represents.
Microsoft describes Adaptive Cards as platform-agnostic UI snippets represented in JSON that are rendered by a host application.
Conceptually:
Data
↓
Adaptive Card JSON
↓
Host
↓
Rendered UI
The host might be:
- Microsoft Teams
- Copilot Chat
- Web Chat
- Outlook
- Another supported client
Therefore, Adaptive Cards primarily solve a presentation and interaction problem.
They answer questions such as:
How should this information appear?
or:
How should the user interact with this information?
They don’t inherently improve the underlying data.
They don’t make the API more accurate.
They don’t automatically improve reasoning.
They don’t replace orchestration.
They provide a controlled presentation contract.
2. The REST API Already Returns Structured Data
Suppose our football API returns something similar to:
{
“homeTeam”: “Arsenal”,
“awayTeam”: “Chelsea”,
“competition”: “Premier League”,
“date”: “2026-09-22”,
“time”: “20:00”,
“venue”: “Emirates Stadium”
}
There are two fundamentally different ways to use this information.
Option A — Developer-controlled rendering
REST API
↓
JSON
↓
Mapping logic
↓
Adaptive Card JSON
↓
Rendered Card
The developer decides exactly how the information appears.
Option B — Model-controlled synthesis
REST API
↓
JSON
↓
Agent context
↓
LLM
↓
Generated response
The model interprets the returned structure and determines how to communicate the relevant information.
For example:
“Arsenal’s next Premier League match is against Chelsea on September 22 at 20:00 at Emirates Stadium.”
The API provided the facts.
The LLM provided the language.
This distinction is fundamental.
3. The Agent Does Not Necessarily Need an Adaptive Card
Modern Copilot Studio architecture increasingly relies on Generative Orchestration.
The Agent can interpret the user’s request, determine which Tool should be called, provide its parameters, receive the Tool output, and compose the final response.
Conceptually:
User Prompt
↓
Generative Orchestration
↓
Tool Selection
↓
REST API Tool
↓
Structured Result
↓
LLM
↓
Generated Answer
Microsoft describes generative orchestration as an LLM-driven planning layer capable of interpreting intent, selecting tools and knowledge, executing plans, and composing responses.
This means that manually creating a presentation layer for every possible API response can sometimes duplicate work that the Agent is already capable of doing.
4. Example: Football Agent
Consider our football Agent.
The user asks:
“Show me Arsenal’s next match.”
The REST API might return:
{
“competition”: “Premier League”,
“homeTeam”: “Arsenal”,
“awayTeam”: “Chelsea”,
“utcDate”: “2026-09-22T19:00:00Z”,
“status”: “SCHEDULED”
}
We could create an Adaptive Card:
Premier League
Arsenal vs Chelsea
22 September 2026
19:00 UTC
Status: Scheduled
That works perfectly.
But ask an architectural question:
What did the Adaptive Card actually add?
If the user simply wanted to know the next match, the Agent could have interpreted the JSON and answered naturally.
“Arsenal’s next scheduled Premier League match is against Chelsea on September 22 at 19:00 UTC.”
The card might add visual polish.
But it also adds:
- Card schema
- JSON authoring
- Data mapping
- Testing
- Channel compatibility considerations
- Maintenance
- Localization considerations
- Additional presentation logic
For a simple conversational answer, this can be unnecessary complexity.
5. Adaptive Cards Introduce a Presentation Contract
An Adaptive Card essentially says:
“I know beforehand how this information should be presented.”
That is useful when presentation matters.
But it also constrains the response.
Imagine that the API returns ten fields:
{
“team”: “…”,
“opponent”: “…”,
“competition”: “…”,
“date”: “…”,
“venue”: “…”,
“status”: “…”,
“matchday”: 5,
“season”: “…”,
“stage”: “…”,
“referee”: “…”
}
A developer-created card must decide which fields appear.
Maybe:
Team
Opponent
Date
Venue
But then the user asks:
“Which matchday is that?”
The data might already exist in the Tool result.
A generative Agent can potentially reason over the complete structured response and select the relevant property.
This illustrates an important difference:
Adaptive Card = predefined presentation
LLM synthesis = contextual presentation
6. The User’s Question Should Influence the Answer
Suppose the same REST API returns:
{
“homeTeam”: “Arsenal”,
“awayTeam”: “Chelsea”,
“date”: “2026-09-22”,
“venue”: “Emirates Stadium”,
“status”: “SCHEDULED”
}
Different users might ask:
“When is Arsenal playing?”
“Who is Arsenal playing?”
“Where is Arsenal playing?”
“Is Arsenal playing at home?”
“What is Arsenal’s next fixture?”
The underlying API response can be identical.
But the relevant answer changes.
With a fixed Adaptive Card, we often present the same fields every time.
With LLM synthesis:
REST JSON
User Intent
Conversation Context
↓
LLM
↓
Contextually appropriate answer
This is one of the strongest reasons not to automatically transform every API response into an Adaptive Card.
7. Let the API Provide Facts and the LLM Provide Language
A very useful Agent design principle is:
API = source of facts
LLM = interpretation and communication
Consider:
REST API
↓
{
“position”: 1,
“team”: “Arsenal”,
“playedGames”: 10,
“won”: 8,
“draw”: 1,
“lost”: 1,
“points”: 25
}
The API should be trusted for:
- Position
- Matches played
- Wins
- Draws
- Losses
- Points
The LLM should not invent these values.
But the LLM can transform them into:
“Arsenal is currently first with 25 points from 10 matches, having won eight, drawn one, and lost one.”
This is exactly the kind of transformation LLMs are good at.
8. Structured Data Does Not Automatically Require Structured UI
This is an important architectural misconception:
Structured input ≠ structured visual output
An API returning JSON does not mean the user needs to see JSON.
It also does not mean the user needs an Adaptive Card.
JSON can simply be the machine-readable contract between:
API
and
Agent.
Conceptually:
External System
↓
JSON
↓
Agent
↓
Natural Language
The JSON exists because machines need predictable structure.
The user does not necessarily need that structure exposed visually.
9. When Natural Language Is Better
Natural-language synthesis is especially attractive when the user’s request is:
- Exploratory
- Conversational
- Variable
- Context-dependent
- Analytical
- Comparative
- Summarization-oriented
Imagine the API returns five matches.
The user asks:
“How has Arsenal been performing recently?”
A rigid card might display:
Match 1
Match 2
Match 3
Match 4
Match 5
But the Agent could potentially reason over those results and produce:
“Arsenal has won four of its last five matches, scoring 11 goals and conceding four. The only defeat came against Liverpool.”
Assuming every statement is supported by the returned data, this is much closer to the user’s actual intent.
The user didn’t ask:
“Display five database records.”
The user asked for an interpretation.
10. This Is Where the LLM Adds Value
Without the LLM:
API
↓
Data
↓
UI
With an Agent:
API
↓
Data
↓
Reasoning / Synthesis
↓
Answer
This difference is important.
If we always force API responses directly into rigid UI components, we can unintentionally reduce the Agent to:
a conversational API client with pretty cards.
Sometimes that is exactly what we need.
But often it isn’t.
The purpose of the Agent can instead be:
retrieve reliable data and intelligently communicate what matters to the user.
11. When Adaptive Cards Are the Better Choice
This doesn’t mean Adaptive Cards should be avoided.
They become particularly valuable when the structure itself has UX value.
Examples include:
Multiple comparable records
League standings:
| Position | Team | Played | Points |
|---|
A structured visual representation can be easier to scan than a long paragraph.
User interaction
Examples:
- Approve
- Reject
- Select
- Confirm
- Cancel
- Open
- Submit
Adaptive Cards can collect structured user input and expose actions directly in the conversation.
Business transactions
Imagine:
Purchase Request #482
Amount: $4,500
Department: IT
Requester: John Smith
[Approve]
[Reject]
Here, deterministic presentation is valuable.
Fixed enterprise information
Examples include:
- Support tickets
- Expense requests
- Approval records
- Order summaries
- Incident records
- Service requests
- Employee onboarding tasks
The UI itself contributes to usability.
12. When Adaptive Cards Are Probably Unnecessary
Adaptive Cards may add little value when:
The answer is short
User:
“When does Arsenal play next?”
A sentence is enough.
The user asks an analytical question
“Who has been performing better over the last five matches?”
The Agent should reason over the returned data.
The result shape varies
Different queries may return very different data structures.
Creating cards for every permutation increases development complexity.
The conversation is exploratory
“What can you tell me about Arsenal’s season?”
The model should have freedom to organize the answer around the user’s intent.
No interaction is required
If there are no buttons, selections, confirmations, forms, or structured actions, a card may provide only cosmetic value.
13. A Useful Decision Rule
Before creating an Adaptive Card, ask:
Does the USER need structure, or does only the SYSTEM need structure?
If only the system needs structure:
REST API
↓
JSON
↓
LLM
↓
Natural Language
may be sufficient.
If the user needs structure:
REST API
↓
JSON
↓
Adaptive Card
↓
Structured UI
may be better.
That is a much more useful criterion than:
“API returns JSON, therefore I need an Adaptive Card.”
14. A Hybrid Architecture Is Often Better
There is also no requirement to choose only one approach.
A sophisticated Agent can use both.
For example:
User:
“Show me the Premier League standings and tell me how Arsenal is doing.”
Architecture:
REST API
↓
Standings JSON
↓
┌──────────────────────────┐
│ │
▼ ▼
Adaptive Card LLM
↓ ↓
Standings table Natural-language analysis
The Agent could respond:
“Arsenal is currently second, three points behind the leader.”
And then display the structured standings.
This creates an excellent division of responsibilities:
LLM = explanation
Adaptive Card = visualization
15. Another Hybrid Pattern: Summary + Card
Another useful pattern is:
LLM Summary
↓
Adaptive Card
For example:
“Arsenal has won four of its last five matches and has been particularly strong at home.”
Then:
Last 5 Matches
Arsenal 3–0 Team A
Team B 1–2 Arsenal
Arsenal 2–1 Team C
Team D 2–0 Arsenal
Arsenal 4–1 Team E
Here the card is not replacing reasoning.
It is supporting it.
That distinction is architecturally important.
16. Do Not Ask the LLM to Reconstruct Facts the API Already Knows
There is an important boundary.
Allowing the LLM to synthesize the response does not mean allowing it to invent missing API values.
Suppose the API returns:
{
“team”: “Arsenal”,
“points”: 25
}
The Agent should not infer:
“Arsenal is first.”
unless position can actually be established from the available data.
The desired pattern is:
API Facts
↓
LLM Interpretation
not:
Incomplete API Facts
↓
LLM Guessing
This connects directly with the grounding principles we have already studied.
Our earlier experiments demonstrated the difference between a plausible generated answer and an answer constrained by available evidence.
The same principle applies to REST API results.
The Tool result becomes evidence.
The model can transform that evidence into language, but it shouldn’t silently invent missing facts.
17. Tool Output Becomes Context for the Agent
A useful mental model is:
User Request
↓
Agent
↓
Generative Orchestration
↓
REST Tool
↓
API
↓
JSON Response
↓
Tool Output
↓
Agent Context
↓
LLM
↓
Final Response
The JSON doesn’t necessarily need to be the final answer.
It becomes input to the next reasoning/generation step.
This is one of the most important architectural ideas when working with Agent Tools.
18. Good Tool Descriptions Become Critical
Once we rely more heavily on generative orchestration, the quality of Tool definitions becomes increasingly important.
The Agent needs to understand:
- What the Tool does
- When it should be called
- What inputs it requires
- What its outputs represent
For example:
Tool:
GetTeamMatches
Description:
“Retrieves scheduled and completed matches for a football team. Use this tool when the user asks about fixtures, previous matches, upcoming matches, match dates, opponents, or results.”
Inputs:
teamId
dateFrom
dateTo
Outputs:
Structured match data.
Now the orchestrator has semantic information that helps it determine when the Tool is relevant.
This is more aligned with generative orchestration than manually routing every possible user question through handcrafted UI logic.
19. Adaptive Cards Increase Coupling
Another architectural consideration is coupling.
With:
API → Adaptive Card
the presentation layer becomes coupled to the API schema.
Suppose:
homeTeam.name
changes to:
homeTeam.shortName
or the API changes the structure of competitions, dates, or venues.
The card mapping may need to change.
Now consider:
API
↓
Tool Contract
↓
Agent
↓
Generated Response
There is still a data contract that must remain valid, but the presentation is less rigid.
The model can often select relevant fields from a richer structured result without requiring a different UI template for every conversational variation.
20. Adaptive Cards Also Have Channel Considerations
Adaptive Cards aren’t rendered in a vacuum.
They are rendered by a host.
Microsoft currently documents differences in supported Adaptive Card schema versions across Copilot Studio hosts.
For example, supported capabilities can differ among:
- Web Chat
- Live chat
- Microsoft Teams
- Copilot Studio test experiences
Therefore, choosing Adaptive Cards also introduces another architectural responsibility:
channel compatibility.
A plain generated text response generally has fewer presentation dependencies.
This doesn’t make cards bad.
It simply means they have a cost.
21. Maintenance Matters
Imagine a football Agent supporting:
- Team
- Match
- Competition
- Standings
- Scorers
- Fixtures
- Results
- Seasons
- Venues
One approach is to build:
Team Card
Match Card
Competition Card
Standings Card
Scorer Card
Fixture Card
Result Card
Season Card
Venue Card
Then perhaps additional cards for:
Match List
Team List
Competition List
Last Five Matches
Next Five Matches
Today’s Matches
Tomorrow’s Matches
At some point, we should ask:
Are we building an Agent or a card-rendering application?
If users genuinely benefit from these visual structures, the investment may be justified.
If most questions can be answered naturally from structured Tool output, we may be creating unnecessary maintenance.
22. Deterministic UI vs Generative UI
This gives us a useful architectural distinction.
Adaptive Card
Developer determines:
How should this result appear?
LLM-generated response
Agent determines:
Given the user’s request and the returned data, what is the best way to answer?
Neither is universally better.
They solve different problems.
23. Determinism Has Value
There are cases where giving the LLM freedom is undesirable.
Consider:
“Approve expense request #839.”
We may want:
Expense Request #839
Requester: John
Amount: $7,400
Cost Center: IT-203
Status: Pending
[Approve]
[Reject]
Here the structure isn’t merely visual decoration.
It is part of a controlled business interaction.
We may intentionally prefer:
API
↓
Known Data
↓
Known Card
↓
Known Actions
↓
Controlled operation
rather than allowing the LLM to dynamically decide how the approval interface should look.
24. Conversation Has Value Too
Now consider:
“Why is Arsenal doing better this month?”
A rigid UI cannot anticipate every possible interpretation.
The Agent might need to:
- Retrieve recent matches.
- Examine results.
- Compare periods.
- Identify patterns supported by the data.
- Explain those patterns conversationally.
This is exactly where generative behavior provides value.
Forcing the answer into a predetermined card could actually reduce the usefulness of the Agent.
25. The Architecture Spectrum
We can therefore think of Agent responses as a spectrum:
Fully deterministic
Adaptive Card
↓
Fixed fields
↓
Fixed actions
──────────────
Hybrid
LLM explanation
+
Adaptive Card
──────────────
Generative
REST JSON
↓
LLM
↓
Natural-language response
The correct position on this spectrum depends on the business requirement.
26. A Practical Decision Table
| Scenario | Preferred approach |
|---|---|
| Simple factual answer | LLM from REST result |
| Conversational explanation | LLM |
| Summary | LLM |
| Analysis of API results | LLM |
| Variable user questions over the same dataset | LLM |
| Exploratory conversation | LLM |
| Fixed record display | Adaptive Card |
| Multiple comparable records | Adaptive Card or hybrid |
| Approval | Adaptive Card |
| Confirmation | Adaptive Card |
| Structured user input | Adaptive Card |
| Buttons/actions | Adaptive Card |
| Transactional workflow | Adaptive Card |
| Human-readable explanation + structured records | Hybrid |
| Highly controlled UX | Adaptive Card |
| Flexible contextual UX | LLM |
27. The Architecture We Should Test
For our REST API experiments in Copilot Studio, a particularly useful learning architecture is:
User
↓
Agent
↓
Generative Orchestration
↓
REST API Tool
↓
External REST API
↓
JSON
↓
Tool Output
↓
LLM
↓
Natural-language response
Instead of immediately inserting:
JSON
↓
Adaptive Card transformation
we can first observe what the Agent does with the raw structured Tool result.
This allows us to study something more fundamental:
how the LLM reasons over Tool output.
Only after observing that behavior should we decide whether the user experience actually needs an Adaptive Card.
28. This Is Also a Better Learning Experiment
For our Copilot Studio learning path, this distinction is especially valuable.
If we immediately build an Adaptive Card, several concepts become mixed together:
REST API
Authentication
OpenAPI
Tool
Inputs
Outputs
JSON
Adaptive Card schema
Card rendering
Channel compatibility
Instead, we can isolate the Agent architecture:
REST API
↓
JSON
↓
Agent
↓
LLM
↓
Answer
Once we understand that behavior, Adaptive Cards can be introduced as a separate presentation concern.
This follows the atomic-lab approach of learning one architectural responsibility at a time.
29. Security and Trust Still Matter
Removing Adaptive Cards doesn’t remove security concerns.
We must still ask:
Who authenticated the REST API?
Which credentials are being used?
What data can the API return?
Which data becomes available to the Agent?
Which information can the user see?
Could the Tool return sensitive properties that shouldn’t be exposed?
Could the LLM summarize or reveal fields that the UI would otherwise have hidden?
This last question is particularly important.
A card might deliberately display only:
Name
Status
Date
while the raw API response contains:
Name
Status
Date
InternalID
Salary
ManagerComment
SecurityClassification
If the complete JSON is given to the LLM, those additional properties become part of the Agent’s available context.
Therefore:
“Let the LLM handle the JSON” does not mean “send every API property to the LLM.”
The Tool contract should expose only the information the Agent actually needs.
This is an application of least privilege to data context.
30. Final Architectural Principle
The most useful principle is not:
Use Adaptive Cards whenever an API returns JSON.
Instead:
Use structured API responses to give the Agent reliable facts.
Then decide independently how those facts should be presented.
The architecture becomes:
Reliable External System
↓
REST API
↓
Structured JSON
↓
Agent
↓
LLM Interpretation
↓
User-appropriate response
And only when the experience benefits from explicit structure:
Reliable External System
↓
REST API
↓
Structured JSON
↓
Adaptive Card
↓
Controlled UI
Or, frequently, the best combination:
REST API
↓
Structured Data
↓
Agent
↓
┌────────────────────┬─────────────────────┐
↓ ↓
LLM Explanation Adaptive Card
↓ ↓
Meaning Structure
Conclusion
Adaptive Cards are powerful, but they should be treated as a UX and interaction mechanism, not as the default destination for every REST API response.
When the requirement is to display predictable records, collect structured information, expose buttons, confirm actions, or create a controlled transactional experience, Adaptive Cards are an excellent choice.
When the requirement is to answer questions, summarize data, interpret results, compare information, maintain conversational context, or respond differently depending on user intent, it can be better to give the structured Tool output to the Agent and allow the LLM to compose the response.
The important architectural separation is:
REST API = facts
JSON = machine-readable contract
LLM = interpretation and communication
Adaptive Card = controlled presentation and interaction
This produces a useful decision rule:
Do not create an Adaptive Card simply because the data is structured. Create an Adaptive Card when the user experience needs to be structured.
And for an Agent:
When reliable structured data already exists, let the API own the facts and let the LLM decide how to explain those facts—unless the business requirement demands a deterministic UI.
That is one of the important differences between building a traditional application around an API and building an Agent around an API.
Official Microsoft References
Microsoft Learn — Using Adaptive Cards in Copilot Studio
https://learn.microsoft.com/en-us/microsoft-copilot-studio/adaptive-cards-overview
Microsoft Learn — Adaptive Cards for Agent Design
https://learn.microsoft.com/en-us/agents/design-guidelines/adaptive-cards-for-agent-design
Microsoft Learn — Extend your Agent with Tools from a REST API
https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-rest-api
Microsoft Learn — Apply Generative Orchestration Capabilities
https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/generative-orchestration
Microsoft Learn — Use Agent Tools to Extend, Automate, and Enhance Your Agents
https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/agent-tools
Microsoft Learn — JSON Output
https://learn.microsoft.com/en-us/microsoft-copilot-studio/process-responses-json-output
edvaldo b. guimarães filho 