Inventory Planning Fabric: replace the retiring visual workflow with a hosted Agent Framework assistant (Challenge 5)

.devcontainer/03-azure-01-04-ai-02-inventory-planning-fabric/devcontainer.json

@@ -1,15 +1,74 @@
 {
+  // Inventory Planning Fabric Hack — GitHub Codespaces / VS Code Dev Containers.
+  // The hack is browser-based (Fabric + Foundry portals). This container is an OPTIONAL
+  // alternative to Azure Cloud Shell for the Challenge 5 hosted-assistant deployment.
+  // It mirrors Cloud Shell: PowerShell 7, Azure CLI, azd and Python 3.12. No Docker is needed
+  // (the hosted agent builds remotely in Foundry) and no GitHub Copilot licence is assumed.
   "name": "Azure / AI / Inventory Planning Fabric",
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
-  "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/microhack,type=bind,consistency=cached",
-  "workspaceFolder": "/workspaces/microhack/03-Azure/01-04-AI/02_Inventory_Planning_Fabric",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12-bookworm",
+
+  "features": {
+    "ghcr.io/devcontainers/features/azure-cli:1": {
+      "version": "latest"
+    },
+    "ghcr.io/azure/azure-dev/azd:latest": {},
+    "ghcr.io/devcontainers/features/powershell:1": {
+      "version": "latest"
+    }
+  },
+
   "customizations": {
     "vscode": {
+      "extensions": [
+        "ms-vscode.powershell"
+      ],
       "settings": {
-        "terminal.integrated.defaultProfile.linux": "bash"
+        // Same shell as Cloud Shell, so the challenge commands work unchanged.
+        "terminal.integrated.defaultProfile.linux": "pwsh",
+        // Lab accounts have no GitHub Copilot licence: hide the built-in AI chat features.
+        "chat.disableAIFeatures": true,
+        // Hide facilitator/authoring folders from attendees (container only).
+        // VS Code defaults are repeated because this object replaces them.
+        "files.exclude": {
+          "**/.git": true,
+          "**/.svn": true,
+          "**/.hg": true,
+          "**/.DS_Store": true,
+          "**/Thumbs.db": true,
+          "**/__pycache__": true,
+          "labautomation": true,
+          ".github": true,
+          "docs": true,
+          "dev": true,
+          "archive": true,
+          "tests": true,
+          ".devcontainer": true
+        },
+        // Open Markdown (README, challenges) rendered by default.
+        "workbench.editorAssociations": {
+          "*.md": "vscode.markdown.preview.editor"
+        }
       }
     }
   },
+
+  "postAttachCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/welcome.sh",
+
   "remoteUser": "vscode",
-  "postAttachCommand": "bash /workspaces/microhack/.devcontainer/welcome.sh"
-}
+
+  // Keep the deployment tooling venv on a container volume: Docker Desktop (Windows/macOS)
+  // bind mounts can't create Python venvs ("ensurepip ... returned non-zero exit status 1").
+  "mounts": [
+    "source=inv-fabric-venv-tools-${devcontainerId},target=/workspaces/${localWorkspaceFolderBasename}/03-Azure/01-04-AI/02_Inventory_Planning_Fabric/orchestrator/.venv-tools,type=volume"
+  ],
+  // New volumes are root-owned; hand this one to the vscode user.
+  "postCreateCommand": "sudo chown vscode:vscode /workspaces/${localWorkspaceFolderBasename}/03-Azure/01-04-AI/02_Inventory_Planning_Fabric/orchestrator/.venv-tools",
+
+  // ${localWorkspaceFolderBasename} = the repo/fork name, so this works for Codespaces on
+  // microsoft/MicroHack, for uniquely named forks, and for local clones.
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}/03-Azure/01-04-AI/02_Inventory_Planning_Fabric",
+
+  "remoteEnv": {
+    "hackFolder": "/workspaces/${localWorkspaceFolderBasename}/03-Azure/01-04-AI/02_Inventory_Planning_Fabric"
+  }
+}

03-Azure/01-04-AI/02_Inventory_Planning_Fabric/.gitignore

@@ -13,6 +13,7 @@ labautomation/lab-defaults.local.json
 Thumbs.db
 desktop.ini
 .DS_Store
+__pycache__/
 
 # Diagram build artifacts — only the rendered PNG (images/architecture.png) is committed
 images/render/

03-Azure/01-04-AI/02_Inventory_Planning_Fabric/README.md

