MAF v1 — Setup your dev environment (Python + .NET)

Why this chapter

The rest of the series runs real code against real LLMs. You need one Python toolchain, one .NET toolchain, Docker for the supporting infra, and a key for either OpenAI or Azure OpenAI. Do this once and forget it.

If you have never heard of the Microsoft Agent Framework before, read the next section first. It makes the installation steps feel less arbitrary. If you’re already running MAF locally, skip straight to Step 1.

What is the Microsoft Agent Framework?

The Microsoft Agent Framework (MAF) is Microsoft’s SDK for building LLM-powered agents and multi-agent workflows. It ships in two flavours that share the same abstractions:

• Python: the agent-framework package (plus agent-framework-a2a, agent-framework-openai, and friends).
• .NET: the Microsoft.Agents.AI family of NuGet packages (built on Microsoft.Extensions.AI).

Under the hood MAF wraps three moving parts. An agent is an LLM (called a chat client in MAF) plus instructions, tools, and optional middleware. A session is how MAF remembers a multi-turn conversation. A workflow is a graph of executors you use when an LLM-driven agent is too free-form and you want deterministic orchestration instead.

This tutorial series builds a full e-commerce platform on top of those three primitives. The stack you’re installing in this chapter is a superset of what any individual chapter needs. We over-provision on purpose so later chapters don’t ask you to install anything new.

You install the blue pieces (language toolchains) and the grey pieces (Docker + infra) locally. You bring your own orange piece (one LLM provider key). The green piece is Next.js, which talks to whichever backend you run.

Prerequisites

You need a Unix-like shell. macOS and Linux work out of the box; on Windows, use WSL2². Everything below assumes bash or zsh.

If you plan to follow the official Microsoft tutorials alongside this series, keep the MAF docs tabs open:

• Agent Framework overview³
• Get Started, Step 1: Your First Agent

Step 1: Install the toolchains

uv (Python package manager)

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify and install Python 3.12:

uv --version          # expect: uv 0.5.x or later
uv python install 3.12

Why uv and not pip / poetry? It resolves and installs 10–100× faster, manages the virtualenv for you, and is what every tutorial in this repo pins. Treat uv as the single entry point for Python deps.

.NET 9 SDK

Verify:

dotnet --list-sdks    # expect: 9.0.x or later

Docker + Compose v2

Install Docker Desktop (macOS / Windows) or Docker Engine + docker-compose-plugin on Linux. docker compose version must print a v2.x string.

Node 20 + pnpm (for the frontend)

# If you don't have Node:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 20

# pnpm:
corepack enable pnpm

Step 2: Clone and configure

git clone https://github.com/nitin27may/e-commerce-agents.git
cd e-commerce-agents
cp .env.minimal .env

.env.minimal holds the one variable a first run needs. .env.example is the full reference, with every switch the stack understands; copy that one instead when you want to explore the options.

Open .env and pick one provider. You only need one key to follow the series; the code reads LLM_PROVIDER and switches automatically.

Option A: OpenAI

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...           # from platform.openai.com/api-keys
LLM_MODEL=gpt-4.1
EMBEDDING_MODEL=text-embedding-3-small

Get a key at platform.openai.com/api-keys. The series assumes a model with tool-calling support: gpt-4.1, gpt-4o, or gpt-4o-mini all work.

Option B: Azure OpenAI

LLM_PROVIDER=azure
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_KEY=...
AZURE_OPENAI_DEPLOYMENT=gpt-4.1
AZURE_OPENAI_API_VERSION=2025-03-01-preview
AZURE_EMBEDDING_DEPLOYMENT=text-embedding-3-small

On Azure OpenAI, AZURE_OPENAI_DEPLOYMENT is the deployment name you created in the portal, not the model family. If your deployment is called gpt-4.1-prod, that’s what goes here.

Environment variable reference

Keep JWT_SECRET and AGENT_SHARED_SECRET at their defaults for local dev. They’re rotated in production only.

Step 3: Verify

One script checks everything at once:

./scripts/verify-setup.sh

Expected output:

Tooling
  ✓ uv (Python package manager)
  ✓ Python 3.12+
  ✓ .NET SDK 9+
  ✓ Docker
  ✓ Docker Compose v2
  ...

Summary
  All 15 checks passed.

If any check shows ✗, fix that item and re-run; the script is idempotent. See Troubleshooting below for common failures.

Step 4: Run something

Bring up the Python stack:

./scripts/dev.sh --demo

--demo pulls the ten released images from GitHub Container Registry rather than building them, which takes about a minute instead of about twelve. Drop the flag when you want to build from your own working tree, which is what the later chapters assume.

• Frontend: http://localhost:3000
• Orchestrator API: http://localhost:8080
• Aspire Dashboard (telemetry): http://localhost:18888

Log in with any seeded test user (see the repo root README.md) and try a prompt like “show me running shoes under $100”.

To try the .NET stack (as each chapter’s dotnet/ side lands):

docker compose -f docker-compose.dotnet.yml --profile agents up --build

Both compose files expose the backend on :8080, so you only run one backend at a time.

Side-by-side differences

This chapter is pure tooling, with no agent code yet. Two cross-cutting differences are worth flagging before Chapter 01:

Troubleshooting

The most common verify-setup.sh failures and what to do about them:

Gotchas

• Azure deployment name vs model family. Portal shows gpt-4.1-prod → put gpt-4.1-prod in .env, not gpt-4.1. This is the #1 Azure pitfall.
• verify-setup.sh rejects the placeholder. OPENAI_API_KEY=sk-your-openai-api-key-here is a sentinel. Replace with your real key.
• WSL2 + Docker Desktop networking. On Windows, the containers bind to WSL2’s localhost; confirm localhost:3000 reaches it.
• Cost awareness. Every request hits a paid LLM. gpt-4.1 is cheap per-request, but tight loops (e.g. streaming tests) add up. Use gpt-4o-mini for iteration if you want to keep the meter low.

Tests

This chapter’s “test” is the verify script. Run it in CI to catch toolchain regressions:

./scripts/verify-setup.sh
echo "exit code: $?"   # 0 if all checks pass

The script exits non-zero on the first failure, making it usable as a gate in GitHub Actions.

How this shows up in the capstone

verify-setup.sh lives alongside scripts/dev.sh and is linked from the repo root README.md. It is the single source of truth for “my environment is ready”, both for newcomers on their first clone and for CI.

Further reading & links

This chapter

• Source on GitHub: tutorials/00-setup
• Next: Chapter 01: Your First Agent

Microsoft Agent Framework docs

• Overview³
• Get Started
• Agents: Providers (OpenAI vs Azure OpenAI)

Supporting tools

• uv documentation · .NET 9 SDK⁴ · Docker Compose v2
• Platform OpenAI API keys⁵ · Azure OpenAI portal

Series shared resources

• Mermaid style guide: the palette all diagrams in this series use.
• Jargon glossary: one-line definitions for every MAF term.

What’s next

Chapter 01: Your First Agent takes the stack you just installed and builds the smallest possible MAF agent, about 40 lines per language, to prove everything is wired up.