docs: update wizard flow and known issues for Foundry Toolkit v1.2.1

- Update KNOWN_ISSUES.md: date to 2026-05-18, tag Foundry Toolkit v1.2.1,
  fix KI-001/KI-002 package versions (1.0.0 -> 1.0.1), add upstream
  tracking table for KI-002, add KI-005 (Teams/M365 BotId/ClientId
  mismatch, vscode-ai-toolkit#381), add KI-006 (no multi-agent wizard
  template in AITK v1.2.1), expand References with 3 GitHub issue links

- Update lab01/README.md: scaffold steps reflect new 9-step wizard flow
  (language -> Response API -> Basic-Agent Framework -> model -> workspace
  -> name), replacing stale framework-selection step

- Update lab01/docs/03-create-hosted-agent.md: reorder wizard steps to
  match v1.2.1 flow; add Step 3 (API type) and Step 4 (template) with
  comparison tables; renumber Steps 5-8 and sub-sections 8.1-8.4;
  update Mermaid diagram to 7-node flow

- Update lab02/docs/02-scaffold-multi-agent.md: same wizard flow update;
  Step 4 template includes KI-006 callout (no multi-agent template);
  renumber Steps 5-8, sub-sections 8.1-8.4; update Mermaid diagram

Author: ShivamGoyal03

KNOWN_ISSUES.md

@@ -2,7 +2,7 @@
 
 This document tracks known issues with the current repository state.
 
-> Last updated: 2026-04-15. Tested against Python 3.13 / Windows in `.venv_ga_test`.
+> Last updated: 2026-05-18. Tested against Python 3.13 / Windows in `.venv_ga_test`. Foundry Toolkit v1.2.1.
 
 ---
 
@@ -14,26 +14,26 @@ This document tracks known issues with the current repository state.
 | `agent-framework-core` | `1.0.0rc3` |
 | `azure-ai-agentserver-agentframework` | `1.0.0b16` |
 | `azure-ai-agentserver-core` | `1.0.0b16` |
-| `agent-dev-cli` | `--pre` *(fixed — see KI-003)* |
+| `agent-dev-cli` | `--pre` *(fixed - see KI-003)* |
 
 ---
 
-## KI-001 — GA 1.0.0 Upgrade Blocked: `agent-framework-azure-ai` Removed
+## KI-001 - GA 1.0.0 Upgrade Blocked: `agent-framework-azure-ai` Removed
 
 **Status:** Open | **Severity:** 🔴 High | **Type:** Breaking
 
 ### Description
 
 The `agent-framework-azure-ai` package (pinned at `1.0.0rc3`) was **removed/deprecated**
-in the GA release (1.0.0, released 2026-04-02). It is replaced by:
+in the GA release (1.0.x; latest GA 1.0.1, released 2026-04-10). It is replaced by:
 
-- `agent-framework-foundry==1.0.0` — Foundry-hosted agent pattern
-- `agent-framework-openai==1.0.0` — OpenAI-backed agent pattern
+- `agent-framework-foundry==1.0.1` - Foundry-hosted agent pattern
+- `agent-framework-openai==1.0.1` - OpenAI-backed agent pattern
 
 All three `main.py` files import `AzureAIAgentClient` from `agent_framework.azure`, which
 raises `ImportError` under GA packages. The `agent_framework.azure` namespace still exists
 in GA but now contains only Azure Functions classes (`DurableAIAgent`,
-`AzureAISearchContextProvider`, `CosmosHistoryProvider`) — not Foundry agents.
+`AzureAISearchContextProvider`, `CosmosHistoryProvider`) - not Foundry agents.
 
 ### Confirmed error (`.venv_ga_test`)
 
@@ -52,38 +52,47 @@ ImportError: cannot import name 'AzureAIAgentClient' from 'agent_framework.azure
 
 ---
 
-## KI-002 — `azure-ai-agentserver` Incompatible with GA `agent-framework-core`
+## KI-002 - `azure-ai-agentserver` Incompatible with GA `agent-framework-core`
 
-**Status:** Open | **Severity:** 🔴 High | **Type:** Breaking (blocked on upstream)
+**Status:** Open (fix pending SDK release) | **Severity:** 🔴 High | **Type:** Breaking (blocked on upstream)
 
 ### Description
 
 `azure-ai-agentserver-agentframework==1.0.0b17` (latest) hard-pins
-`agent-framework-core<=1.0.0rc3`. Installing it alongside `agent-framework-core==1.0.0` (GA)
+`agent-framework-core<=1.0.0rc3`. Installing it alongside `agent-framework-core==1.0.1` (latest GA)
 forces pip to **downgrade** `agent-framework-core` back to `rc3`, which then breaks
-`agent-framework-foundry==1.0.0` and `agent-framework-openai==1.0.0`.
+`agent-framework-foundry==1.0.1` and `agent-framework-openai==1.0.1`.
 
 The `from azure.ai.agentserver.agentframework import from_agent_framework` call used by all
 agents to bind the HTTP server is therefore also blocked.
 
+### Upstream tracking
+
+| Repo | Issue | Status |
+|------|-------|--------|
+| microsoft/agent-framework | [#5273](https://github.com/microsoft/agent-framework/issues/5273) | ✅ Closed 2026-04-21 - fix submitted to azure-sdk-for-python |
+| Azure/azure-sdk-for-python | [#46324](https://github.com/Azure/azure-sdk-for-python/issues/46324) | 🔴 Open - new `azure-ai-agentserver-agentframework` release pending |
+
+Workshop stays pinned at rc3 until azure-sdk-for-python#46324 ships.
+
 ### Confirmed dependency conflict (`.venv_ga_test`)
 
 ```
 ERROR: pip's dependency resolver does not currently take into account all the packages
 that are installed. This behaviour is the source of the following dependency conflicts.
-agent-framework-foundry 1.0.0 requires agent-framework-core<2,>=1.0.0,
+agent-framework-foundry 1.0.1 requires agent-framework-core<2,>=1.0.1,
   but you have agent-framework-core 1.0.0rc3 which is incompatible.
-agent-framework-openai 1.0.0 requires agent-framework-core<2,>=1.0.0,
+agent-framework-openai 1.0.1 requires agent-framework-core<2,>=1.0.1,
   but you have agent-framework-core 1.0.0rc3 which is incompatible.
 ```
 
 ### Files affected
 
-All three `main.py` files — both the top-level import and the in-function import in `main()`.
+All three `main.py` files - both the top-level import and the in-function import in `main()`.
 
 ---
 
-## KI-003 — `agent-dev-cli --pre` Flag No Longer Needed
+## KI-003 - `agent-dev-cli --pre` Flag No Longer Needed
 
 **Status:** ✅ Fixed (non-breaking) | **Severity:** 🟢 Low
 
@@ -97,7 +106,7 @@ pre-release CLI. Since GA 1.0.0 was released on 2026-04-02, the stable release o
 
 ---
 
-## KI-004 — Dockerfiles Use `python:3.14-slim` (Pre-release Base Image)
+## KI-004 - Dockerfiles Use `python:3.14-slim` (Pre-release Base Image)
 
 **Status:** Open | **Severity:** 🟡 Low
 
@@ -114,7 +123,58 @@ For production deployments this should be pinned to a stable release (e.g., `pyt
 
 ---
 
+## KI-005 - Teams/M365 Publish Succeeds but Agent Unreachable (BotId/ClientId Mismatch)
+
+**Status:** Open | **Severity:** 🔴 High | **Type:** Integration bug | **Ref:** [vscode-ai-toolkit#381](https://github.com/microsoft/vscode-ai-toolkit/issues/381)
+
+### Description
+
+Publishing a Hosted Agent to Teams/M365 Copilot via Foundry Toolkit completes successfully but the agent is **not reachable** on those channel surfaces.
+
+Root cause: **Publish** (registers bot channel artifacts) and **Deploy** (starts live hosted runtime) are two separate operations. Without Deploy, no running backend exists behind the endpoint.
+
+Error observed when Bot Service attempts to route traffic:
+
+```
+Failed to publish agent BotId '<id>' does not match the application's default instance identity ClientId '<id>'.
+[Status: 400, Code: UserError]
+```
+
+Azure Bot Service sends Bot Framework JWTs (`iss=https://api.botframework.com`). The current Foundry gateway auth path does not fully accept this token shape in this configuration.
+
+**Deploy blocker:** Deploy Hosted Agent requires a local Docker build. No cloud-side build fallback is currently offered.
+
+### Workaround
+
+Test using the **web chat** channel in Azure Bot Service - this path works correctly. Teams/M365 channel integration is blocked until upstream auth and UX issues are resolved.
+
+---
+
+## KI-006 - No Multi-Agent Wizard Template in AITK v1.2.1
+
+**Status:** Open | **Severity:** 🟡 Medium | **Type:** Feature gap
+
+### Description
+
+The AITK wizard (Foundry Toolkit v1.2.1) provides the following templates under the **Response API** path:
+
+- Echo (Streaming)
+- Multi-Turn Chat
+- Note Taking
+- **Basic - Agent Framework** ← used in Lab 01
+
+There is no **Multi-Agent Workflow** template. Lab 02 uses the pre-built **`PersonalCareerCopilot/`** folder rather than a wizard-generated scaffold.
+
+### Workshop impact
+
+Learners cannot use the wizard to scaffold a new multi-agent project using MAF GA. Lab 02 proceeds using the pre-existing example code directly.
+
+---
+
 ## References
 
 - [agent-framework-core on PyPI](https://pypi.org/project/agent-framework-core/)
 - [agent-framework-foundry on PyPI](https://pypi.org/project/agent-framework-foundry/)
+- [microsoft/agent-framework#5273](https://github.com/microsoft/agent-framework/issues/5273) - agentserver incompatibility with MAF GA (closed)
+- [Azure/azure-sdk-for-python#46324](https://github.com/Azure/azure-sdk-for-python/issues/46324) - SDK fix pending (open)
+- [microsoft/vscode-ai-toolkit#381](https://github.com/microsoft/vscode-ai-toolkit/issues/381) - Teams/M365 publish + auth (open)

workshop/lab01-single-agent/README.md

@@ -59,12 +59,13 @@ Complete the tutorial modules before starting this lab:
 
 1. Open **Command Palette** (`Ctrl+Shift+P`).
 2. Run: **Microsoft Foundry: Create a New Hosted Agent**.
-3. Select **Microsoft Agent Framework**
-4. Select **Single Agent** template.
-5. Select **Python**.
+3. Select **Python** as the language.
+4. Select **Response API** as the API type.
+5. Select **Basic - Agent Framework** template.
 6. Select the model you deployed (e.g., `gpt-4.1-mini`).
-7. Save to the `workshop/lab01-single-agent/agent/` folder.
-8. Name it: `executive-summary-agent`.
+7. Select your Foundry workspace.
+8. Save to the `workshop/lab01-single-agent/agent/` folder.
+9. Name it: `executive-summary-agent`.
 
 A new VS Code window opens with the scaffold.
 

workshop/lab01-single-agent/docs/03-create-hosted-agent.md

@@ -9,15 +9,17 @@ In this module, you use the Microsoft Foundry extension to **scaffold a new [hos
 ```mermaid
 flowchart LR
     A["Command Palette:
-    Create Hosted Agent"] --> B["Choose Template:
-    Single Agent"]
-    B --> C["Choose Language:
+    Create Hosted Agent"] --> B["Choose Language:
     Python"]
-    C --> D["Select Model:
+    B --> C["Select API Type:
+    Response API ✓"]
+    C --> D["Select Template:
+    Basic - Agent Framework"]
+    D --> E["Select Model:
     gpt-4.1-mini"]
-    D --> E["Choose Folder +
+    E --> F["Workspace +
     Agent Name"]
-    E --> F["Scaffolded Project:
+    F --> G["Scaffolded Project:
     agent.yaml, main.py,
     Dockerfile, .env"]
 
@@ -26,7 +28,8 @@ flowchart LR
     style C fill:#7B68EE,color:#fff
     style D fill:#7B68EE,color:#fff
     style E fill:#7B68EE,color:#fff
-    style F fill:#27AE60,color:#fff
+    style F fill:#7B68EE,color:#fff
+    style G fill:#27AE60,color:#fff
 ```
 
 ---
@@ -41,30 +44,46 @@ flowchart LR
 
 ---
 
-## Step 2: Choose your template
+## Step 2: Choose programming language
 
-The wizard asks you to select a template. You'll see options like:
-
-| Template | Description | When to use |
-|----------|-------------|-------------|
-| **Single Agent** | One agent with its own model, instructions, and optional tools | This workshop (Lab 01) |
-| **Multi-Agent Workflow** | Multiple agents that collaborate in sequence | Lab 02 |
+1. Select **Python** (recommended for this workshop).
+2. Click **Next**.
 
-1. Select **Single Agent**.
-2. Click **Next** (or the selection proceeds automatically).
+> **C# is also supported** if you prefer .NET. The scaffold structure is similar (uses `Program.cs` instead of `main.py`).
 
 ---
 
-## Step 3: Choose programming language
+## Step 3: Select API type
 
-1. Select **Python** (recommended for this workshop).
+The wizard asks how your agent receives and responds to requests:
+
+| API type | Endpoint | Use when |
+|----------|----------|----------|
+| **Response API** ✅ *(this workshop)* | `POST /responses` | Conversational chatbots, streaming, multi-turn with platform-managed history |
+| Invocation API | `POST /invocations` | Webhooks, non-conversational processing, custom async workflows |
+
+1. Select **Response API**.
 2. Click **Next**.
 
-> **C# is also supported** if you prefer .NET. The scaffold structure is similar (uses `Program.cs` instead of `main.py`).
+---
+
+## Step 4: Select template
+
+Available templates for Response API + Python (Foundry Toolkit v1.2.1):
+
+| Template | Description |
+|----------|-------------|
+| **Basic - Agent Framework** ← *(select this)* | A basic agent using the Agent Framework SDK |
+| Echo (Streaming) | A basic echo agent with streaming support |
+| Multi-Turn Chat | An agent that supports multi-turn conversations |
+| Note Taking | An agent with note-taking capabilities |
+
+1. Select **Basic - Agent Framework**.
+2. Click **Next**.
 
 ---
 
-## Step 4: Select your model
+## Step 5: Select your model
 
 1. The wizard shows the models deployed in your Foundry project (from Module 2).
 2. Select the model you deployed - e.g., **gpt-4.1-mini**.
@@ -74,17 +93,18 @@ The wizard asks you to select a template. You'll see options like:
 
 ---
 
-## Step 5: Choose folder location and agent name
+## Step 6: Choose workspace and agent name
 
-1. A file dialog opens - choose a **target folder** where the project will be created. For this workshop:
+1. Select your **Foundry workspace** from the list.
+2. A file dialog opens - choose a **target folder** where the project will be created. For this workshop:
    - If starting fresh: choose any folder (e.g., `C:\Projects\my-agent`)
    - If working within the workshop repo: create a new subfolder under `workshop/lab01-single-agent/agent/`
-2. Enter a **name** for the hosted agent (e.g., `executive-summary-agent` or `my-first-agent`).
-3. Click **Create** (or press Enter).
+3. Enter a **name** for the hosted agent (e.g., `executive-summary-agent` or `my-first-agent`).
+4. Click **Create** (or press Enter).
 
 ---
 
-## Step 6: Wait for scaffolding to complete
+## Step 7: Wait for scaffolding to complete
 
 1. VS Code opens a **new window** with the scaffolded project.
 2. Wait a few seconds for the project to fully load.
@@ -107,16 +127,15 @@ The wizard asks you to select a template. You'll see options like:
 
 ---
 
-## Step 7: Understand each generated file
+## Step 8: Understand each generated file
 
 Take a moment to inspect each file the wizard created. Understanding them is important for Module 4 (customization).
 
-### 7.1 `agent.yaml` - Agent definition
+### 8.1 `agent.yaml` - Agent definition
 
 Open `agent.yaml`. It looks like this:
 
 ```yaml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
 
 kind: hosted
 name: my-first-agent
@@ -153,7 +172,7 @@ resources:
 | `dockerfile_path` | Points to the Dockerfile used to build the container image |
 | `resources` | CPU and memory allocation for the container (0.25 CPU, 0.5Gi memory) |
 
-### 7.2 `main.py` - Agent entry point
+### 8.2 `main.py` - Agent entry point
 
 Open `main.py`. This is the main Python file where your agent logic lives. The scaffold includes:
 
@@ -174,7 +193,7 @@ from azure.identity.aio import DefaultAzureCredential
 The main flow is:
 1. Create a credential → create a client → call `.as_agent()` to get an agent (async context manager) → wrap it as a server → run
 
-### 7.3 `Dockerfile` - Container image
+### 8.3 `Dockerfile` - Container image
 
 ```dockerfile
 FROM python:3.14-slim
@@ -202,7 +221,7 @@ CMD ["python", "main.py"]
 - **Exposes port 8088** - this is the required port for hosted agents. Do not change it.
 - Starts the agent with `python main.py`.
 
-### 7.4 `requirements.txt` - Dependencies
+### 8.4 `requirements.txt` - Dependencies
 
 ```
 agent-framework-azure-ai==1.0.0rc3