@@ -11,7 +11,7 @@
 
 This MicroHack teaches you to build **AI agents that reason over governed enterprise data and take human-approved actions**. You will use **Microsoft Foundry Agent Service** to create three agents that form a closed planning loop for inventory management: sensing real-world demand signals, optimising stock positions, and submitting replenishment orders with a human-in-the-loop approval gate.
 
-No coding background in AI is required. All agents in this MicroHack are built as **prompt agents** directly in the Foundry portal — no application code to write or maintain. You will spend your time on the *reasoning* layer, not the infrastructure layer.
+No coding background in AI is required. The three core agents are built as **prompt agents** directly in the Foundry portal. In the optional final challenge, participants deploy the supplied **hosted assistant from GitHub through browser-based Azure Cloud Shell**; they do not write application code or install Python/azd on their computer. You will spend your time on the *reasoning* layer, not the infrastructure layer.
 
 The star of the hack is the **Fabric Data Agent**: a published Microsoft Fabric agent that turns plain-English questions into governed queries (NL2SQL) over an inventory Lakehouse. Every Foundry agent you build calls it as a tool — so you get trustworthy, governed answers without writing a line of SQL.
 
@@ -20,14 +20,15 @@ The star of the hack is the **Fabric Data Agent**: a published Microsoft Fabric
 
 ## What you'll build
 
-Three Foundry prompt agents that form one closed planning loop — every one of them calling **your** **Fabric Data Agent** for governed answers:
+Your own **Fabric Data Agent** (built in **Challenge 1**) plus three Foundry prompt agents that form one closed planning loop — every one of them calling **your** **Fabric Data Agent** for governed answers:
 
-| # | Agent | Tools it uses | What it produces |
-|---|-------|---------------|------------------|
-| 1 | **Demand Sensing** | Fabric Data Agent *(+ optional Web Search)* | A demand-exposure assessment (adequate / at risk / critically exposed) |
-| 2 | **Inventory Optimisation** | Fabric Data Agent | A reorder recommendation table with CRITICAL items flagged |
-| 3 | **Replenishment Action** | Fabric Data Agent + human approval gate | A **human-approved** purchase order (simulated submit) |
-| ⭐ *(stretch)* | **Workflow** | The three agents chained in a Foundry Workflow | The whole loop, driven from a single prompt |
+| Challenge | Agent | Tools it uses | What it produces |
+|-----------|-------|---------------|------------------|
+| 1 | **Fabric Data Agent** (the governed data layer) | Inventory Lakehouse, published Data Agent | Plain-English answers over your own data — the foundation for everything else |
+| 2 | **Demand Sensing** | Fabric Data Agent *(+ optional Web Search)* | A demand-exposure assessment (adequate / at risk / critically exposed) |
+| 3 | **Inventory Optimisation** | Fabric Data Agent | A reorder recommendation table with CRITICAL items flagged |
+| 4 | **Replenishment Action** | Fabric Data Agent + human approval gate | A **human-approved** purchase order (simulated submit) |
+| 5 ⭐ *(stretch)* | **Hosted Inventory Planning Assistant** | Agent Framework chains the three specialists; application-controlled approval | The whole loop from one prompt, publishable to Teams/M365 |
 
 ![Agentic Inventory Planning — the sense → reason → act loop across Foundry Agents, a human-approved action, and the governed Fabric data layer](images/architecture.png)
 
@@ -52,15 +53,19 @@ The architecture uses two key Foundry tools:
 | **Web Search** *(optional)* | Grounds the demand signal in live external information (news, market trends, competitor activity) |
 
 > [!NOTE]
-> The Fabric Data Agent and Web Search are in Public Preview. They are stable enough for a hack environment and are the tools underlying the production-bound architecture described in the slide deck.
+> You connect your published Fabric Data Agent to your agents through **Fabric IQ (OneLake Catalog)**.
+> The Foundry visual workflow designer retires on **1 December 2026**, so Challenge 5
+> uses a small [hosted assistant](orchestrator/README.md) instead. The earlier
+> visual-workflow exercise is kept for reference in the repository:
+> [archived workflow exercise](archive/visual-workflow-exercise.md).
 
 ## Objectives
 
 After completing this MicroHack you will be able to:
 
 - Create and configure **Foundry prompt agents** in the portal with specific tools and instructions.
 - Ground an agent's reasoning in **live web signals** using the Web Search tool.
