Microsoft Agent Framework Workflows support ships with the core agent-framework or agent-framework-core package, so no extra installation step is required.
To install with visualization support:
pip install agent-framework[viz] --preTo export visualization images you also need to install GraphViz.
Begin with the _start-here folder in order. These three samples introduce the core ideas of executors, edges, agents in workflows, and streaming.
| Sample | File | Concepts |
|---|---|---|
| Executors and Edges | _start-here/step1_executors_and_edges.py | Minimal workflow with basic executors and edges |
| Agents in a Workflow | _start-here/step2_agents_in_a_workflow.py | Introduces adding Agents as nodes; calling agents inside a workflow |
| Streaming (Basics) | _start-here/step3_streaming.py | Extends workflows with event streaming |
Once comfortable with these, explore the rest of the samples below.
| Sample | File | Concepts |
|---|---|---|
| Azure Chat Agents (Streaming) | agents/azure_chat_agents_streaming.py | Add Azure Chat agents as edges and handle streaming events |
| Azure AI Chat Agents (Streaming) | agents/azure_ai_agents_streaming.py | Add Azure AI agents as edges and handle streaming events |
| Azure Chat Agents (Function Bridge) | agents/azure_chat_agents_function_bridge.py | Chain two agents with a function executor that injects external context |
| Azure Chat Agents (Tools + HITL) | agents/azure_chat_agents_tool_calls_with_feedback.py | Tool-enabled writer/editor pipeline with human feedback gating |
| Custom Agent Executors | agents/custom_agent_executors.py | Create executors to handle agent run methods |
| Sequential Workflow as Agent | agents/sequential_workflow_as_agent.py | Build a sequential workflow orchestrating agents, then expose it as a reusable agent |
| Concurrent Workflow as Agent | agents/concurrent_workflow_as_agent.py | Build a concurrent fan-out/fan-in workflow, then expose it as a reusable agent |
| Magentic Workflow as Agent | agents/magentic_workflow_as_agent.py | Configure Magentic orchestration with callbacks, then expose the workflow as an agent |
| Workflow as Agent (Reflection Pattern) | agents/workflow_as_agent_reflection_pattern.py | Wrap a workflow so it can behave like an agent (reflection pattern) |
| Workflow as Agent + HITL | agents/workflow_as_agent_human_in_the_loop.py | Extend workflow-as-agent with human-in-the-loop capability |
| Sample | File | Concepts |
|---|---|---|
| Checkpoint & Resume | checkpoint/checkpoint_with_resume.py | Create checkpoints, inspect them, and resume execution |
| Checkpoint & HITL Resume | checkpoint/checkpoint_with_human_in_the_loop.py | Combine checkpointing with human approvals and resume pending HITL requests |
| Checkpointed Sub-Workflow | checkpoint/sub_workflow_checkpoint.py | Save and resume a sub-workflow that pauses for human approval |
| Handoff + Tool Approval Resume | checkpoint/handoff_with_tool_approval_checkpoint_resume.py | Handoff workflow that captures tool-call approvals in checkpoints and resumes with human decisions |
| Sample | File | Concepts |
|---|---|---|
| Sub-Workflow (Basics) | composition/sub_workflow_basics.py | Wrap a workflow as an executor and orchestrate sub-workflows |
| Sub-Workflow: Request Interception | composition/sub_workflow_request_interception.py | Intercept and forward sub-workflow requests using @handler for SubWorkflowRequestMessage |
| Sub-Workflow: Parallel Requests | composition/sub_workflow_parallel_requests.py | Multiple specialized interceptors handling different request types from same sub-workflow |
| Sample | File | Concepts |
|---|---|---|
| Sequential Executors | control-flow/sequential_executors.py | Sequential workflow with explicit executor setup |
| Sequential (Streaming) | control-flow/sequential_streaming.py | Stream events from a simple sequential run |
| Edge Condition | control-flow/edge_condition.py | Conditional routing based on agent classification |
| Switch-Case Edge Group | control-flow/switch_case_edge_group.py | Switch-case branching using classifier outputs |
| Multi-Selection Edge Group | control-flow/multi_selection_edge_group.py | Select one or many targets dynamically (subset fan-out) |
| Simple Loop | control-flow/simple_loop.py | Feedback loop where an agent judges ABOVE/BELOW/MATCHED |
| Sample | File | Concepts |
|---|---|---|
| Human-In-The-Loop (Guessing Game) | human-in-the-loop/guessing_game_with_human_input.py | Interactive request/response prompts with a human |
| Azure Agents Tool Feedback Loop | agents/azure_chat_agents_tool_calls_with_feedback.py | Two-agent workflow that streams tool calls and pauses for human guidance between passes |
| Agents with Approval Requests in Workflows | human-in-the-loop/agents_with_approval_requests.py | Agents that create approval requests during workflow execution and wait for human approval to proceed |
For observability samples in Agent Framework, see the observability getting started samples. The sample demonstrates integrating observability into workflows.
| Sample | File | Concepts |
|---|---|---|
| Concurrent Orchestration (Default Aggregator) | orchestration/concurrent_agents.py | Fan-out to multiple agents; fan-in with default aggregator returning combined ChatMessages |
| Concurrent Orchestration (Custom Aggregator) | orchestration/concurrent_custom_aggregator.py | Override aggregator via callback; summarize results with an LLM |
| Concurrent Orchestration (Custom Agent Executors) | orchestration/concurrent_custom_agent_executors.py | Child executors own ChatAgents; concurrent fan-out/fan-in via ConcurrentBuilder |
| Group Chat Orchestration with Prompt Based Manager | orchestration/group_chat_prompt_based_manager.py | LLM Manager-directed conversation using GroupChatBuilder |
| Group Chat with Simple Function Selector | orchestration/group_chat_simple_selector.py | Group chat with a simple function selector for next speaker |
| Handoff (Simple) | orchestration/handoff_simple.py | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response |
| Handoff (Specialist-to-Specialist) | orchestration/handoff_specialist_to_specialist.py | Multi-tier routing: specialists can hand off to other specialists using .add_handoff() fluent API |
| Handoff (Return-to-Previous) | orchestration/handoff_return_to_previous.py | Return-to-previous routing: after user input, routes back to the previous specialist instead of coordinator using .enable_return_to_previous() |
| Magentic Workflow (Multi-Agent) | orchestration/magentic.py | Orchestrate multiple agents with Magentic manager and streaming |
| Magentic + Human Plan Review | orchestration/magentic_human_plan_update.py | Human reviews/updates the plan before execution |
| Magentic + Checkpoint Resume | orchestration/magentic_checkpoint.py | Resume Magentic orchestration from saved checkpoints |
| Sequential Orchestration (Agents) | orchestration/sequential_agents.py | Chain agents sequentially with shared conversation context |
| Sequential Orchestration (Custom Executor) | orchestration/sequential_custom_executors.py | Mix agents with a summarizer that appends a compact summary |
Magentic checkpointing tip: Treat MagenticBuilder.participants keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast.
Handoff workflow tip: Handoff workflows maintain the full conversation history including any
ChatMessage.additional_properties emitted by your agents. This ensures routing metadata remains
intact across all agent transitions. For specialist-to-specialist handoffs, use .add_handoff(source, targets)
to configure which agents can route to which others with a fluent, type-safe API.
| Sample | File | Concepts |
|---|---|---|
| Concurrent (Fan-out/Fan-in) | parallelism/fan_out_fan_in_edges.py | Dispatch to multiple executors and aggregate results |
| Aggregate Results of Different Types | parallelism/aggregate_results_of_different_types.py | Handle results of different types from multiple concurrent executors |
| Map-Reduce with Visualization | parallelism/map_reduce_and_visualization.py | Fan-out/fan-in pattern with diagram export |
| Sample | File | Concepts |
|---|---|---|
| Shared States | state-management/shared_states_with_agents.py | Store in shared state once and later reuse across agents |
| Sample | File | Concepts |
|---|---|---|
| Concurrent with Visualization | visualization/concurrent_with_visualization.py | Fan-out/fan-in workflow with diagram export |
- Sample text inputs used by certain workflows:
Notes
- Agent-based samples use provider SDKs (Azure/OpenAI, etc.). Ensure credentials are configured, or adapt agents accordingly.
Sequential orchestration uses a few small adapter nodes for plumbing:
- "input-conversation" normalizes input to
list[ChatMessage] - "to-conversation:" converts agent responses into the shared conversation
- "complete" publishes the final
WorkflowOutputEventThese may appear in event streams (ExecutorInvoke/Completed). They’re analogous to concurrent’s dispatcher and aggregator and can be ignored if you only care about agent activity.
-
AzureOpenAIChatClient: Set Azure OpenAI environment variables as documented here. These variables are required for samples that construct
AzureOpenAIChatClient -
OpenAI (used in orchestration samples):