Skip to content

microsoft/AKS-Lab-GitHubCopilot

BranchesTags

Repository files navigation

ZavaShop on AKS + ACA — built by GitHub Copilot Multi Custom Coding Agents

bg

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 + Microsoft Entra ID + Microsoft Defender for Cloud.

This repo now includes the packaged ZavaShop stock-out response fleet: five MAF agents, four FastMCP servers, focused tests and evals, Docker packaging, ACA Bicep, AKS Helm, and GitHub Actions deployment gates.

🧭 What makes this lab different

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.

       ┌─────────────────────── GitHub Copilot Multi Custom Agents ───────────────────────┐
       │                                                                                  │
 Issue ─►  /requirements-analyst  ─►  specs/<slug>.md                                      │
                  │                                                                       │
                  ▼                                                                       │
          /mcp-builder  ───────►  src/mcp_servers/*                                        │
          /agent-builder  ─────►  src/agents/<specialist>/*                                │
          /orchestrator-architect ─► src/agents/orchestrator, src/shared, docker-compose   │
                  │                                                                       │
                  ▼                                                                       │
          /test-author  ───────►  tests/** (unit · integration · evals)                    │
                  │                                                                       │
                  ▼                                                                       │
          /deploy-engineer  ───►  infra/** + .github/workflows/** + ACR/ACA/AKS rollout    │
       └──────────────────────────────────────────────────────────────────────────────────┘

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.

🚀 Fast Deploy Track

The full lab path teaches every engineering step. For workshops and demos, use the fast deploy track: let the workflow prompts drive the custom-agent handoffs, generate the application code and deployment artifacts as one packaged application, then deploy the built images through a single /ship-it flow.

Fast path:

  1. Complete Lab 01 once to create the Azure foundation.
  2. Run /feature-from-issue with the ZavaShop stock-out scenario. Follow its handoffs to the owning custom agents instead of manually designing each coding prompt.
  3. Run /ship-it to build all service images, deploy ACA specialists/MCP servers, deploy the AKS orchestrator, smoke-test /healthz + /readyz, and run evals.

This reduces the application coding portion from open-ended manual prompting into a guided workflow while preserving the same generated structure under src/, tests/, and infra/. The resulting deployment must still satisfy the AKS landing zone, Entra ID, and Defender for Cloud gates described in Labs 01 and 05.

Current packaged fleet

The fast path produces these runtime services:

Layer Services Runtime Ports and probes
Orchestration orchestrator AKS + Helm Uvicorn on 8000; /healthz, /readyz, /plan, /invoke
Specialists inventory, supplier, logistics, pricing Azure Container Apps Uvicorn on 8000; /healthz, /readyz, /invoke
MCP tools inventory-mcp, supplier-mcp, shipping-mcp, pricing-mcp Azure Container Apps FastMCP on 8080; /healthz, /readyz, /mcp

Images are tagged with the short git SHA and built through ACR Tasks for linux/amd64. Lab 05 keeps ACA specialists and MCP servers at minReplicas=1 so workshop smoke tests and live evals are reliable; production landing zones can revisit private ingress and scale-to-zero after DNS, network, and cold-start budgets are designed.

🛍 The Story: ZavaShop

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:

Application Agent Responsibility
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 and MCP servers run on Azure Container Apps. In the lab deployment they are exposed by ACA HTTPS FQDNs with minReplicas=1 for repeatable smoke/eval runs; the same Bicep module can be adjusted for private ingress and scale-to-zero in a production landing zone. Each specialist reaches its backend capability through a dedicated MCP server so the LLM never owns business state.

┌──────────────────────────────────────────────────────────────────────────────┐
│ Security + identity guardrails                                               │
│                                                                              │
│  Microsoft Entra ID + Azure RBAC                                             │
│  - GitHub Actions OIDC -> UAMI                                               │
│  - AKS Workload Identity / ACA managed identity                              │
│  - Key Vault GITHUB-TOKEN -> CSI on AKS / secretref on ACA                   │
│                                                                              │
│  Microsoft Defender for Cloud                                                │
│  - AKS Defender monitoring                                                   │
│  - Defender Containers + KeyVaults plans must be Standard                    │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ AKS                                                                          │
│  OrchestratorAgent (MAF Workflow + GitHub Copilot SDK)                       │
│  ServiceAccount: orchestrator-sa + azure.workload.identity/use=true          │
│  Routes: /healthz, /readyz, /plan, /invoke                                   │
└─────────────────────────────────────┬────────────────────────────────────────┘
                                      │ A2A / HTTP (/invoke)
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ Azure Container Apps specialists                                             │
│  inventory  | supplier  | logistics  | pricing                               │
│  Routes: /healthz, /readyz, /invoke                                          │
└─────────────────────────────────────┬────────────────────────────────────────┘
                                      │ Copilot SDK remote MCP over HTTP
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ Azure Container Apps MCP servers                                             │
│  inventory-mcp | supplier-mcp | shipping-mcp | pricing-mcp                  │
│  Routes: /healthz, /readyz, /mcp                                             │
└──────────────────────────────────────────────────────────────────────────────┘

Entra ID and Defender for Cloud in the architecture

These controls sit around the fleet rather than inside the retail business logic. They are enforced by Lab 01 infrastructure and re-checked by the /ship-it and GitHub Actions deployment path before workloads roll forward.

Control Where it appears What it protects
Microsoft Entra ID for AKS The deployment preflight checks that the AKS aadProfile exists before deploying. Human cluster access is expected to use Entra ID and Azure RBAC, not admin kubeconfig. Prevents unmanaged local cluster credentials from becoming the normal operator path.
GitHub Actions OIDC The workflow grants id-token: write and uses azure/login@v2 with AZURE_CLIENT_ID, tenant, and subscription values. Lets CI/CD authenticate to Azure without storing a client secret in GitHub.
Workload Identity and UAMI The AKS orchestrator uses orchestrator-sa with the Workload Identity label; ACA apps use the same user-assigned managed identity pattern. Gives workloads Azure identity without embedding passwords or service principal secrets.
Key Vault secret delivery AKS reads GITHUB-TOKEN through Secrets Store CSI; ACA reads it through Key Vault secretref. Keeps Copilot credentials out of Helm values, Bicep parameters, images, and source control.
Defender for Cloud The deployment preflight requires AKS Defender security monitoring and Standard tiers for Containers and KeyVaults. Blocks rollout when container and secret surfaces are not covered by the lab security baseline.
Azure Policy gate The deployment preflight checks the AKS Azure Policy add-on. Keeps the cluster aligned with the AKS landing-zone baseline before application rollout.

Story arc across the labs

The five labs are five chapters of one story — ZavaShop going from a blank Azure subscription to a live, observable retail control plane:

Lab Chapter What changes in ZavaShop's world
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 GitHubCopilotAgent wrapped by the shared _RunnableAgent adapter. Inventory, Supplier, Logistics, Pricing, and the Orchestrator are born — every external system kept behind an MCP server so the LLM never owns business state. Fast-track users can drive this through /feature-from-issue.
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 Unit, integration, and live eval checks 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 Workload Identity + CSI-mounted token, and the 8 specialist/MCP services to ACA with Key Vault secretref, external lab FQDNs, and minReplicas=1 for smoke reliability. GitHub Actions OIDC re-runs the same pipeline on every main, with AKS landing zone, Entra ID, Azure Policy, monitoring, and Defender for Cloud checks.

⚠️ Don't confuse the two layers:

  • Application agents (the table above) — the runtime ZavaShop fleet you deploy.
  • GitHub Copilot Custom Coding Agents (/requirements-analyst etc.) — the dev-time team that writes the application agents for you.

👥 Meet the GitHub Copilot Custom Coding Agents

Phase Coding Agent Owns File
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/:

  • /feature-from-issue — issue → spec → code → tests → PR → deploy.
  • /spec-to-code — drive an existing spec through code + tests.
  • /ship-it — quality gate → landing-zone preflight → ACR Tasks build → ACA/AKS rollout → /healthz + /readyz smoke → evals.

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.

🗺 Lab Index

# Lab Coding agents you'll drive What you build
01 Environment Setup — Azure subscription, landing-zone-aware AKS cluster, ACA env, ACR, Key Vault, Entra ID/RBAC, Defender for Cloud, 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 Packaged app images, Helm for AKS, Bicep for ACA, OIDC-federated CD, readiness probes, landing zone security gates, 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.

📚 Microsoft Learn knowledge map

The Learn references are grouped by the concern they answer. Every link is also embedded inside the lab that uses it.

Platform foundations (Lab 01)

Identity & secret-less auth (Labs 01, 03, 05)

Agents, MCP & the Copilot SDK (Labs 02, 03)

Testing & quality gate (Lab 04)

Deployment (Lab 05)

✅ Prerequisites

  • Azure subscription with Owner on a resource group
  • Azure CLI ≥ 2.65, kubectl, helm, docker, uv (or pip)
  • Python 3.11+
  • A GitHub Copilot subscription (Individual / Business / Enterprise)
  • VS Code with GitHub Copilot + GitHub Copilot Chat extensions
    • After cloning, run Developer: Reload Window so VS Code discovers .github/agents/*.agent.md and the six ZavaShop agents appear in the /-invocation picker.

📚 How to use Copilot in this lab

  1. Read AGENTS.md — the house rules every coding agent obeys.
  2. Open Copilot Chat. Type / and confirm you see requirements-analyst, mcp-builder, agent-builder, orchestrator-architect, test-author, deploy-engineer.
  3. Start every task by invoking the right coding agent, not by free-form prompting: 
    /requirements-analyst
We need a returns-handling pipeline. Goal, contracts, eval scenarios.
  4. When an agent finishes, it ends with a handoff line naming the next /<agent> to invoke. Follow it.
  5. For multi-step changes, run a workflow prompt: /feature-from-issue, /spec-to-code, or /ship-it.

📂 Repository Layout

.
├── AGENTS.md                        # House rules — read this first
├── pyproject.toml                    # uv/ruff/pyright/pytest/poe configuration
├── .dockerignore                     # Keeps secrets/caches out of ACR build context
├── .github/
│   ├── copilot-instructions.md      # Always-on Copilot context
│   ├── agents/                      # 6 Copilot Custom Coding Agents (*.agent.md)
│   ├── skills/                      # Shared knowledge consulted by the agents
│   ├── prompts/                     # Workflow prompts (/feature-from-issue, /spec-to-code, /ship-it)
│   ├── instructions/                # Scoped *.instructions.md (python, k8s, agent-framework)
│   └── workflows/                   # CI/CD (authored by /deploy-engineer)
├── labs/                            # The 5 step-by-step labs
├── specs/                           # Authored by /requirements-analyst
├── src/
│   ├── Dockerfile.base               # Shared base image for app agents
│   ├── agents/                      # ZavaShop application agents (one folder each)
│   │   ├── orchestrator/             # AKS orchestrator: /plan + /invoke
│   │   ├── inventory/                # ACA specialist: stock-out response
│   │   ├── supplier/                 # ACA specialist: PO drafting
│   │   ├── logistics/                # ACA specialist: shipment planning
│   │   └── pricing/                  # ACA specialist: price recommendation
│   ├── mcp_servers/                 # FastMCP tool servers on /mcp
│   │   ├── inventory/
│   │   ├── supplier/
│   │   ├── shipping/
│   │   └── pricing/
│   └── shared/                      # Settings, telemetry, Copilot client, A2A server factory
├── infra/
│   ├── aks/                         # Helm chart + WIF docs (authored by /deploy-engineer)
│   └── aca/                         # ACA Bicep module + deploy.sh + FQDN export
└── tests/                           # Unit · integration · live evals (authored by /test-author)

License

MIT

About

ZavaShop multi-agent retail demo on AKS + ACA. Specs, MCP servers, agents, tests, Bicep/Helm and CI are all authored by 6 GitHub Copilot Custom Coding Agents using Microsoft Agent Framework + Copilot SDK.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Security policy

Security policy
Activity
Custom properties

Stars

3 stars

Watchers

0 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages