Skip to content
Mf

Microsoft Agent Framework — Workflows & Declarative Agents

Graph workflows with WorkflowBuilder and WorkflowContext, workflow visualisation, and YAML-defined agents and workflows with agent-framework-declarative.

This page covers two related capabilities:

  1. Graph workflows: WorkflowBuilder in agent-framework-core (Python) and Microsoft.Agents.AI.Workflows (.NET) wires executors and agents into a directed graph with fan-out, fan-in, switch-case and conditional routing, checkpointing and human-in-the-loop pauses.
  2. Declarative agents and workflows: agent-framework-declarative loads agents and workflows from YAML.

The examples are Python. For .NET, see the workflow and declarative sections of the .NET feature tour.

The workflow types are exported from agent_framework.

Class / functionPurpose
WorkflowBuilder(max_iterations=100, name=None, description=None, *, start_executor, checkpoint_storage=None, output_from=..., intermediate_output_from=...)Fluent builder; .build() returns a Workflow.
WorkflowThe compiled graph. run(message), run(message, stream=True), run(responses=...), run(checkpoint_id=...), as_agent().
Executor + @handlerClass-based node with one handler per input type.
@executor / FunctionExecutorA node from a single function.
AgentExecutorWraps an agent; the builder does this for you when you pass an agent.
WorkflowExecutorWraps a whole workflow as one node.
Case, DefaultBranches for switch-case routing.
InMemoryCheckpointStorage, FileCheckpointStorageCheckpoint stores, passed as checkpoint_storage=.
WorkflowContext, WorkflowEvent, WorkflowRunResult, WorkflowRunStateRuntime types.
WorkflowVizMermaid and Graphviz rendering.

Builder methods, all returning the builder for chaining:

  • .add_edge(source, target, condition=None): a fixed or conditional edge.
  • .add_chain([a, b, c]): shorthand for consecutive edges.
  • .add_fan_out_edges(source, targets) and .add_fan_in_edges(sources, target): parallel branches and their join (the target receives a list).
  • .add_switch_case_edge_group(source, [Case(...), ..., Default(...)]): first matching branch.
  • .add_multi_selection_edge_group(source, targets, selection_func): a function picks the subset of targets.
  • .build(): validates the graph (types, connectivity, duplicate ids) and returns the Workflow.

Two rules catch most people out:

  • Return values are discarded. An executor passes data on only by calling await ctx.send_message(...), and produces workflow output only with await ctx.yield_output(...). A function executor that just returns a value sends nothing, and the workflow finishes with no output.
  • Types are checked at build(). Function executors need annotations (or explicit input= / output= / workflow_output= arguments), so lambdas can’t be used. Each edge’s target must accept a type the source sends; an agent node accepts str, Message, a list of these or an upstream agent’s response.
import asyncio
from typing_extensions import Never
from agent_framework import WorkflowBuilder, WorkflowContext, executor
@executor(id="score")
async def score(text: str, ctx: WorkflowContext[dict]) -> None:
await ctx.send_message({"text": text, "score": len(text.split()) / 10})
@executor(id="accept")
async def accept(payload: dict, ctx: WorkflowContext[Never, str]) -> None:
await ctx.yield_output(f"Accepted: {payload['text']}")
@executor(id="reject")
async def reject(payload: dict, ctx: WorkflowContext[Never, str]) -> None:
await ctx.yield_output(f"Rejected: {payload['text']}")
workflow = (
WorkflowBuilder(start_executor=score, name="review")
.add_edge(score, accept, condition=lambda p: p["score"] >= 0.5)
.add_edge(score, reject, condition=lambda p: p["score"] < 0.5)
.build()
)
print(asyncio.run(workflow.run("two words")).get_outputs()) # ['Rejected: two words']

Runnable examples of every routing shape, output filtering with output_from, nesting, events, checkpointing and as_agent() are in the Python comprehensive guide. The prebuilt multi-agent patterns (sequential, concurrent, handoff, group chat, Magentic) are on the orchestration page, and workflows written as plain async functions with @workflow / @step are on the functional workflows page.

