Learn Microsoft Agent Framework with Foundry — ZavaShop Supply‑Chain Workshop

A Chinese edition of every README in this workshop is preserved alongside as README.zh.md.

This workshop walks you through the Microsoft Agent Framework + Microsoft Foundry (gpt-5.5) stack in five LABs, each one delivering a runnable feature on top of a single, continuous story.

Two implementation tracks share the same story. Every LAB ships in both Python and .NET (C#). Same fixtures, same acceptance criteria, same Foundry model. Pick a track per LAB — you can switch between LABs.

---

0. The story — ZavaShop

ZavaShop is a fictional global e-commerce company. Its catalog covers three categories:

• 🏠 Home goods — bedding, decor, lighting
• 🌿 Garden & outdoor — garden tools, BBQ grills, outdoor furniture
• 🔌 Small home appliances — coffee machines, air purifiers, robotic vacuums

ZavaShop has 5 fulfillment centers (Seattle SEA-01, London LON-02, Shanghai SHA-03, São Paulo SAO-04, Dubai DXB-05) and partners with dozens of suppliers. Over the past year, the same pain points keep surfacing:

The CTO has signed off on a Foundry-as-the-brain charter:

Every team rebuilds its workflow on Microsoft Agent Framework + Microsoft Foundry. The model is gpt-5.5. Workflows must orchestrate cross-team. The frontend is AG-UI + React, so the CEO can see everything from one console.

You are the AI Platform Engineer at ZavaShop. The five LABs below are the five deliverables of this initiative.

---

1. The five LABs

Every LAB ships:

• A story setup so you understand why you are building this
• A task list anchored to the SKILL’s best practices
• Acceptance criteria so you can self-verify
• A story handoff that connects to the next LAB

---

2. Common prerequisites

2.1 Azure / Foundry

• An Azure subscription with the Microsoft Foundry service enabled
• A Foundry project with the gpt-5.5 model + text-embedding-3-small deployed
• Local Azure CLI logged in:

az login --use-device-code

2.2 Local environment — pick a track (or both)

The core fixtures and the Coding Agent are language-agnostic. Pick whichever LAB tracks you want to run.

Python option

• Python 3.10+
• Node.js 20+ (LAB05 frontend only)

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows PowerShell

pip install \
  agent-framework \
  agent-framework-azure-ai \
  agent-framework-ag-ui \
  azure-identity \
  python-dotenv \
  fastapi \
  "uvicorn[standard]"

.NET option

• .NET 10 SDK (dotnet --version ≥ 10.0.100)
• Node.js 20+ (LAB05 frontend only)

The .NET track uses the prerelease Agent Framework NuGet packages — each C# SKILL lists the exact set per LAB. The common ones are:

Microsoft.Agents.AI
Microsoft.Agents.AI.Foundry
Microsoft.Agents.AI.Workflows                          # LAB 4 / LAB 5
Microsoft.Agents.AI.Hosting.AGUI.AspNetCore            # LAB 5 server
Microsoft.Agents.AI.AGUI                               # LAB 5 client
Microsoft.Extensions.AI
Azure.AI.Projects
Azure.Identity
ModelContextProtocol                                   # MCP clients

Each LAB’s .csproj links the shared data helper:

Individual LABs may add small extras (e.g. AG-UI client). Check each LAB’s README for details.

2.3 .env

Create .env at the workspace root:

FOUNDRY_PROJECT_ENDPOINT=https://.services.ai.azure.com/api/projects/
FOUNDRY_MODEL=gpt-5.5
AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Only required for LAB05
AGUI_SERVER_URL=http://127.0.0.1:5100/
AG_UI_API_KEY=zava-control-tower-demo-key

Every LAB reads FOUNDRY_MODEL / FOUNDRY_PROJECT_ENDPOINT from the environment — never hardcode these in source files. The same env vars are used by both the Python and the .NET tracks.

---

3. Six SKILL files (three per track, read in order)

The Coding Agent always loads the SKILL for the chosen track. Python and C# SKILLs cover the same topics so you can swap tracks per LAB.

Python

.NET (C#)

Every LAB README starts by saying “Read the SKILL first.” Do not skip.

---

3.5 Shared ZavaShop data (workshop/data/)

All five LABs read the same fictional dataset from workshop/data/ instead of inlining mock dicts. That keeps stock numbers, PO IDs, customer preferences and freight rates consistent across labs:

In every Python LAB script, add the data folder to sys.path and call the loader:

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "data"))
from zava_data import find_stock, find_po

