Foundry Toolkit + Foundry Hosted Agents Workshop

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.

🌐 Multi-Language Support

Supported via GitHub Action (Automated & Always Up-to-Date)

Prefer to Clone Locally?

This repository includes 50+ language translations which significantly increases the download size. To clone without translations, use sparse checkout:

Bash / macOS / Linux:
git clone --filter=blob:none --sparse https://github.com/microsoft-foundry/Foundry_Toolkit_for_VSCode_Lab.git
cd Foundry_Toolkit_for_VSCode_Lab
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'
CMD (Windows):
git clone --filter=blob:none --sparse https://github.com/microsoft-foundry/Foundry_Toolkit_for_VSCode_Lab.git
cd Foundry_Toolkit_for_VSCode_Lab
git sparse-checkout set --no-cone "/*" "!translations" "!translated_images"
This gives you everything you need to complete the course with a much faster download.

Architecture

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.

What you will build

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

Meet the Executive Agent

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?"

How it works

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.

See it in action

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.

Why this agent?

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.

Workshop structure

📂 Foundry_Toolkit_for_VSCode_Lab/
├── 📄 README.md                      ← You are here
└── 📂 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-setup.md
    │   │   ├── 02-create-hosted-agent.md
    │   │   ├── 03-configure-and-code.md
    │   │   ├── 04-test-locally.md
    │   │   ├── 05-deploy-to-foundry.md
    │   │   ├── 06-verify-in-playground.md
    │   │   ├── 07-summary.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
        └── 📂 PersonalCareerCopilotCompleted/ ← 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 run Microsoft Foundry: Create a New Hosted Agent from 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.

Getting started

1. Clone the repository

git clone https://github.com/microsoft-foundry/Foundry_Toolkit_for_VSCode_Lab.git
cd Foundry_Toolkit_for_VSCode_Lab

2. Set up a Python virtual environment

python -m venv venv

Activate it:

Windows (PowerShell):
```
.\venv\Scripts\Activate.ps1
```
macOS / Linux:
```
source venv/bin/activate
```

3. Install dependencies

pip install -r workshop/lab01-single-agent/agent/requirements.txt

4. Configure environment variables

Copy 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/.env

Edit workshop/lab01-single-agent/agent/.env:

AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

5. Follow the workshop labs

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-setup.md
3	Create a Foundry project	01-setup.md
4	Create a hosted agent	02-create-hosted-agent.md
5	Configure instructions & environment	03-configure-and-code.md
6	Test locally	04-test-locally.md
7	Deploy to Foundry	05-deploy-to-foundry.md
8	Verify in playground	06-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

Person wey dey maintain am

_{Shivam Goyal}

Permission dem wey you need (quick reference)

Scenario	Roles wey you need
Create new Foundry project	Azure AI Owner for Foundry resource
Deploy for existing project (new resources)	Azure AI Owner + Contributor for subscription
Deploy for fully configured project	Reader for account + Azure AI User for project

Important: Azure Owner and Contributor roles get only management permissions, no be development (data action) permissions. You go need Azure AI User or Azure AI Owner to build and deploy agents.

References

Quickstart: Deploy your first hosted agent (VS Code)
Wetin hosted agents be?
Create hosted agent workflows for VS Code
Deploy hosted agent
RBAC for Microsoft Foundry
Architecture Review Agent Sample - Real-world hosted agent with MCP tools, Excalidraw diagrams, and dual deployment

License

MIT

Disclaimer: Dis document don translate wit AI translation service Co-op Translator. Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation.

FilesExpand file tree

README.md

Latest commit

History