from agent_framework import FileCheckpointStorage, WorkflowBuilder
storage = FileCheckpointStorage("./checkpoints")
workflow = (
WorkflowBuilder(start_executor=score, name="review", checkpoint_storage=storage)
.add_edge(score, accept, condition=lambda p: p["score"] >= 0.5)
.add_edge(score, reject, condition=lambda p: p["score"] < 0.5)
.build()
)

The store saves one checkpoint per superstep and exposes save, load, get_latest, list_checkpoints, list_checkpoint_ids and delete. Resume with workflow.run(checkpoint_id=...). Details and custom backends are on the checkpointing page.

Every handler takes the message plus a WorkflowContext. Its type parameters declare what the executor may send and yield:

AnnotationAllows
WorkflowContextSide effects only.
WorkflowContext[OutT]ctx.send_message(value: OutT) to downstream executors.
WorkflowContext[OutT, W_OutT]send_message plus ctx.yield_output(value: W_OutT) as workflow output.
WorkflowContext[Never, W_OutT]Workflow output only.
WorkflowContext[str | int, bool]Unions on either side.
MemberPurpose
await send_message(message, target_id=None)Send downstream; target_id delivers to one connected executor instead of all of them.
await yield_output(output)Emit a workflow output (result.get_outputs()).
await add_event(event)Emit a custom WorkflowEvent.
await request_info(request_data, response_type, *, request_id=None)Pause for an external response, received by a @response_handler on the same executor.
get_state(key, default=None) / set_state(key, value)Run-scoped state shared by all executors.
source_executor_ids / get_source_executor_id()Who sent the current message; the method raises when there are several (fan-in).
is_streaming()Whether the run was started with stream=True.

Targeted delivery and shared state together:

import asyncio
from typing_extensions import Never
from agent_framework import WorkflowBuilder, WorkflowContext, executor
@executor(id="intake")
async def intake(ticket: dict, ctx: WorkflowContext[str]) -> None:
ctx.set_state("ticket_id", ticket["id"])
target = "premium" if ticket.get("tier") == "pro" else "standard"
await ctx.send_message(ticket["text"], target_id=target)
@executor(id="premium")
async def premium(text: str, ctx: WorkflowContext[Never, str]) -> None:
await ctx.yield_output(f"[{ctx.get_state('ticket_id')}] priority queue: {text}")
@executor(id="standard")
async def standard(text: str, ctx: WorkflowContext[Never, str]) -> None:
await ctx.yield_output(f"[{ctx.get_state('ticket_id')}] standard queue: {text}")
workflow = (
WorkflowBuilder(start_executor=intake)
.add_edge(intake, premium)
.add_edge(intake, standard)
.build()
)
result = asyncio.run(workflow.run({"id": "T-1", "tier": "pro", "text": "Login fails"}))
print(result.get_outputs()) # ['[T-1] priority queue: Login fails']

WorkflowViz(workflow) renders any built workflow. Mermaid and DOT need no extra dependencies; SVG, PNG and PDF need the graphviz package and the Graphviz dot binary.

from agent_framework import WorkflowViz
viz = WorkflowViz(workflow)
print(viz.to_mermaid())
print(viz.to_digraph()) # DOT source
# viz.save_svg("workflow.svg") # also save_png, save_pdf, export(format=...)

For the conditional workflow in the first example, to_mermaid() produces:

flowchart TD
score["score (Start)"];
accept["accept"];
reject["reject"];
score -. conditional .-> accept;
score -. conditional .-> reject;

Conditional edges are drawn dashed and labelled, nested workflows appear as subgraphs, and include_internal_executors=True adds the framework’s internal nodes.

Terminal window
pip install agent-framework-declarative

agent-framework-declarative is stable and needs no --pre.