In every .NET LAB project, link the shared helper into the csproj and use it directly:

using ZavaShop.Workshop.Data;

var stock = ZavaData.FindStock("SKU-7421", "SEA-01");
int onHand = stock?["on_hand"]?.GetValue() ?? 0;   // 312

See workshop/data/README.md for the full schema and editing rules.

---

4. GitHub Copilot Coding Agent + SKILL convention

This workshop ships a Coding Agent ready for GitHub Copilot Chat:

• Definition: .github/agents/zavashop-coding-agent.agent.md
• Activation: open Agent Mode in VS Code Copilot Chat → open the Agent picker → select zavashop-coding-agent.

It already knows the LAB ↔ SKILL routing and the track ↔ SKILL routing. For every LAB, the very first step in the README is to pick the agent from the dropdown and send a plain-text prompt that always states (a) the LAB number and (b) the language:

I'm doing LAB X in  — 

Do not type @zavashop-coding-agent. The agent is chosen from the Agent Mode dropdown; the chat text is plain task description. If you omit the language, the agent will ask once and then stick with your choice for the LAB.

When you do that, the Coding Agent will:

1. Look up the LAB ↔ SKILL routing table for your track.
2. read_file the matching SKILL into context (Python or C#).
3. read_file the LAB README (Python section or .NET section).
4. Generate the task plan, write the code, run validation.
5. Map each acceptance criterion in your LAB and report which ones pass.

Always start a LAB by switching from the default Copilot Chat agent to zavashop-coding-agent — this guarantees the SKILL is loaded before any code is written.

The Coding Agent will reply in your language (English by default). If you write Chinese, it will switch automatically.

---

5. Suggested order

LAB01  →  LAB02  →  LAB03  →  LAB04  →  LAB05
single   tools+    memory+   workflow   AG-UI
agent    Skills    Eval      (HITL)     frontend

• LAB01 → LAB02 → LAB03 progress from a single agent to a “real” agent (tools, Skills, memory, evaluation).
• LAB04 lifts the single agent up to a multi-agent workflow (with stock-check, shipping-quote, approval — reusing LAB01’s tool).
• LAB05 publishes the LAB04 workflow as an AG-UI control tower for end-user interaction.

You can do them in 5 short sessions or in one long workshop day — your call.

---

6. Directory layout

MAF_Foundry_Foundation_Workshop/
├── README.md                                  # ← you are here
├── README.zh.md                               # Chinese edition
├── .github/
│   ├── agents/
│   │   └── zavashop-coding-agent.agent.md   # GitHub Copilot Coding Agent (Python + .NET aware)
│   └── skills/
│       ├── agent-framework-azure-ai-py/         # 🐍 Python track
│       ├── agent-framework-workflows-py/
│       ├── agent-framework-agui-py/
│       ├── agent-framework-azure-ai-csharp/     # 🟦 .NET track
│       ├── agent-framework-workflows-csharp/
│       └── agent-framework-agui-csharp/
└── workshop/
    ├── data/                                  # 🔵 shared ZavaShop fixtures (see data/README.md)
    │   ├── zava_data.py                       # Python loader
    │   ├── ZavaData.cs                        # .NET loader (linked into each LAB csproj)
    │   ├── warehouses.json / skus.json / inventory.json
    │   ├── purchase_orders.json / suppliers.json / contracts.json
    │   ├── customers.json / orders.json / carriers.json
    │   └── exceptions.json / eval_queries.jsonl
    ├── LAB01-inventory-agent/
    ├── LAB02-procurement-toolbox/
    ├── LAB03-customer-memory-eval/
    ├── LAB04-fulfillment-workflow/
    └── LAB05-control-tower-agui/

---

7. Onwards

Set up your environment, then go to LAB01 — Inventory Agent to meet Mei, the warehouse supervisor desperate for help.

One mantra to remember: “Read the SKILL first.”