Build, test, and deploy AI agents to Microsoft Foundry Agent Service as Hosted Agents - entirely from VS Code using the Microsoft Foundry extension and Foundry Toolkit.
Hosted Agents are currently in preview. Supported regions are limited - see region availability.
The
agent/folder inside each lab is automatically scaffolded by the Foundry extension - you then customize the code, test locally, and deploy.
flowchart TB
subgraph Local["Local Development (VS Code)"]
direction TB
FE["Microsoft Foundry
Extension"]
FoundryToolkit["Foundry Toolkit
Extension"]
Scaffold["Scaffolded Agent Code
(main.py · agent.yaml · Dockerfile)"]
Inspector["Agent Inspector
(Local Testing)"]
FE -- "Create New
Hosted Agent" --> Scaffold
Scaffold -- "F5 Debug" --> Inspector
FoundryToolkit -.- Inspector
end
subgraph Cloud["Microsoft Foundry"]
direction TB
ACR["Azure Container
Registry"]
AgentService["Foundry Agent Service
(Hosted Agent Runtime)"]
Model["Azure OpenAI
(gpt-4.1 / gpt-4.1-mini)"]
Playground["Foundry Playground
& VS Code Playground"]
ACR --> AgentService
AgentService -- "/responses API" --> Model
AgentService --> Playground
end
Scaffold -- "Deploy
(Docker build + push)" --> ACR
Inspector -- "POST /responses
(localhost:8088)" --> Scaffold
Playground -- "Test prompts" --> AgentService
style Local fill:#f0f4ff,stroke:#4a6cf7,stroke-width:2px
style Cloud fill:#fff4e6,stroke:#f59e0b,stroke-width:2px
Flow: Foundry extension scaffolds the agent → you customize code & instructions → test locally with Agent Inspector → deploy to Foundry (Docker image pushed to ACR) → verify in Playground.
| Lab | Description | Status |
|---|---|---|
| Lab 01 - Single Agent | Build the "Explain Like I'm an Executive" Agent, test it locally, and deploy to Foundry | ✅ Available |
| Lab 02 - Multi-Agent Workflow | Build the "Resume → Job Fit Evaluator" - 4 agents collaborate to score resume fit and generate a learning roadmap | ✅ Available |
In this workshop you will build the "Explain Like I'm an Executive" Agent - an AI agent that takes gnarly technical jargon and translates it into calm, boardroom-ready summaries. Because let's be honest, nobody in the C-suite wants to hear about "thread pool exhaustion caused by synchronous calls introduced in v3.2."
I built this agent after one too many incidents where my perfectly crafted post-mortem got the response: "So... is the website down or not?"
You feed it a technical update. It spits back an executive summary - three bullet points, no jargon, no stack traces, no existential dread. Just what happened, business impact, and next step.
You say:
"The API latency increased due to thread pool exhaustion caused by synchronous calls introduced in v3.2."
The agent replies:
Executive Summary:
- What happened: After the latest release, the system slowed down.
- Business impact: Some users experienced delays while using the service.
- Next step: The change has been rolled back and a fix is being prepared before redeployment.
It is a dead-simple, single-purpose agent - perfect for learning the hosted agent workflow end to end without getting bogged down in complex tool chains. And honestly? Every engineering team could use one of these.
📂 Foundry_Toolkit_for_VSCode_Lab/
├── 📄 README.md ← You are here
├── 📂 ExecutiveAgent/ ← Standalone hosted agent project
│ ├── agent.yaml
│ ├── Dockerfile
│ ├── main.py
│ └── requirements.txt
└── 📂 workshop/
├── 📂 lab01-single-agent/ ← Full lab: docs + agent code
│ ├── README.md ← Hands-on lab instructions
│ ├── 📂 docs/ ← Step-by-step tutorial modules
│ │ ├── 00-prerequisites.md
│ │ ├── 01-install-foundry-toolkit.md
│ │ ├── 02-create-foundry-project.md
│ │ ├── 03-create-hosted-agent.md
│ │ ├── 04-configure-and-code.md
│ │ ├── 05-test-locally.md
│ │ ├── 06-deploy-to-foundry.md
│ │ ├── 07-verify-in-playground.md
│ │ └── 08-troubleshooting.md
│ └── 📂 agent/ ← Reference solution (auto-scaffolded by Foundry extension)
│ ├── agent.yaml
│ ├── Dockerfile
│ ├── main.py
│ └── requirements.txt
└── 📂 lab02-multi-agent/ ← Resume → Job Fit Evaluator
├── README.md ← Hands-on lab instructions (end-to-end)
├── 📂 docs/ ← Step-by-step tutorial modules
│ ├── 00-prerequisites.md
│ ├── 01-understand-multi-agent.md
│ ├── 02-scaffold-multi-agent.md
│ ├── 03-configure-agents.md
│ ├── 04-orchestration-patterns.md
│ ├── 05-test-locally.md
│ ├── 06-deploy-to-foundry.md
│ ├── 07-verify-in-playground.md
│ └── 08-troubleshooting.md
└── 📂 PersonalCareerCopilot/ ← Reference solution (multi-agent workflow)
├── agent.yaml
├── Dockerfile
├── main.py
└── requirements.txt
Note: The
agent/folder inside each lab is what the Microsoft Foundry extension generates when you runMicrosoft Foundry: Create a New Hosted Agentfrom the Command Palette. The files are then customized with your agent's instructions, tools, and configuration. Lab 01 walks you through recreating this from scratch.
git clone https://github.com/microsoft-foundry/Foundry_Toolkit_for_VSCode_Lab.git
cd Foundry_Toolkit_for_VSCode_Labpython -m venv venvActivate it:
- Windows (PowerShell):
.\venv\Scripts\Activate.ps1
- macOS / Linux:
source venv/bin/activate
pip install -r workshop/lab01-single-agent/agent/requirements.txtCopy the example .env file inside the agent folder and fill in your values:
cp workshop/lab01-single-agent/agent/.env.example workshop/lab01-single-agent/agent/.envEdit workshop/lab01-single-agent/agent/.env:
AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>Each lab is self-contained with its own modules. Start with Lab 01 to learn the fundamentals, then move on to Lab 02 for multi-agent workflows.
Lab 01 - Single Agent (full instructions)
| # | Module | Link |
|---|---|---|
| 1 | Read the prerequisites | 00-prerequisites.md |
| 2 | Install Foundry Toolkit & Foundry extension | 01-install-foundry-toolkit.md |
| 3 | Create a Foundry project | 02-create-foundry-project.md |
| 4 | Create a hosted agent | 03-create-hosted-agent.md |
| 5 | Configure instructions & environment | 04-configure-and-code.md |
| 6 | Test locally | 05-test-locally.md |
| 7 | Deploy to Foundry | 06-deploy-to-foundry.md |
| 8 | Verify in playground | 07-verify-in-playground.md |
| 9 | Troubleshooting | 08-troubleshooting.md |
Lab 02 - Multi-Agent Workflow (full instructions)
| # | Module | Link |
|---|---|---|
| 1 | Prerequisites (Lab 02) | 00-prerequisites.md |
| 2 | Understand multi-agent architecture | 01-understand-multi-agent.md |
| 3 | Scaffold the multi-agent project | 02-scaffold-multi-agent.md |
| 4 | Configure agents & environment | 03-configure-agents.md |
| 5 | Orchestration patterns | 04-orchestration-patterns.md |
| 6 | Test locally (multi-agent) | 05-test-locally.md |
| 7 | Deploy to Foundry | 06-deploy-to-foundry.md |
| 8 | Verify in playground | 07-verify-in-playground.md |
| 9 | Troubleshooting (multi-agent) | 08-troubleshooting.md |
 Shivam Goyal |
| Scenario | Required roles |
|---|---|
| Create new Foundry project | Azure AI Owner on Foundry resource |
| Deploy to existing project (new resources) | Azure AI Owner + Contributor on subscription |
| Deploy to fully configured project | Reader on account + Azure AI User on project |
Important: Azure
OwnerandContributorroles only include management permissions, not development (data action) permissions. You need Azure AI User or Azure AI Owner to build and deploy agents.
- Quickstart: Deploy your first hosted agent (VS Code)
- What are hosted agents?
- Create hosted agent workflows in VS Code
- Deploy a hosted agent
- RBAC for Microsoft Foundry
- Architecture Review Agent Sample - Real-world hosted agent with MCP tools, Excalidraw diagrams, and dual deployment