A hands-on workshop for running language models on your own machine and building intelligent applications with Foundry Local and the Microsoft Agent Framework.
What is Foundry Local? Foundry Local is a lightweight runtime that lets you download, manage, and serve language models entirely on your hardware. It exposes an OpenAI-compatible API so any tool or SDK that speaks OpenAI can connect - no cloud account required.
By the end of this workshop you will be able to:
| # | Objective |
|---|---|
| 1 | Install Foundry Local and manage models with the CLI |
| 2 | Master the Foundry Local SDK API for programmatic model management |
| 3 | Connect to the local inference server using the Python, JavaScript, and C# SDKs |
| 4 | Build a Retrieval-Augmented Generation (RAG) pipeline that grounds answers in your own data |
| 5 | Create AI agents with persistent instructions and personas |
| 6 | Orchestrate multi-agent workflows with feedback loops |
| 7 | Explore a production capstone app - the Zava Creative Writer |
| 8 | Transcribe audio with Whisper - speech-to-text on-device using the Foundry Local SDK |
| Requirement | Details |
|---|---|
| Hardware | 8 GB RAM minimum (16 GB recommended); AVX2-capable CPU or a supported GPU |
| OS | Windows 10/11 (x64/ARM), Windows Server 2025, or macOS 13+ |
| Foundry Local CLI | Install via winget install Microsoft.FoundryLocal (Windows) or brew tap microsoft/foundrylocal && brew install foundrylocal (macOS). See the getting started guide for details. |
| Language runtime | Python 3.9+ and/or .NET 9.0+ and/or Node.js 18+ |
| Git | For cloning this repository |
# 1. Clone the repository
git clone https://github.com/microsoft/foundry-local-workshop.git
cd foundry-local-workshop
# 2. Verify Foundry Local is installed
foundry model list # List available models
foundry model run phi-3.5-mini # Start an interactive chat
# 3. Choose your language track (see Part 2 lab for full setup)| Language | Quick Start |
|---|---|
| Python | cd python && pip install -r requirements.txt && python foundry-local.py |
| C# | cd csharp && dotnet run |
| JavaScript | cd javascript && npm install && node foundry-local.mjs |
Lab guide: labs/part1-getting-started.md
- What is Foundry Local and how it works
- Installing the CLI on Windows and macOS
- Exploring models - listing, downloading, running
- Understanding model aliases and dynamic ports
Lab guide: labs/part2-foundry-local-sdk.md
- Why use the SDK over the CLI for application development
- Full SDK API reference for Python, JavaScript, and C#
- Service management, catalog browsing, model lifecycle (download, load, unload)
- Quick-start patterns: Python constructor bootstrap, JavaScript
init(), C#CreateAsync() FoundryModelInfometadata, aliases, and hardware-optimal model selection
Lab guide: labs/part3-sdk-and-apis.md
- Connecting to Foundry Local from Python, JavaScript, and C#
- Using the Foundry Local SDK to manage the service programmatically
- Streaming chat completions via the OpenAI-compatible API
- SDK method reference for each language
Code samples:
| Language | File | Description |
|---|---|---|
| Python | python/foundry-local.py |
Basic streaming chat |
| C# | csharp/BasicChat.cs |
Streaming chat with .NET |
| JavaScript | javascript/foundry-local.mjs |
Streaming chat with Node.js |
Lab guide: labs/part4-rag-fundamentals.md
- What is RAG and why it matters
- Building an in-memory knowledge base
- Keyword-overlap retrieval with scoring
- Composing grounded system prompts
- Running a complete RAG pipeline on-device
Code samples:
| Language | File |
|---|---|
| Python | python/foundry-local-rag.py |
| C# | csharp/RagPipeline.cs |
| JavaScript | javascript/foundry-local-rag.mjs |
Lab guide: labs/part5-single-agents.md
- What is an AI agent (vs. a raw LLM call)
- The
ChatAgentpattern and the Microsoft Agent Framework - System instructions, personas, and multi-turn conversations
- Structured output (JSON) from agents
Code samples:
| Language | File | Description |
|---|---|---|
| Python | python/foundry-local-with-agf.py |
Single agent with Agent Framework |
| C# | csharp/SingleAgent.cs |
Single agent (ChatAgent pattern) |
| JavaScript | javascript/foundry-local-with-agent.mjs |
Single agent (ChatAgent pattern) |
Lab guide: labs/part6-multi-agent-workflows.md
- Multi-agent pipelines: Researcher → Writer → Editor
- Sequential orchestration and feedback loops
- Shared configuration and structured hand-offs
- Designing your own multi-agent workflow
Code samples:
| Language | File | Description |
|---|---|---|
| Python | python/foundry-local-multi-agent.py |
Three-agent pipeline |
| C# | csharp/MultiAgent.cs |
Three-agent pipeline |
| JavaScript | javascript/foundry-local-multi-agent.mjs |
Three-agent pipeline |
Lab guide: labs/part7-zava-creative-writer.md
- A production-style multi-agent app with 4 specialised agents
- Sequential pipeline with evaluator-driven feedback loops
- Streaming output, product catalog search, structured JSON hand-offs
- Full implementation in Python (FastAPI), JavaScript (Node.js CLI), and C# (.NET console)
Code samples:
| Language | Directory | Description |
|---|---|---|
| Python | zava-creative-writer-local/src/api/ |
FastAPI web service with orchestrator |
| JavaScript | zava-creative-writer-local/src/javascript/ |
Node.js CLI application |
| C# | zava-creative-writer-local/src/csharp/ |
.NET 9 console application |
Lab guide: labs/part8-whisper-voice-transcription.md
- Speech-to-text transcription using OpenAI Whisper running locally
- Privacy-first audio processing - audio never leaves your device
- Python, JavaScript, and C# tracks with
client.audio.transcriptions.create()(Python/JS) andAudioClient.TranscribeAudioAsync()(C#) - Includes Zava-themed sample audio files for hands-on practice
Note: This lab uses the Foundry Local SDK to programmatically download and load the Whisper model, then sends audio to the local OpenAI-compatible endpoint for transcription. The Whisper model (
whisper) is listed in the Foundry Local catalog and runs entirely on-device - no cloud API keys or network access required.
├── python/ # Python examples
│ ├── foundry-local.py # Basic chat
│ ├── foundry-local-with-agf.py # Single agent (AGF)
│ ├── foundry-local-rag.py # RAG pipeline
│ ├── foundry-local-multi-agent.py # Multi-agent workflow
│ └── requirements.txt
├── csharp/ # C# examples
│ ├── Program.cs # CLI router (chat|rag|agent|multi)
│ ├── BasicChat.cs # Basic chat
│ ├── RagPipeline.cs # RAG pipeline
│ ├── SingleAgent.cs # Single agent (ChatAgent pattern)
│ ├── MultiAgent.cs # Multi-agent workflow
│ └── csharp.csproj
├── javascript/ # JavaScript examples
│ ├── foundry-local.mjs # Basic chat
│ ├── foundry-local-with-agent.mjs # Single agent
│ ├── foundry-local-rag.mjs # RAG pipeline
│ ├── foundry-local-multi-agent.mjs # Multi-agent workflow
│ └── package.json
├── zava-creative-writer-local/ # Production multi-agent app
│ └── src/api/
│ ├── main.py # FastAPI server
│ ├── orchestrator.py # Pipeline coordinator
│ ├── foundry_config.py # Shared Foundry Local config
│ └── agents/ # Researcher, Product, Writer, Editor
├── labs/ # Step-by-step lab guides
│ ├── part1-getting-started.md
│ ├── part2-foundry-local-sdk.md
│ ├── part3-sdk-and-apis.md
│ ├── part4-rag-fundamentals.md
│ ├── part5-single-agents.md
│ ├── part6-multi-agent-workflows.md
│ ├── part7-zava-creative-writer.md
│ └── part8-whisper-voice-transcription.md
├── samples/
│ └── audio/ # Zava-themed WAV files for Part 7
│ ├── generate_samples.py # TTS script (pyttsx3) to create WAVs
│ └── README.md # Sample descriptions
└── README.md
| Resource | Link |
|---|---|
| Foundry Local website | foundrylocal.ai |
| Model catalog | foundrylocal.ai/models |
| Foundry Local GitHub | github.com/microsoft/foundry-local |
| Getting started guide | Microsoft Learn - Foundry Local |
| Foundry Local SDK Reference | Microsoft Learn - SDK Reference |
| Microsoft Agent Framework | Microsoft Learn - Agent Framework |
| OpenAI Whisper | github.com/openai/whisper |
This workshop material is provided for educational purposes.
Happy building! 🚀