Repository navigation
Migrating Adaptive/Waterfall Dialogs from Bot Framework SDK to Agents SDK #344
Description
Hi,
We are currently migrating our production bot from the Bot Framework SDK (botbuilder-python) to the
Microsoft 365 Agents SDK (microsoft-agents-* packages). Our existing bot heavily relies on
dialog-based conversation flows, specifically:
- WaterfallDialogs for multi-step sequential workflows .
- DialogState management for tracking conversation position across turns
These patterns are central to how we orchestrate multi-turn conversations, and we don't see an
equivalent to botbuilder-dialogs in the Agents SDK package surface.
Our questions:
- Is there a planned replacement or recommended alternative for botbuilder-dialogs in the Agents
SDK? - What is the suggested approach for implementing multi-step, stateful conversation flows?
- Are there any migration guides, samples, or reference implementations for moving dialog-heavy
bots to the Agents SDK?
Thank you!
Activity
tracyboehrer commentedon Mar 25, 2026
Shivam Bhardwaj (@Shivam-a0621) Let's be clear on the type of dialogs. "Adaptive" is quite different from "Waterfall". The description indicates the functionality in Dialogs. Adaptive Dialogs will not be supported in Agents SDK. But there are plans to bring the functionality in botbuilder-dialogs forward.
MattB (@MattB-msft) Do we have a timeline for when this would happen?
MattB-msft commentedon Mar 27, 2026
Shivam Bhardwaj (@Shivam-a0621)
In general we are trying to guide folks away from the botframework dialogs systems as there are many better options implemented by orchestrators for deterministic flows,
That said Dialogs are a compatibility commitment for us and we will get this port prioritized for migration, its been low priority item due to the very low adoption of BotFramework Python.
We will get this picked up in the next month or so once we complete OTEL work that is in flight.
Im going to move this feature over to our Python repo for tracking,
Shivam-a0621 commentedon Mar 29, 2026
Thanks MattB (@MattB-msft) tracyboehrer (@tracyboehrer) for clarity and making this a high priority feature.
rodrigobr-msft commentedon Apr 22, 2026
Once the PR is merged, you will be able to find the source code for a few ported BotFramework dialog samples in
test_samples/compat/dialogsShivam-a0621 commentedon Aug 17, 2026
Hi MattB (@MattB-msft)
Following up on this after some time, when you mentioned “better options implemented by orchestrators for deterministic flows,” could you guide me what orchestration patterns you would recommend today?
We are revisiting our migration from Bot Framework and it would be really helpful to understand what the recommended approach is now for implementing deterministic, multi-step conversational flows.
rodrigobr-msft commentedon Sep 2, 2026
Hi Shivam. In particular, we recommend using
agent-frameworkand it's workflows system. Here is a page that illustrates some of that in action: https://learn.microsoft.com/en-us/agent-framework/workflows/human-in-the-loop?pivots=programming-language-pythonShivam-a0621 commentedon Sep 3, 2026
Got it
Thanks, Rodrigo Brandão (@rodrigobr-msft)