Using Adaptive Card Dialog Boxes in Microsoft 365 Copilot Agents

There is a moment in almost every Copilot agent project where chat stops being the right interface. The agent needs five specific pieces of information to do the thing, and trying to collect them through conversation turns into a painful interrogation. "What's the project name?" "When's it due?" "Who's the owner?" One question at a time, the user answering in fragments, the agent occasionally misreading a date. Everyone has used a chatbot that does this and everyone has hated it.

Adaptive Card dialog boxes are Microsoft's answer to that moment. Instead of dragging structured input out of a user one message at a time, the agent pops open a small modal form, the user fills it in properly, hits submit, and the agent gets clean, validated data back in one shot. It is a small feature that makes the difference between an agent that feels professional and one that feels like a phone tree.

Microsoft's documentation on dialog boxes covers the manifest and the mechanics. This post is about the judgement: when a dialog earns its place, when it gets in the way, and what we have learned building these into agents for Australian businesses.

What a dialog box actually is

If you have built anything on the Microsoft Teams platform you might know these by their older name, task modules. A dialog box is a modal window that opens on top of the conversation. Inside it you render an Adaptive Card, which is Microsoft's JSON-based UI format, and that card can hold text fields, dropdowns, date pickers, toggles, whatever structured input you need. The user completes the form, submits, and the card's data comes back to your agent as a single tidy payload.

The key thing to understand is that a dialog is a deliberate break from the conversational flow. Chat is loose and free-form by design. A dialog is the opposite: it is bounded, structured, and it will not let the user wander off topic. That constraint is exactly the point. When you genuinely need a specific set of fields, you do not want the freedom of natural language, you want a form. The dialog gives you a form without leaving the Copilot surface.

Adaptive Cards render across the Microsoft 365 surfaces, so a dialog you define once shows up consistently whether the user is in Teams, Outlook or the Microsoft 365 Copilot app. That cross-surface consistency is genuinely useful and it is one of the better arguments for building on this platform rather than rolling your own web form and bouncing users out to it.

When a dialog earns its place

I am fairly opinionated about this because I have seen dialogs used well and used badly, and the difference is stark.

A dialog is the right call when the agent needs several related pieces of structured information at once, and getting them wrong has consequences. Logging a support ticket with a category, priority, and description. Booking a meeting room with a date, time, duration and attendee list. Submitting an expense with an amount, category, date and receipt. In all of these, the fields are known in advance, they benefit from validation, and collecting them through chat would be slow and error-prone. Pop a form, get it right, done.

Dialogs also shine when input needs constraining. A dropdown of the five valid ticket categories will always beat asking the user to type the category and then trying to match their free text against your list. A date picker returns an unambiguous date rather than "next Tuesday", which the agent then has to interpret and might get wrong. Every field you can turn from free text into a constrained control is a field that stops generating edge cases.

And they help when the action is consequential enough to deserve a deliberate confirmation. If the agent is about to raise a purchase order or send something to a customer, making the user review a filled-in form and click submit is a reasonable, honest bit of friction. It slows them down at exactly the moment they should slow down.

When a dialog gets in the way

Now the other side, because reaching for a dialog too eagerly is its own mistake.

If you only need one piece of information, do not open a dialog for it. Just ask in the chat. Popping a modal to collect a single text field is heavier than the conversation it interrupts, and it feels bureaucratic. The whole appeal of a conversational agent is that simple things stay simple. A dialog for one field throws that away.

Dialogs also break flow, and flow has value. Part of why people like Copilot agents is the frictionless back-and-forth. Every modal you open is a small interruption, a context switch, a thing to close. Use too many and the experience stops feeling like a conversation and starts feeling like clicking through a wizard, which is precisely the clunky enterprise software people hoped the agent would spare them from. I have seen agents where every interaction detoured through a form, and they were exhausting to use.

There is a subtler trap too. Because a dialog is structured, it is tempting to cram it full of fields "while we have the user's attention". Resist that. A dialog with fifteen fields is a form, and if you wanted a fifteen-field form you probably did not need an agent at all. Keep dialogs tight. Ask for what the immediate action needs and nothing more. If you find your dialog growing arms and legs, that is usually a sign the workflow behind it is too big for a single step.

How we build them in practice

When we design an agent that uses dialogs, the collaboration between the conversational layer and the structured layer is where the craft is. The agent should carry as much of the interaction as it sensibly can in natural language, and only drop into a dialog at the precise point where structure genuinely helps. The user says what they want in their own words, the agent understands the intent, and then the dialog appears pre-populated with everything the agent could already infer, leaving the human to confirm or correct rather than fill in from scratch.

That pre-population detail matters more than it sounds. A dialog that opens blank makes the user do all the work. A dialog that opens with the fields the agent already worked out from the conversation, and only asks the human to check them and add the one or two things it could not know, feels genuinely intelligent. It is the difference between the agent handing you a blank form and the agent handing you a form it already mostly filled in. Getting that right is a lot of what separates an agent that feels helpful from one that feels like a fancy front end on a database insert, and it is the kind of detail our Copilot Studio consultants sweat over when building these.

On the technical side, the important habits are validation in the card itself so bad input never reaches your backend, clear submit and cancel paths so the user is never trapped in a modal, and a graceful handling of the submitted payload so a half-completed dialog or a cancelled one does not leave the agent confused about what happens next. None of that is hard, but skipping it produces exactly the flaky agent behaviour that erodes trust the first time it happens in front of a real user.

The honest assessment

Adaptive Cards as a technology are solid but they are not the most pleasant thing to author by hand. The JSON gets verbose, the tooling is decent but not delightful, and complex layouts take more fiddling than you would like. For simple dialogs this is a non-issue. For elaborate ones you will spend time in the designer getting spacing and alignment to behave. That is the reality and it is worth knowing before you commit to a heavily form-driven design.

The cross-surface consistency is genuinely good, and being able to define a rich input experience that works inside Copilot without shipping people off to a separate web app is a real advantage of building on this platform. When the alternative is a clumsy chat interrogation or a jarring hand-off to an external form, a well-judged dialog is clearly the better experience.

My overall take: dialog boxes are a sharp tool that most agent projects should use, sparingly. The agents that get this right use conversation for the flexible parts and dialogs only for the handful of moments that genuinely need structure. The agents that get it wrong either avoid dialogs and subject users to endless one-question-at-a-time chat, or overuse them and turn the whole thing into a click-through wizard. The good version sits in the middle, and finding that middle is a design decision, not a technical one.

Where to start

If you are building a Copilot agent and any part of it collects structured input, sketch the interaction before you write a line of manifest. Mark the points where the agent needs several specific fields with consequences attached. Those are your dialog candidates. Everything else should stay in conversation. That single bit of upfront design tends to prevent both failure modes at once.

If you would like help building Copilot agents that use the extensibility platform well, dialogs and all, that is core work for us. Take a look at what our AI agent builders do, or the wider Microsoft AI consulting we offer, and if you have got an agent idea you want to get right, get in touch.