Microsoft Agent Framework - Learning Labs

Introduction

Welcome to the Microsoft Agent Framework Learning Labs! This repository provides a hands-on approach to learning how to build AI Agents using the Microsoft Agents Framework with Azure OpenAI.

Objective

The objective of these labs is to guide developers through the process of building intelligent AI agents, from basic chat interactions to advanced multi-agent systems. Each lab focuses on a specific concept and includes practical scenarios that progressively build your knowledge and skills.

How the Labs are Structured

Each lab follows a consistent structure designed for effective learning:

LabXX-LabName/
├── README.md       <-- Detailed instructions, hints, and explanations
├── Start/          <-- Your working folder with TODOs to complete
│   └── Program.cs  <-- Contains step-by-step TODOs with hints
└── Solution/       <-- Complete reference implementation
    └── Program.cs  <-- Fully working code to compare with your solution

How to Work with Each Lab

1. Read the README.md - Understand the objective and key concepts
2. Open the Start/ folder - This is your working directory
3. Complete the TODOs - Follow the comments in Program.cs with basic hints
4. Need more help? - Check the README.md for detailed hints and explanations
5. Stuck? - Compare your code with the Solution/ folder

Each lab contains one or more scenarios that demonstrate different aspects of the topic being covered.

---

Prerequisites

Migration in progress: the labs are being migrated to the stable release of Microsoft Agent Framework (1.22.0). Migrated so far: AzureOpenAI/Lab01, AzureOpenAI/Lab02, AzureOpenAI/Lab03, AzureOpenAI/Lab04, AzureOpenAI/Lab05, AzureOpenAI/Lab06_A2AServer, AzureOpenAI/Lab06_A2AClient, AzureOpenAI/Lab07, AzureOpenAI/Lab08 and AzureOpenAI/Lab09. See Migration/Migration-Plan.md. Only the migrated labs are available in the dashboard; every lab runs with the CLI.

---

Running the Labs: CLI or Dashboard

There are two ways to run a lab. Both run the same projects, with the same dotnet commands and the same configuration, so you can switch at any time.

Whichever you choose, configure Azure OpenAI once first: the configuration is shared by every lab and by both options.

Configure Azure OpenAI

Each lab reads its settings from these sources (the last one wins):

1. appsettings.json of the lab (ships with YOUR-… placeholders)
2. User secrets shared by all migrated labs (id microsoft-agent-framework-learninglabs, stored outside the repository)
3. Environment variables AzureOpenAI__*

Pick one method:

• Dashboard form, no terminal needed — see step 4 of Option B.
• User secrets (recommended for the API key), from any migrated lab project folder:

  cd LearningLabs/AzureOpenAI/Lab01-FirstBasicAIAgent/Start
  dotnet user-secrets set "AzureOpenAI:Endpoint" "https://my-resource.openai.azure.com/"
  dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "gpt-4o"
  dotnet user-secrets set "AzureOpenAI:APIKey" "<your-api-key>"   # optional: omit it to use Microsoft Entra ID
  dotnet user-secrets list
  