ClassPurpose
AgentFactoryBuilds an agent from YAML: create_agent_from_yaml_path, create_agent_from_yaml, create_agent_from_dict (each with an _async twin).
WorkflowFactoryBuilds a workflow from YAML after register_agent, register_tool and register_binding calls: create_workflow_from_yaml_path, create_workflow_from_yaml, create_workflow_from_definition.
ExternalInputRequest, ExternalInputResponse, AgentExternalInputRequest, AgentExternalInputResponseHuman-in-the-loop request and response types.
DefaultHttpRequestHandler, DefaultMCPToolHandlerHandlers for the HTTP-request and MCP-tool actions.
DeclarativeLoaderError, DeclarativeWorkflowError, ProviderLookupErrorErrors.
from agent_framework.declarative import AgentFactory
agent = AgentFactory().create_agent_from_yaml_path("agent.yaml")
result = await agent.run("Hello")

AgentFactory(safe_mode=True) (the default) makes =Env.* expressions in the YAML resolve to empty values, so a YAML file from an untrusted source can’t read your environment variables. It does not check file paths, so validate any path you pass to create_agent_from_yaml_path.

from agent_framework.declarative import WorkflowFactory
factory = WorkflowFactory()
factory.register_agent("ResearcherAgent", researcher_agent)
factory.register_agent("WriterAgent", writer_agent)
factory.register_tool("get_weather", get_weather)
workflow = factory.create_workflow_from_yaml_path("pipeline.yaml")
result = await workflow.run({"topic": "AI in healthcare"})

A workflow that uses the HTTP-request or MCP-tool actions needs http_request_handler= or mcp_tool_handler= on the factory; without them, building the workflow raises DeclarativeWorkflowError.

Declarative workflows use Power Fx expressions and a fixed set of kind: actions. The full reference is in Microsoft’s documentation, which also covers the .NET loader.

The Python loader (agent-framework-declarative 1.3.0) builds these kinds:

CategoryActions
VariablesSetVariable, SetMultipleVariables, SetTextVariable, SetValue, ResetVariable, ClearAllVariables, ParseValue, EditTable, EditTableV2
Control flowIf, ConditionGroup, Foreach, BreakLoop, ContinueLoop, GotoAction
OutputSendActivity
Agents and toolsInvokeAzureAgent, InvokeFunctionTool, HttpRequestAction, InvokeMcpTool
Human in the loopQuestion, RequestExternalInput
Workflow controlEndWorkflow, EndConversation, EndDialog, CancelDialog, CancelAllDialogs, CreateConversation

Any other kind: (for example RepeatUntil, Confirmation or EmitEvent, which appear in other Copilot Studio dialects) is skipped with a logged warning rather than rejected, so check the log when a step seems to do nothing. ALL_ACTION_EXECUTORS in agent_framework_declarative._workflows lists the supported kinds for your installed version.

Power Fx expressions (values starting with =) are evaluated by the .NET Power Fx engine through pythonnet, so a .NET runtime must be installed; without one the run fails with RuntimeError: PowerFx is not available. A workflow that writes checkpoints also needs agent_framework_declarative._workflows._declarative_base:ActionComplete in the storage’s allowed_checkpoint_types, otherwise every checkpoint save fails (the run itself continues).

The YAML below runs as shown and outputs ['Hello, Ada!'] for workflow.run({"name": "Ada"}):

kind: AdaptiveDialog
schema: v1
actions:
- kind: SetVariable
id: greet
variable: Local.name
value: =Workflow.Inputs.name
- kind: SendActivity
activity:
text: =Concat("Hello, ", Local.name, "!")
DateVersionChanges
2026-10-251.22.0Replaced the YAML action table with the kinds the Python loader actually builds (AppendValue, RepeatUntil, EmitEvent, Confirmation and WaitForInput are not among them and are skipped with a warning). Added the .NET runtime requirement for Power Fx and the checkpoint allow-list entry declarative workflows need.