View all files | ||||
A hands-on lab series that teaches you to deliver a multi-agent retail supply-chain solution end-to-end through a team of six GitHub Copilot Custom Coding Agents — from requirements through deployment. Stack: Microsoft Agent Framework (MAF) + GitHub Copilot SDK (gpt-5.5) + AKS + Azure Container Apps.
Every artifact in this repo — specs, agent code, MCP servers, tests, Bicep, Helm, CI — is authored by a named GitHub Copilot Custom Coding Agent that owns one slice of the repo and carries its own tools, skills, and refusal rules.
The labs teach the operating model itself — not just the code. By the end you will have shipped ZavaShop and internalised a repeatable Copilot Custom Agent workflow you can take to any project.
Each agent is a file under .github/agents/ (*.agent.md). You invoke it by typing /<agent-name> in Copilot Chat. Three workflow prompts in .github/prompts/ chain the agents together: /feature-from-issue, /spec-to-code, /ship-it.
ZavaShop is a fast-growing global retailer with 500+ stores. Their supply chain runs on a mix of legacy ERPs, supplier portals, and ad-hoc spreadsheets. The Ops team wants an AI-native control plane — a fleet of cooperating agents that:
| InventoryAgent | Monitor stock-out risk across stores and warehouses |
| SupplierAgent | Negotiate purchase orders with suppliers via MCP-backed tools |
| LogisticsAgent | Plan shipments, track ETAs, re-route on disruption |
| PricingAgent | Recommend dynamic pricing from demand + competitor signals |
| OrchestratorAgent | The "store manager" — powered by the GitHub Copilot SDK, routes goals to the specialist agents |
The orchestrator runs as a long-lived service on AKS. The specialist agents run as event-driven workloads on ACA with KEDA scale-to-zero. All agents share a fleet of MCP servers that wrap ZavaShop's domain tools (inventory DB, supplier API, shipping API, pricing API).
The five labs are five chapters of one story — ZavaShop going from a blank Azure subscription to a live, observable retail control plane:
| 01 | Day 0 — lay the foundation | The platform team provisions the loading docks (ACR), the shop floor (AKS), the bursty back-of-house (ACA), the safe (Key Vault), and the single staff badge (UAMI) that every worker will wear. |
| 02 | Hire the specialists | Each business role becomes a typed MAF ChatAgent. Inventory, Supplier, Logistics, Pricing, and the Orchestrator are born — every external system kept behind an MCP server so the LLM never owns business state. |
| 03 | Make them a team | The orchestrator stops being a one-shot LLM call and becomes a deterministic Workflow. Secrets leave .env and move into Key Vault. The whole fleet boots locally via Docker Compose so a /plan can be debugged end-to-end without the cloud. |
| 04 | Earn trust before opening day | A four-layer test pyramid + five golden eval scenarios (S1–S5) pin the fleet's behaviour. The same uv run poe check runs in GitHub Actions, so even Copilot-authored PRs must pass the human bar. |
| 05 | Open the store | /ship-it rolls the orchestrator to AKS behind a public LB with Workload Identity + CSI-mounted token, and the 8 specialist/MCP services to ACA with scale-to-zero. GitHub Actions OIDC re-runs the same pipeline on every main. |
⚠️ Don't confuse the two layers:
| Requirements | /requirements-analyst | specs/*.md only — refuses to write code | .github/agents/requirements-analyst.agent.md |
| MCP impl | /mcp-builder | src/mcp_servers/* (one server per turn) | .github/agents/mcp-builder.agent.md |
| Agent impl | /agent-builder | src/agents/<specialist>/* (one specialist per turn) | .github/agents/agent-builder.agent.md |
| Orchestration | /orchestrator-architect | src/agents/orchestrator/*, src/shared/*, docker-compose.yml | .github/agents/orchestrator-architect.agent.md |
| Tests | /test-author | tests/** only — never edits src/ | .github/agents/test-author.agent.md |
| Deploy | /deploy-engineer | infra/**, .github/workflows/** | .github/agents/deploy-engineer.agent.md |
Shared, agent-agnostic knowledge lives in .github/skills/ — every coding agent declares which skills it must consult before writing code.
Workflow prompts in .github/prompts/:
Hard rule (see AGENTS.md §1.1): for every code change, invoke the right /<agent> from the table above. Each agent carries the tools, skills, and refusal rules needed for its slice of the repo.
| 01 | Environment Setup | — | Azure subscription, AKS cluster, ACA env, ACR, Key Vault, Workload Identity, then install the 6 Copilot Custom Agents |
| 02 | Agent Creation | /requirements-analyst → /mcp-builder ×4 → /agent-builder ×4 → /orchestrator-architect | The five ZavaShop application agents in Python with MAF + Copilot SDK |
| 03 | Multi-Agent Orchestration & Config | /requirements-analyst → /spec-to-code → /orchestrator-architect | MAF Workflow, A2A wiring, MCP tools, Key Vault hydration, Docker Compose |
| 04 | Testing | /test-author (unit + MCP + integration + evals) → remote GitHub Copilot Coding Agent PR loop | Full test pyramid; assign GitHub-side Copilot to a failing-eval issue |
| 05 | Deployment & Run | /deploy-engineer + /ship-it | Helm for AKS, Bicep for ACA, OIDC-federated CD, Day-2 partial roll |
Each lab opens with its own ZavaShop story beat and a curated Microsoft Learn knowledge points list — read those first to anchor the operations in concepts.
The Learn references are grouped by the concern they answer. Every link is also embedded inside the lab that uses it.
MIT