• Environment variables, required for the labs that are not migrated yet (they don't read user secrets) — see Environment Variables Configuration.
• appsettings.json of a single lab — works, but never commit a real key.

If the endpoint or the deployment is missing, a migrated lab stops with "'AzureOpenAI:Endpoint' is not configured". No API version is needed: the labs use the Azure OpenAI v1 API (…/openai/v1/).

---

Option A — Run a lab with the dotnet CLI

1. Find the lab

Labs live in LearningLabs/<Part>/<LabFolder>/, and each lab has two projects:

ls LearningLabs/AzureOpenAI        # Part 1: Lab01-FirstBasicAIAgent, Lab02-AIAgentWithSO, ...
ls LearningLabs/MultiAgentSystem   # Part 2: Lab01-UseAgentAsTool, Lab02_OrchestrationSequential, ...

What each lab covers is listed in Labs Overview.

2. Run it

From the lab folder:

cd LearningLabs/AzureOpenAI/Lab01-FirstBasicAIAgent/Start
dotnet run

Or from the repository root:

# My exercise
dotnet run --project LearningLabs/AzureOpenAI/Lab01-FirstBasicAIAgent/Start

# Reference solution
dotnet run --project LearningLabs/AzureOpenAI/Lab01-FirstBasicAIAgent/Solution

The first dotnet run restores the NuGet packages and builds the project (including the shared CommonUtilities project). To only check that your code compiles: dotnet build LearningLabs/AzureOpenAI/Lab01-FirstBasicAIAgent/Start.

Lab06 (A2A) has two separate labs: start Lab06_A2AServer in one terminal (it listens on http://localhost:5000 until Ctrl+C), then Lab06_A2AClient in another. Both use the A2A protocol v1 (preview packages aligned on Agent Framework 1.22.0): a migrated client cannot call an old v0.3 server.

3. Read the result

The program prints each scenario (=== Scenario 1: … ===), the agent answers and, in most labs, the token usage (Input tokens: …). Compare it with the output of Solution/. Stop a running lab with Ctrl+C.

---

Option B — Run a lab with the Lab Bench Dashboard

The dashboard is a local web UI (listening on 127.0.0.1 only) that builds and runs the labs for you and shows the live output, a verdict, the token usage and the run history. It is optional: no lab depends on it.

1. Start the dashboard

Run it from its own folder (it locates the labs relative to this folder):

cd Dashboard/LabDashboard
dotnet run

The terminal prints Lab dashboard running on http://127.0.0.1:5057 (Ctrl+C to stop). Keep it open; stop the dashboard with Ctrl+C.

Port 5057 already in use? Dashboard__Port=5058 dotnet run (macOS/Linux) or $env:Dashboard__Port=5058; dotnet run (PowerShell).

2. Open the interface

Open http://127.0.0.1:5057 in your browser. The top bar shows:

• the runner status (Runner connected);
• the Azure OpenAI button with the authentication status: API key, Microsoft Entra ID or Not configured;
• the EN | FR language selector.

The Labs list on the left shows every registered lab with its progress (Not started, In progress, Completed) and last result.

3. Select a lab

Click a lab in the list. Its page has five tabs:

4. Configure Azure OpenAI from the dashboard

Click Azure OpenAI in the top bar and fill in:

• Endpoint — e.g. https://my-resource.openai.azure.com/
• Chat deployment — the deployment name in your resource (not the model name)
• API key — optional; leave it empty to use Microsoft Entra ID (az login). Once saved, the key is never displayed again ("•••• stored — leave empty to keep it"); Remove API key deletes it.

Click Save. The values are written to the shared user secrets (outside the repository) and are used by the next run, from the dashboard and from dotnet run alike. The form shows where each value comes from and warns when an AzureOpenAI__* environment variable overrides it.

5. Run the lab

In the Run tab:

1. Choose the project: My exercise (Start/) or Reference solution (Solution/).
2. Click Run. The dashboard runs dotnet build, then dotnet run --no-build — the same commands as the CLI.
3. Follow the steps Build → Run → Checks. Cancel stops the run (the whole process tree is killed); a run also stops when the lab timeout is reached.

Only one run can be in progress at a time.

Interactive labs (the program calls Console.ReadLine()): during the run, an input box appears under the output. When the program reads, the box is focused with a Waiting for input #n badge; type the value and press Enter — it is echoed in the output and sent to the program. You can type ahead, and End input closes the standard input (the next ReadLine() returns null, like Ctrl+D). Waiting for your answer does not count against the lab time limit; a prompt left unanswered for 10 minutes stops the run. The About tab says whether a lab is interactive.

6. Read the results, logs and execution details

The API key never appears in the output, the history or a copied output: it is replaced by ••••.

Dashboard limitations

• Only the migrated labs are listed (AzureOpenAI Lab01–Lab09): run the other labs with the CLI.
• Lab09: scenario 1 waits for your decision in the input box under the output (type Y to approve; its checks expect the approval). Scenario 2 needs no input.
• Lab06: the dashboard runs the A2A server and client together (on port 5071), you do not need to start the server yourself.
• Interactive input works for the labs declared interactive in the dashboard catalog; key-by-key input (Console.ReadKey) is not supported.
• Console colors are not rendered.

More details (architecture, HTTP API, security, registering a new lab, tests): Dashboard/README.md.

Optional: report your progress to the trainer's admin dashboard

In a workshop, the trainer may host the Admin Dashboard (a separate Next.js + MongoDB application, kept in its own repository) and give you its URL and a workshop key. Set them once (Dashboard:Reporting:ServerUrl and Dashboard:Reporting:WorkshopKey, see Reporting to the admin dashboard), choose a username at the first launch, and your Lab Bench reports which labs you run and finish, plus a Help / Je suis bloqué button that the trainer sees in real time. Nothing is reported when ServerUrl is empty (the default), and never your code, your API key or your console output. The API contract between the two applications is described in specs/admin-dashboard-progress-tracking/spec.md.

---

Labs Overview

The labs are organized into two main parts:

Part 1: AzureOpenAI - Individual AI Agents

This part focuses on building individual AI agents with various capabilities. You will learn how to create agents, add tools, handle structured output, connect to external services, and implement human-in-the-loop patterns.

---

Lab 01 - First Basic AI Agent

Learn the fundamentals of creating an AI Agent

---

Lab 02 - AI Agent with Structured Output

Learn how to get structured JSON responses from an AI Agent

---

Lab 03 - AI Agent with Function Tools

Learn how to give agents access to external functions and data

---

Lab 04 - AI Agent with MCP Client

Learn how to integrate with Model Context Protocol (MCP) servers

---

Lab 05 - AI Agent with Sessions

Learn how to hold, save and resume conversations (AgentSession) and where their chat history is stored (ChatHistoryProvider)

---

Lab 06 - Agent-to-Agent Communication (A2A)

Learn how agents call each other over HTTP with the Agent-to-Agent protocol (A2A v1)

This lab is split into two parts: start the server, then run the client.

Lab 06 - A2A Server

Lab 06 - A2A Client

---

Lab 07 - Agentic RAG with a Vector Store

Learn how to build agents that answer from your own data (RAG): embeddings, vector store, search tool and TextSearchProvider

---

Lab 08 - Data Format Comparison

Learn how the format of the data exchanged with the model (tool results and answers) changes the token usage

---

Lab 09 - AI Agent with Function Tools and Human Approval

Learn how to make an agent pause before a sensitive tool runs (human-in-the-loop): ApprovalRequiredAIFunction, ToolApprovalRequestContent, CreateResponse and the same AgentSession

---

Lab 10 - Expose AI Agent as MCP Tool

Learn how to expose your AI Agent as an MCP server for other clients

---

Lab 11 - AI Agent with Custom HTTP Transport

Learn how to customize HTTP communication for debugging and monitoring

---

Lab 12 - AI Agent with AI Context Provider

Learn how to inject dynamic context into agent conversations

---

Part 2: MultiAgentSystem - Multi-Agent Solutions

This part focuses on building multi-agent systems where multiple agents collaborate to solve complex problems. You will learn how to orchestrate agents, use agents as tools, and build sophisticated AI workflows.

---

Lab 01 - Use Agent as Tool

Learn how to use an AI Agent as a tool for another agent

---

Lab 02 - Orchestration Sequential

Learn how to orchestrate multiple agents in a sequential pipeline

---

Lab 03 - Orchestration Concurrent

Learn how to orchestrate multiple agents running in parallel

---

Common Utilities

The CommonUtilities project provides shared helper classes used across all labs:

---

Getting Started

1. Clone the repository and check the prerequisites

   git clone <repository-url>
   cd MicrosoftAgentFramework
   dotnet --version   # 10.0 or newer
   

2. Configure Azure OpenAI once — see Configure Azure OpenAI

3. Choose a lab (AzureOpenAI/Lab01 recommended for beginners), read its README.md and complete the TODOs in Start/Program.cs

4. Run it with either option (see Running the Labs):

   # Option A — CLI
   dotnet run --project LearningLabs/AzureOpenAI/Lab01-FirstBasicAIAgent/Start
   
   # Option B — Dashboard: then open http://127.0.0.1:5057, select the lab and click Run
   cd Dashboard/LabDashboard && dotnet run
   

---

Environment Variables Configuration

Instead of editing each appsettings.json file in every lab, you can set environment variables once. The .NET configuration system automatically reads environment variables using the pattern SectionName__PropertyName (double underscore).

Required Variables

Linux / macOS

Add the following to your ~/.bashrc or ~/.zshrc file:

# Azure OpenAI Configuration
export AzureOpenAI__Endpoint="https://YOUR-RESOURCE.openai.azure.com/"
export AzureOpenAI__ChatDeploymentName="YOUR-DEPLOYMENT-NAME"
export AzureOpenAI__EmbeddingDeploymentName="YOUR-EMBEDDING-DEPLOYMENT-NAME"

# MongoDB Configuration (for Lab05, Lab12)
export MongoDB__ConnectionString="mongodb://localhost:27017"

Then reload your shell:

source ~/.bashrc
# or for zsh
source ~/.zshrc

Windows (PowerShell - Current Session)

# Azure OpenAI Configuration
$env:AzureOpenAI__Endpoint = "https://YOUR-RESOURCE.openai.azure.com/"
$env:AzureOpenAI__ChatDeploymentName = "YOUR-DEPLOYMENT-NAME"
$env:AzureOpenAI__EmbeddingDeploymentName = "YOUR-EMBEDDING-DEPLOYMENT-NAME"

# MongoDB Configuration (for Lab05, Lab12)
$env:MongoDB__ConnectionString = "mongodb://localhost:27017"

Windows (Permanent - System Environment Variables)

1. Open System Properties → Advanced → Environment Variables
2. Under User variables, click New for each variable:
   • Variable name: AzureOpenAI__Endpoint
   • Variable value: https://YOUR-RESOURCE.openai.azure.com/
3. Repeat for other variables
4. Click OK and restart your terminal

Or using PowerShell (Administrator):

[Environment]::SetEnvironmentVariable("AzureOpenAI__Endpoint", "https://YOUR-RESOURCE.openai.azure.com/", "User")
[Environment]::SetEnvironmentVariable("AzureOpenAI__ChatDeploymentName", "YOUR-DEPLOYMENT-NAME", "User")
[Environment]::SetEnvironmentVariable("AzureOpenAI__EmbeddingDeploymentName", "YOUR-EMBEDDING-DEPLOYMENT-NAME", "User")
[Environment]::SetEnvironmentVariable("MongoDB__ConnectionString", "mongodb://localhost:27017", "User")

Verify Your Configuration

Run this command to verify your environment variables are set:

# Linux/macOS
echo $AzureOpenAI__Endpoint

# Windows PowerShell
echo $env:AzureOpenAI__Endpoint

Note: Environment variables take precedence over values in appsettings.json. You can still use appsettings.json for lab-specific overrides if needed.

Migrated labs also read user secrets (shared id microsoft-agent-framework-learninglabs), the recommended place for the API key during local development: dotnet user-secrets set "AzureOpenAI:APIKey" "<your-api-key>" (run from any migrated lab project folder), or, without a terminal, the Azure OpenAI settings of the Lab Bench dashboard, which write the same file.

---

Learning Path

We recommend following the labs in order, starting with the AzureOpenAI labs (individual agents) and then moving to the MultiAgentSystem labs:

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                           Part 1: AzureOpenAI (Individual Agents)                              │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│  Lab01 → Lab02 → Lab03 → Lab04 → Lab05 → Lab06 → Lab07 → Lab08 → Lab09 → Lab10 → Lab11 → Lab12│
│    │       │       │       │       │       │       │       │       │       │       │       │   │
│    ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼   │
│  Basic  Struct  Tools    MCP   Threads   A2A    RAG   Format  Human    MCP   Custom  Context  │
│  Agent  Output  Calling Client                        Optim  Approval Server  HTTP  Provider  │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
                                            │
                                            ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                        Part 2: MultiAgentSystem (Multi-Agent Solutions)                        │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│  Lab01 → Lab02 → Lab03 → ...                                                                   │
│    │       │       │                                                                           │
│    ▼       ▼       ▼                                                                           │
│  Agent  Sequential Concurrent                                                                  │
│  as Tool Orchestr. Orchestr.                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────────────┘

Note: While we recommend following the labs in order, there are no strict dependencies between the different labs. If you already have some knowledge in a specific area, feel free to jump to any lab that interests you.

---

Useful Links

• Microsoft Agent Framework
• Microsoft Agents Documentation
• Azure OpenAI Documentation
• Model Context Protocol (MCP)

---

Contributing

If you find issues or have suggestions for improving these labs, please open an issue or submit a pull request.

---

Author

Mohammed BEN SAID

---

Happy Learning! 🚀