Microsoft Agent Framework Declarative Workflows YAML Guide

Quick answer

Microsoft Agent Framework declarative workflows move common orchestration—state, branches, loops, agent calls, functions, MCP or HTTP tools, human review, and checkpoint-resume—into YAML. Microsoft announced declarative workflows 1.0 for Python and .NET on July 23, 2026.

Use YAML when the sequence is standard, changes frequently, or benefits from non-developer review. Use a code-first workflow when you need complex custom logic, dynamic graphs, or deep integration with application code.

The current loaders are:

workflow = WorkflowFactory().create_workflow_from_yaml_path("workflow.yaml")

var workflow = DeclarativeWorkflowBuilder.Build<string>(yaml);

The two SDKs do not currently show the same document envelope. Do not copy a Python YAML example into a .NET project and assume it is portable.

See the Microsoft Agent Framework product guide for the agents-versus-workflows boundary.

Python and .NET YAML shapes

A small Python-style document begins with a workflow name and an action list:

name: triage-support-request
description: Classify a request before an agent drafts a response.
inputs:
  request:
    type: string
actions:
  - kind: SetVariable
    id: preserve-request
    variable: originalRequest
    value: =workflow.inputs.request

Current .NET documentation instead shows a trigger-based envelope:

kind: Workflow
trigger:
  kind: OnConversationStart
  id: begin
  actions:
    - kind: SetVariable
      id: preserve-request
      variable: Local.originalRequest
      value: =System.LastMessage.Text

These snippets illustrate structure, not a complete production flow. Action names, expression contexts, input syntax, provider bindings, and available handlers must match the exact SDK and package schema.

What belongs in YAML

Declarative actions cover several common categories:

Category	Typical use	Control to keep outside or explicit
State and Power Fx	Variables, transformations, conditions	Validate types, missing values, and expression limits
Branch, loop, jump	Known routing and bounded repetition	Hard loop, time, token, and cost limits
Agent invocation	Drafting, classification, open-ended reasoning	Model, prompt, tools, data boundary, and evaluation
Function, MCP, HTTP	Deterministic work and external calls	Handler allowlist, identity, argument validation, approval
Human-in-the-loop	Review or missing input	Persist who approved what and invalidate stale approvals
Checkpoint and resume	Durable long-running flows	Version compatibility, idempotency, retention, and recovery tests

YAML is configuration, not a security sandbox. A declared HTTP or MCP action still depends on host code that resolves the handler and grants credentials. Register only named, reviewed handlers; do not allow the model or document to choose arbitrary endpoints, commands, or identities.

Package status needs an exact check

Microsoft’s July 23 announcement describes declarative workflows 1.0, calls Python package agent-framework-declarative 1.0.0, and describes the .NET declarative package as stable. Current Learn installation examples can still include --prerelease for .NET packages and prerelease instructions for related integrations.

Treat those as two different pieces of evidence:

1. the workflow format reached the announced 1.0 milestone;
2. the artifact and provider combination in your project may still require a prerelease feed or package flag.

Before adopting it, record the actual package version, install command, schema, transitive dependencies, release notes, and warning output. Lock those together with the YAML and its tests.

Build a reviewable workflow

Start with one path and one typed input. Give every action a stable ID, keep side effects behind named handlers, and add an explicit review action before external messages, production writes, purchases, deployment, or access changes.

Then test:

• valid, missing, malformed, and oversized inputs;
• every branch, including no-match and error routes;
• loop limits and cancellation;
• duplicate delivery and idempotent resume;
• a checkpoint created under the previous workflow version;
• revoked credentials and denied tools;
• untrusted text attempting to alter the YAML-defined policy;
• telemetry redaction and audit reconstruction.

Power Fx makes common expressions concise, but expression success does not validate business meaning. Keep invariant checks in deterministic code and return a typed failure rather than silently coercing unexpected data.

Choose YAML, code, or the Harness

Use a normal function when deterministic code is sufficient. Use declarative YAML for visible, standard orchestration. Use a code-first Workflow for custom graph behavior. Use the Agent Framework Harness when one agent needs an integrated long-task runtime rather than a known graph.

These can be composed: a workflow can call an agent, and an agent can be configured behind a stable action. Keep the boundary clear so reviewers can see which step is deterministic, which is model-driven, and which can change external state.

Frequently asked questions

What are Microsoft Agent Framework declarative workflows?

Declarative workflows define common Agent Framework orchestration in YAML instead of application code. Microsoft announced format version 1.0 for Python and .NET on July 23, 2026; the YAML loads into the same Workflow object used by code-first orchestration.

Can the same declarative workflow YAML run unchanged in Python and .NET?

Do not assume so. Current Python examples use top-level name, optional inputs, and actions, while current .NET examples use kind: Workflow with a trigger such as OnConversationStart and nested trigger actions. Validate against the selected SDK’s schema and package version.

When should I use code instead of a declarative workflow?

Use code-first workflows for complex custom logic, dynamic graph construction, or deep integration with existing Python or .NET code. Use declarative YAML for standard action sequences that change frequently or need review by people who should not edit application code.

Official sources

• Microsoft Developer Blog: Move agent orchestration workflows out of code
• Microsoft Learn: Declarative workflows
• Microsoft Learn: Agent Framework overview

Source check: August 3, 2026. Verify the selected SDK’s current package, install flags, YAML schema, action catalog, Power Fx behavior, handlers, checkpoint compatibility, and provider lifecycle.