-- Connect a Foundry agent to a **governed Fabric data source** via the Fabric Data Agent tool, without writing any SQL or understanding Fabric internals.
+- Connect a Foundry agent to a **governed Fabric Data Agent** via Fabric IQ, without writing SQL or understanding Fabric internals.
 - Implement a **human-in-the-loop** approval pattern inside an agent conversation.
 - Use **agent tracing** in Foundry to inspect every model call and tool invocation — understanding *why* the agent made a decision.
 - Articulate the **sense → plan → approve → act** agentic pattern and identify where it applies in your own organisation.
@@ -74,21 +79,39 @@ Complete the following before the hack session:
 - A modern browser (Chrome, Edge, or Firefox).
 - Access to the **Microsoft Foundry portal** at [ai.azure.com](https://ai.azure.com) — your facilitator will share credentials on the day.
 - No local software installation required — all participant work is browser-based.
+- For the optional Challenge 5: a private browser window (Edge InPrivate or Chrome Incognito)
+  and the lab account you were given. Everything runs in your browser — Azure Cloud Shell,
+  Teams for the web and Microsoft 365 Copilot for the web.
+- *Optional alternative for Challenge 5:* if you prefer VS Code, you can deploy from a local
+  **VS Code Dev Container** (Docker, no GitHub account needed) or **GitHub Codespaces** (needs
+  your **personal** GitHub account — the lab provides no GitHub account or GitHub Copilot
+  licence, and none is needed), using the configuration **Azure / AI / Inventory Planning
+  Fabric**. See the [deployment guide](orchestrator/README.md#option-b-github-codespaces-or-a-local-dev-container).
+
+> [!TIP]
+> **Portal language:** the steps and screenshots use English. Before starting, set
+> the Fabric portal display language to **English** under **Settings → General →
+> Language**, then refresh (labels can vary by portal version). Do the same in
+> Foundry if needed. Translated item names can be surprising: a *Lakehouse* is a
+> Fabric data item, not a different service. Keep resource names such as
+> `InventoryLakehouse` unchanged. You can restore your preferred language afterward.
 
 > [!NOTE]
 > Your Foundry project, gpt-5.4-mini model deployment, and your **own Fabric capacity** are provisioned for you by the lab automation. In **Challenge 1** you stand up your own Fabric workspace and publish your **Fabric Data Agent** by running one notebook (Run All). You'll be handed a project endpoint and your capacity name at the start of the hack. Web Search is optional and may need project-level enablement.
 
 > [!TIP]
-> **You're ready to start when**, in the Foundry portal, you can: (1) see `gpt-5.4-mini` in your **model deployments** with status *Succeeded*, and (2) add the **Fabric Data Agent** tool to an agent and create the `inventory-hack-agent` connection (you do this in Challenge 2). If `gpt-5.4-mini` is missing, flag your facilitator before starting.
+> **You're ready to start when**, in Foundry, you can: (1) see the dashboard model deployment with status *Succeeded*, and (2) use **Fabric IQ (OneLake Catalog)** to connect your published `inventory-hack-agent` (Challenge 2). Confirm OAuth consent and permissions as the participant, not just the facilitator.
 
 > [!IMPORTANT]
 > **Facilitators:** there is **no shared Fabric backend** — [`labautomation/deploy-lab.ps1`](labautomation/deploy-lab.ps1) provisions each attendee's Foundry project, model, and their **own Fabric capacity**, and each attendee builds their workspace + Data Agent in Challenge 1. Ensure: the platform service principal has **Owner** on the attendee resource groups; [`lab-defaults.json`](labautomation/lab-defaults.json) sets **`groups: ["M365-E5-Users"]`** so attendees get a Power BI Pro license for the Fabric portal; the **lab tenant has Fabric enabled** (tenant-admin setting *“Users can create Fabric items / workspaces”* — **not** settable via `lab-defaults.json`); and the subscription has **Fabric F-SKU quota** (F4 = 4 CU; ~128 attendees per 512-CU subscription). See [`labautomation/README.md`](labautomation/README.md).
 
 > [!NOTE]
 > **Facilitator guidance (from run feedback):**
 > - **Audience & expectations:** pitch this at a **no-code / low-code** audience (e.g. technical decision-makers, level 150–200) and set that expectation in the invite — it is *not* a hardcore-developer hack.
-> - **Token throughput:** the model deploys at **200K TPM** and the lab packs **5 attendees per subscription**. If attendees hit rate limits, prefer **one subscription per attendee** (or raise the deployment's TPM). See [`labautomation/README.md`](labautomation/README.md).
-> - **Fabric capacity:** the per-attendee **F4** default covers this hack comfortably, including capacity-heavy steps (parquet-load contention, intermittent Data Agent calls). To cut cost, drop to **F2** (`-FabricSkuName F2`, or **resize live** — F SKUs support on-demand resize, no redeploy) if attendees aren't hitting throttling, and lower `estimatedDailyCostsUsd` to match (each SKU step roughly doubles the Fabric cost). For the **ontology** feature, size up further (F8+) for that path.
+> - **Token throughput:** the default model deployment requests capacity **200** and the platform packs **5 attendees per subscription**. These are starting values, not a throughput guarantee. Diagnose TPM/RPM and service-capacity throttling separately; adding subscriptions does not increase an unchanged deployment's limit. See the [quota and rehearsal runbook](labautomation/README.md#workshop-readiness-and-rehearsal).
+> - **Fabric capacity:** **F4 remains the default**, but must be rehearsed. An event reported stalled table loads on F4, and we reproduced it on a fresh F4: the fourth file hung and cancelling the job fixed it. The reported cause was the concurrent Spark core limit, not CU consumption (loading used about 1% of an F4): finished **TableLoad** jobs kept showing **In progress** and held cores. Cancelling them in the Monitor hub freed the cores, so try that before resizing to **F8**. Treat F8 as a validation candidate, not a universal requirement. F2 is a lower-cost experiment only after measurement. If changing the default, update daily costs and subscription capacity calculations together.
+> - **Optional previews:** schema-object descriptions require the preview runtime; ontology also depends on tenant enablement and current capacity requirements. Neither is necessary for the core lab. See the optional ideas in [Challenge 5](challenges/challenge-05.md).
+> - **Fabric IQ and Challenge 5:** Fabric IQ is in preview, so rehearse the exact versions and tenant before every event. The earlier Foundry Fabric Data Agent connector retires on **6 November 2026**. Challenge 5 needs a short preflight (publishing, licenses, private-browser sign-in): see [Challenge 5 preflight](labautomation/README.md#challenge-5-preflight).
 
 ### Challenge overview
 
@@ -98,7 +121,7 @@ Complete the following before the hack session:
 | [Challenge 2](challenges/challenge-02.md) | Demand Sensing Agent | 60 min | Build an agent that combines web signals with governed data |
 | [Challenge 3](challenges/challenge-03.md) | Inventory Optimisation Agent | 60 min | Reasoning over stock positions + reading agent traces |
 | [Challenge 4](challenges/challenge-04.md) | Replenishment + Human-in-the-Loop | 75 min | Close the loop with an approval gate and end-to-end trace |
-| [Challenge 5](challenges/challenge-05.md) *(stretch)* | Orchestrate the Loop | 45 min | Multi-agent orchestration with a Foundry Workflow — optional, for fast finishers |
+| [Challenge 5](challenges/challenge-05.md) *(stretch)* | Run and Publish the Hosted Assistant | 45–60 min | Agent Framework orchestration, explicit approval, Teams/M365 personal publishing; facilitator setup required |
 
 ### Agenda
 
@@ -112,9 +135,23 @@ Complete the following before the hack session:
 
 ## Contributors
 
-| Name | Role |
-|------|------|
-| Digvijay Chauhan | Author & maintainer |
+| Name | Organization | Role |
+|------|--------------|------|
+| Digvijay Chauhan | Microsoft | Author & maintainer |
+| Sorin Peste | Microsoft | **Contributor** — manual Lakehouse and Data Agent option; **Reviewer** |
+| Martin Kruse | PRODYNA | **Contributor** — setup script update (MCP 2.x) and model image fix; **Reviewer** |
+| Peter Williams | Microsoft | **Reviewer** |
+| Erik Andersson | Microsoft | **Reviewer** |
+| Katarina Svedman | Microsoft | **Reviewer** |
+| Imran Diva | Microsoft | **Reviewer** |
+| Lotta Åhag | Microsoft | **Reviewer** |
+| Asif Mithawala | Microsoft | **Reviewer** |
+| Jan Kruse | Microsoft | **Reviewer** |
+| Christian Galla | PRODYNA | **Reviewer** |
+| Nico Möller | Microsoft | **Reviewer** |
+| John Håkansson | Microsoft | **Reviewer** |
+| Marco Weber | Microsoft | **Reviewer** |
+| Diana Dreher | Microsoft | **Reviewer** |
 
 <!-- Add your name here when you contribute -->