Microsoft Agent Framework Declarative Workflows 1.0: Stop Burying Orchestration in Your App Code

The most critical logic in most multi-agent systems is also the least visible. Sequencing, branching, handoffs between agents - the decisions that determine what your system actually does - sit wired into application code, scattered across handlers and conditionals, invisible to anyone who is not reading the source.

Microsoft Agent Framework declarative workflows exist because that arrangement fails at scale. You cannot review orchestration in a PR as a distinct artifact. You cannot diff version 3 of your handoff logic against version 2. You cannot change an approval step without a build and a redeploy. That is technical debt by design, and most teams only notice it when the second or third agent arrives and the “orchestration” turns out to be forty if-statements nobody owns.

Here is the position I will defend for the rest of this piece: if changing a handoff requires a compile, your orchestration is in the wrong place.

What Declarative Workflows 1.0 actually ships

Microsoft announced Declarative Workflows 1.0 for Agent Framework with a framing that matches the problem exactly. In the announcement’s own words, most multi-agent apps wire every flow in application code - “the sequence of steps, branching, and handoffs between agents all live inside the program, making the orchestration harder to review, version, and change.” The release moves that into YAML, where, per the post, “you define how agents coordinate, how state changes, where execution branches, and when people step” in.

Read the title of the release again: it moves orchestration out of code. Agent Framework shipped as a code-first SDK, so a programmatic workflow surface already existed. What 1.0 adds is the declarative format on top - orchestration as a versioned artifact that lives in your repo next to your Bicep and your pipeline YAML, not as compiled logic inside the app.

Here is the shape of it. This snippet is illustrative, not copy-paste. I am showing the shape of the idea, not the schema - verify field names against the microsoft/agent-framework repo and the Agent Framework docs on Microsoft Learn before using anything like it, because the declarative surface is new and still moving:

# Illustrative only. Not the official schema.
# Verify against learn.microsoft.com/agent-framework and the GitHub repo.
workflow:
  id: mrd_invoice_triage
  agents:
    - id: mrd_classifier
      instructions: Classify the invoice and extract the total.
    - id: mrd_approver_notify
      instructions: Draft the approval request for finance.
  flow:
    - from: mrd_classifier
      to: human_checkpoint
      condition: output.total > 10000
    - from: mrd_classifier
      to: mrd_approver_notify
      condition: output.total <= 10000
  checkpoints:
    - id: human_checkpoint
      type: human_approval

My editorial pick for the capability that matters most is not branching. It is the “when people step in” part - human checkpoints as declarative config. “The approval gate is a reviewable line in a YAML file” is a sentence a compliance reviewer understands immediately, and that is what gets this past an architecture review board.

We have seen this movie before, and it ends well

Jenkins jobs configured by clicking through a UI became pipeline YAML in the repo. Hand-run deployment scripts became Terraform and Bicep. Imperative kubectl incantations became Kubernetes manifests under GitOps. Every one of those shifts took logic that was invisible and operational and made it reviewable, diffable, and governable. Every one of them also let non-developers - security, compliance, platform teams - participate in review without reading application code.

Agent orchestration is the next domain to make this move, and Microsoft shipping a 1.0 declarative format signals they expect enterprise governance requirements to land here. They are right. I have argued before that risk-tiered agent governance only works when there is an artifact to govern. YAML workflows are that artifact.

The practitioner caveat, because every one of those historical shifts had one: each transition created a new skill gap and a new tooling vacuum. Pipeline YAML needed linters. Terraform needed plan review and drift detection. Agent orchestration YAML will need validators, schema checks, and diff tooling that understands workflow semantics, and almost none of that exists yet. My bet, stated as a bet: teams adopting early will write some of that tooling themselves before the ecosystem fills it in.

Bet on the declarative side of this transition early anyway. The governance tooling always follows, and it follows the format that won.

The Azure angle: positioning against code-first frameworks

LangGraph and CrewAI are not doing it wrong. LangGraph is code-first by design: orchestration is a graph in Python or TypeScript, and for highly dynamic, data-dependent routing that is genuinely the better model. Its documented interrupt and checkpointer mechanisms give it a mature, well-specified human-in-the-loop story - pause, inspect state, resume from a saved thread. CrewAI sits in between, with YAML configuration for agents and tasks but process logic in Python.

What Agent Framework has that neither can match is first-party Microsoft positioning. And here is my read of the strategy - labeled as my read, because Microsoft has not spelled it out this way: declarative artifacts are what a control plane can consume. A portal can render a YAML workflow. A policy engine can evaluate it. An audit pipeline can diff it. Azure AI Foundry becomes far more useful as an enterprise control plane for agent fleets when the orchestration it governs is data, not code. If you are already weighing Foundry hosted versus in-process agents, declarative workflows tilt the hosted story, because hosted governance wants inspectable artifacts. Treat the depth of that Foundry integration as direction, not shipped fact, until you verify it in the Foundry docs.

The one-liner: pick LangGraph when routing decisions depend heavily on runtime data, pick CrewAI when your team wants lightweight role-based crews in Python, and pick Agent Framework when you are on Azure and someone will eventually ask who approved this workflow.

The honest caveat: YAML is not a silver bullet

Anyone who has debugged a 900-line Azure Pipeline knows exactly where this goes wrong. Complex conditional logic in a declarative format becomes its own nightmare: expressions inside strings, no debugger, no stack trace, and a feedback loop measured in minutes. That is shared industry scar tissue, not a measured claim, and it applies here with full force.

The docs will show you clean 40-line examples. Production workflows do not stay at 40 lines. They grow retry policies, error branches, compensation logic, and the one weird special case nobody designed for. Here is where the line actually sits: linear and lightly-branched flows belong in YAML; dynamic routing driven by runtime data belongs in code. “Configuration, not code” is the right default for static orchestration and the wrong religion for everything else.

On the escape hatch: because Agent Framework was a code-first SDK before this release, a programmatic workflow API sits underneath the YAML. What the public documentation does not yet make crisp, as of this writing, is the seam itself - how cleanly you drop from a declarative workflow into custom code for one node and back. That ambiguity is useful information in its own right. Budget a spike against the current repo to test the boundary before you commit a compliance-critical workflow to it, and treat any effort estimate you produce as illustrative until your own spike says otherwise.

Adopt now or wait: a decision framework

Run your situation through five questions.

Four or five yeses: migrate now, especially for new projects and compliance-heavy teams with static-ish flows. Mostly nos: wait, particularly if heavy dynamic routing or an existing stable code-first investment is doing the work, or if your team has no YAML governance muscle yet. The AgentOps CI/CD reference architecture is where that muscle gets built, and declarative workflows slot into it the way pipeline YAML slotted into CI.

My default recommendation is not hedged: new Azure-based agent projects should start declarative-first with Microsoft Agent Framework declarative workflows and escape to code only when the workflow genuinely demands it. Treat agent orchestration the way you treat infrastructure - a declarative, versioned, reviewable artifact from day one. The format is at 1.0. The direction is correct. The teams that adopt the pattern now will have the governance story enterprises demand while everyone else is still explaining why their approval logic lives in a switch statement.