MAF v1: Python and .NET — A Complete Tutorial Series
A chapter-by-chapter walkthrough of Microsoft Agent Framework with runnable examples in Python throughout and .NET through chapter 21. The series builds up from a single agent to the full multi-agent capstone application you see in this repo.
Each chapter is self-contained and in a separate folder under tutorials/. Every chapter ships with:
python/— a minimal runnable exampletests/— unit testsREADME.md— the chapter walkthroughPLAN.md— the chapter’s implementation plancompare.md(where useful) — side-by-side notes on API differences
Chapters 00-21 additionally ship dotnet/ — the same example in C#. Chapters 22-32 are Python-only for now; the status table below marks them, and the .NET column is the source of truth if this paragraph ever drifts.
Companion to an earlier series. The original Python-only e-commerce series lives at Building a Multi-Agent E-Commerce Platform — the complete guide. This MAF v1 series re-tells the same ground in both languages, adds the pieces we never covered (workflows, orchestrations, HITL, checkpoints, declarative, visualization), and ends at the refactored capstone.
Learning Path
The Companion post column links to the cross-posted write-up on nitinksingh.com when one is live. It’s optional background reading, not a prerequisite — every chapter’s own README.md here is the canonical, always-current source; posts that aren’t published yet are marked accordingly instead of linking to a page that 404s.
| # | Chapter | Status | Companion post |
|---|---|---|---|
| 00 | Setup your dev environment | Code done · draft | not yet published |
| 01 | Your First Agent | Code done · draft | not yet published |
| 02 | Adding Tools | Code done · draft | not yet published |
| 03 | Streaming and Multi-turn | Code done · draft | not yet published |
| 04 | Sessions and Memory | Draft | not yet published |
| 05 | Context Providers | Draft | not yet published |
| 06 | Middleware | Draft | not yet published |
| 07 | Observability with OpenTelemetry | Draft | not yet published |
| 08 | MCP Tools | Draft | not yet published |
| 09 | Workflow Executors and Edges | Draft | not yet published |
| 10 | Workflow Events and Builder | Draft | not yet published |
| 11 | Agents in Workflows | Draft | not yet published |
| 12 | Sequential Orchestration | Draft | not yet published |
| 13 | Concurrent Orchestration | Draft | not yet published |
| 14 | Handoff Orchestration | Draft | not yet published |
| 15 | Group Chat Orchestration | Draft | not yet published |
| 16 | Magentic Orchestration | Draft | not yet published |
| 17 | Human-in-the-Loop | Draft | not yet published |
| 18 | State and Checkpoints | Draft | not yet published |
| 19 | Declarative Workflows | Draft | not yet published |
| 20 | Workflow Visualization | Draft | not yet published |
| 20b | DevUI (interactive dashboard) | Draft | not yet published |
| 21 | Capstone Tour | Planned — folder scaffolded, no runnable code yet | not yet published |
| 22 | Group-Chat Debate (Round-Table Orchestration) | Code done · draft | not yet published |
| 23 | A2A Protocol | Code done · draft | not yet published |
| 24 | RAG and Grounding | Code done · draft | not yet published |
| 25 | Guardrails | Code done · draft | not yet published |
| 26 | Evals | Code done · draft | not yet published |
| 27 | Agent-as-tool | Code done · draft | not yet published |
| 28 | Reflection and Critique | Code done · draft | not yet published |
| 29 | Planner-Executor | Code done · draft | not yet published |
| 30 | Subworkflows | Code done · draft | not yet published |
| 31 | Retry and Compensation (Saga Pattern) | Code done · draft | not yet published |
| 32 | Cost Control and Budgets | Code done · draft | not yet published |
Tiers
- Tier 1 — Core Agent (Ch 01–04): the minimum to go from blank editor to working agent.
- Tier 2 — Agent Internals (Ch 05–08): memory, middleware, telemetry, MCP.
- Tier 3 — Workflow Foundations (Ch 09–11): executors, edges, events, wrapping agents.
- Tier 4 — Orchestrations (Ch 12–16): the five built-in multi-agent patterns.
- Tier 5 — Advanced (Ch 17–20): HITL, checkpoints, declarative, visualization.
- Capstone (Ch 21): a guided tour of this repo showing where every concept lives.
- Bonus pattern (Ch 22): a sixth orchestration pattern — round-table group chat — added after the capstone, documented against the production
workflows/group_chat.pymodule. - Tier 6 — Missing Concepts (Ch 23–27): patterns already live in this repo’s production code but never taught — A2A protocol, RAG/grounding, guardrails, evals, and agent-as-tool. Each stands alone with its own dependency-free runnable example; each cross-links the matching
docs/concepts/page instead of re-deriving the “why.” - Tier 7 — Patterns Without Production Wiring (Ch 28–31): reflection/critique, planner-executor, subworkflows, and retry/compensation (saga) — all taught as standalone, dependency-free examples rather than new orchestrator modes, since the mode registry’s per-mode SSE/UI/test surface makes a 6th or 7th live mode disproportionate to a single chapter. Ch 29 explicitly cross-references the still-unbuilt Magentic mode as the eventual production version of the planner-executor idea, so a bespoke production planner never has to be reconciled against it later. Ch 30 teaches MAF’s real
WorkflowExecutornesting primitive and is honest thatreturn_replace.pydoesn’t use it today. Ch 31 is genuinely greenfield — no saga/compensation code exists anywhere in this repo yet. - Ch 32 — Cost Control and Budgets: the one exception to Tier 7’s standalone-only rule. Light, proportionate production code —
CostBudgetMiddleware(agents/python/shared/guardrails/cost_budget_middleware.py) — closes a real gap (estimate_cost()previously had no runtime consumer, only a post-hoc eval reporter) without adding a new orchestration mode or any UI/SSE surface, so it fit inside one chapter’s scope.
Declared out of scope for this series (for now): multi-tenancy, fine-tuning, agent marketplaces, voice. Not overlooked — deliberately not yet covered.
Prerequisites
- Python 3.12+ and
uv - .NET 9 SDK
- Docker + Docker Compose
- An OpenAI or Azure OpenAI key (set in
.envat the repo root)
See Chapter 00 — Setup for step-by-step instructions.
Running a chapter
All Python chapters (01–20, 20b) share one uv project at tutorials/pyproject.toml — a single uv sync --project tutorials installs everything needed for every chapter, and every command runs from the repo root, not from inside the chapter folder:
# Python side
uv sync --project tutorials
uv run --project tutorials python tutorials/01-first-agent/python/main.py
uv run --project tutorials pytest tutorials/01-first-agent/python/tests -v
# .NET side
cd tutorials/01-first-agent/dotnet
dotnet run
dotnet test
Chapter 20b (DevUI) ships its own pyproject.toml and stays on the older cd tutorials/20b-devui/python && uv sync flow — see its README. Chapter 22 (Group-Chat Debate) imports the production workflows.group_chat module directly out of agents/python and runs from there instead of the tutorials/ project — see its README. Chapters 00 and 21 have no standalone runnable code; see their READMEs for what to run instead.
Both sides of every chapter produce equivalent observable behavior. If they don’t, the chapter isn’t shippable — file an issue.
Source: tutorials/README.md — this page is generated from the repository.