From Code Orchestration to Declarative Workflows
Microsoft announced Agent Framework's Declarative Workflows reaching 1.0 on July 23, 2026. The Python package agent-framework-declarative hit 1.0.0, and the .NET side had already joined as a stable release. Multi-agent orchestration that used to get wired inside application code can now be declared in YAML — coordination, state changes, branching, and human touchpoints — with the framework converting that into an executable workflow graph.
The core idea is describing what a workflow should do, not how to implement it. Adding an approval step or changing a handoff condition becomes a YAML diff instead of a code change, so product owners and architects can review orchestration behavior without reading framework code.
Action Kinds Are the Orchestration Grammar
Declarative workflows cover a wide range of action kinds: variable management (SetVariable, AppendValue, ResetVariable), control flow (ConditionGroup, Foreach, If/Then/Else, EndWorkflow), agent and tool invocation (function tools, MCP, HTTP), human-in-the-loop (pause for approval, then resume), checkpoint and resume, and conversation control (SendActivity).
It doesn't push everything into YAML, either. Declarative definitions load as standard Workflow instances, so you can drop to lower-level APIs and compose code for whatever segment needs it. Describing coordination in config and keeping code only where it's needed is an operating principle that isn't tied to any one vendor.
Build Roadmap and Pitfalls: A Declarative Workflow Migration Checklist
Fix the target numbers in writing before you migrate. A reasonable starting bar: YAML diff review lead time under 4 hours, a 100% pass rate on 20 regression scenarios replayed before deploy, condition-branch coverage above 90%, and a 15-minute human-approval SLA with automatic escalation past that.
Failure patterns narrow to four. First, a Foreach exit condition that can never logically become true, so the loop never closes — YAML syntax checks pass, but the loop doesn't.
Second, resuming from an old checkpoint after the checkpoint schema changed, leaving variable state misaligned. Third, no timeout on a human-approval step, so the workflow waits indefinitely when the approver doesn't respond.
Fourth, an MCP or HTTP tool call fails with no branch to catch it, and the whole run dies. Recovery has to be wired per action kind: cap iteration count and set a timeout on loop actions; add a version field to checkpoints so a schema mismatch rejects the resume and restarts clean; give approval waits a safe default path or auto-escalation on timeout; and route tool-call failures to an exception branch once exponential-backoff retries are exhausted.
Before deploying, standardize on selecting a workflow version and replaying conversations in a playground, checking expected against actual responses. Logs need step ID, action kind, variable snapshot, checkpoint version, approver, and elapsed time as required fields — and mask any PII that might land in a variable snapshot before it's stored.
Aggregate failure logs by action kind every week to see which type — branching, tool calls, or approval waits — is where failures cluster, and keep the YAML change history separate from the application code change history so orchestration issues and logic bugs stay distinguishable.
A Checklist You Can Use Today
Once multi-agent orchestration moves to YAML, who reviews it and how it recovers both change. Start from a 4-hour diff lead time, a 100% scenario-replay pass rate, 90% branch coverage, and a 15-minute approval SLA; wire timeouts and backoff into the four points — loops, checkpoints, approvals, tool calls — then track weekly, by action kind, where it's breaking. That operating bar survives a framework swap.