# AI Agents for Beginners — User Guide

## 1. Quick Start

**AI Agents for Beginners** is a 16-lesson open-source course by Microsoft that teaches the fundamentals of building AI agents. Each lesson combines conceptual material (markdown) with hands-on code samples in Python and C# (.NET), covering topics from basic agent creation through multi-agent orchestration, agentic RAG, planning, metacognition, and production deployment.

**Key features:**

- 16 structured lessons progressing from fundamentals to advanced patterns
- Code samples in both Python and C# (.NET) for every lesson
- Uses the Microsoft Agent Framework (MAF) for agent creation and workflow orchestration
- Azure AI Foundry integration for model deployment and agent services
- MCP (Model Context Protocol) examples for agent-to-agent communication
- Covers design patterns: sequential, concurrent, conditional, and multi-agent workflows
- Translated into 40+ languages
- Jupyter notebook-based exercises for interactive learning

**Prerequisites:** Python 3.12+, an Azure subscription, and Azure CLI installed.

**Fastest path to running your first sample:**

```bash
git clone --depth 1 https://github.com/microsoft/ai-agents-for-beginners.git
cd ai-agents-for-beginners
pip install -r requirements.txt
az login
cp .env.example .env
# Edit .env with your Azure AI Project endpoint and model deployment name
```

Then open any lesson notebook (e.g., `01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs` or a `*-python-agent-framework.ipynb` notebook) and run it.

> [!TIP]
> If you only need specific lessons, use a sparse checkout to avoid downloading the full repository (~3 GB with history): `git clone --depth 1 --filter=blob:none --sparse https://github.com/microsoft/ai-agents-for-beginners.git` then `git sparse-checkout set 00-course-setup 01-intro-to-ai-agents`.

**What to try next:**

- Walk through Lesson 01 (Intro to AI Agents) for your first agent
- See the Configuration section below for full environment setup
- Jump to Core Usage for a lesson-by-lesson guide

## 2. Installation

### System Requirements

| Component | Requirement |
|-----------|-------------|
| Python | 3.12 or later |
| .NET SDK | 10.0 or later (for C# samples) |
| Azure CLI | Latest version |
| Git | 2.25+ (for sparse checkout support) |
| OS | Windows, macOS, or Linux |
| Azure Subscription | Required for Azure AI Foundry |

### Clone the Repository

=== "Full Clone"
    ```bash
    git clone https://github.com/microsoft/ai-agents-for-beginners.git
    cd ai-agents-for-beginners
    ```

=== "Shallow Clone (recommended)"
    ```bash
    git clone --depth 1 https://github.com/microsoft/ai-agents-for-beginners.git
    cd ai-agents-for-beginners
    ```

=== "Sparse Checkout (specific lessons only)"
    ```bash
    git clone --depth 1 --filter=blob:none --sparse https://github.com/microsoft/ai-agents-for-beginners.git
    cd ai-agents-for-beginners
    git sparse-checkout set 00-course-setup 01-intro-to-ai-agents 02-explore-agentic-frameworks
    ```

=== "GitHub Codespaces"
    ```text
    Open the repository on GitHub and click "Code" → "Codespaces" → "Create codespace on main"
    ```

### Install Python Dependencies

Create a virtual environment first:

```bash
python3.12 -m venv venv
```

Activate it:

=== "Linux / macOS"
    ```bash
    source venv/bin/activate
    ```

=== "Windows (Command Prompt)"
    ```bash
    venv\Scripts\activate
    ```

=== "Windows (PowerShell)"
    ```powershell
    .\venv\Scripts\Activate.ps1
    ```

Install all dependencies:

```bash
pip install -r requirements.txt
```

> [!IMPORTANT]
> You **must** use Python 3.12 or later. Earlier versions will fail to install some dependencies. Verify with `python --version` before proceeding.

### Install .NET SDK (for C# Samples)

For the C# code samples, install the [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later:

```bash
dotnet --list-sdks
```

```text
10.0.100 [/usr/share/dotnet/sdk]
```

The repository includes a `global.json` that pins the SDK version:

```json
{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature",
    "allowPrerelease": false
  }
}
```

### Install Azure CLI

```bash
# See https://aka.ms/installazurecli for platform-specific instructions
az login
```

### Verify Installation

```bash
python --version
```

```text
Python 3.12.x
```

```bash
pip list | grep agent-framework
```

```text
agent-framework    x.y.z
```

```bash
az account show --query name -o tsv
```

```text
Your-Azure-Subscription-Name
```

> [!WARNING]
> If `az login` fails in a remote environment (Codespaces, SSH), use `az login --use-device-code` instead.

### Install Troubleshooting

### Error: `Python version 3.x is not supported`

**Cause:** You are running a Python version older than 3.12.

**Solution:**
1. Install Python 3.12+ from [python.org](https://www.python.org/downloads/)
2. Create a new venv: `python3.12 -m venv venv`
3. Activate and reinstall: `pip install -r requirements.txt`

**Prevention:** Always check `python --version` before installing dependencies.

### Error: `No module named 'agent_framework'`

**Cause:** Dependencies not installed or wrong virtual environment active.

**Solution:**
1. Ensure your venv is activated (check for `(venv)` in your prompt)
2. Run `pip install -r requirements.txt`

**Prevention:** Always activate the virtual environment before running notebooks.

### Error: `az login` hangs or times out

**Cause:** Running in a headless environment without browser access.

**Solution:**
1. Use device code flow: `az login --use-device-code`
2. Follow the URL and enter the code shown

**Prevention:** Use `--use-device-code` in any remote or containerized environment.

### Error: `dotnet: command not found`

**Cause:** .NET SDK not installed or not on PATH.

**Solution:**
1. Download and install from [dotnet.microsoft.com](https://dotnet.microsoft.com/download/dotnet/10.0)
2. Restart your terminal
3. Verify with `dotnet --version`

**Prevention:** Install the .NET SDK before attempting C# samples.

## 3. Configuration

### Core Environment Variables

Create your `.env` file by copying the example:

```bash
cp .env.example .env
```

The two required variables for most lessons:

```text
AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
```

| Variable | Description | Where to Find |
|----------|-------------|---------------|
| `AZURE_AI_PROJECT_ENDPOINT` | Your Azure AI Foundry project endpoint | Foundry portal → Project → **Overview** page |
| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Deployed model name (e.g., `gpt-4o`) | Foundry portal → **Models + endpoints** |

> [!IMPORTANT]
> Authentication uses `AzureCliCredential` — you must run `az login` before running any notebook. No API keys are stored in `.env` for authentication. This follows [Microsoft's recommended security practices](https://learn.microsoft.com/azure/developer/ai/keyless-connections).

### Lesson-Specific Variables

Some lessons require additional configuration:

**Lesson 5 — Agentic RAG (Azure AI Search):**

| Variable | Description |
|----------|-------------|
| `AZURE_SEARCH_SERVICE_ENDPOINT` | Azure AI Search resource URL |
| `AZURE_SEARCH_API_KEY` | Azure AI Search admin key |

**Lessons 6 & 8 — GitHub Models:**

| Variable | Default | Description |
|----------|---------|-------------|
| `GITHUB_TOKEN` | — | GitHub personal access token |
| `GITHUB_ENDPOINT` | `https://models.inference.ai.azure.com` | GitHub Models endpoint |
| `GITHUB_MODEL_ID` | `gpt-4o-mini` | Model name for GitHub Models |

**Lesson 14 — MiniMax Provider (optional):**

| Variable | Default | Description |
|----------|---------|-------------|
| `MINIMAX_API_KEY` | — | MiniMax API key |
| `MINIMAX_BASE_URL` | `https://api.minimax.io/v1` | MiniMax API endpoint |
| `MINIMAX_MODEL_ID` | `MiniMax-M2.7` | MiniMax model name |

> [!TIP]
> The code samples auto-detect which provider to use. If `MINIMAX_API_KEY` is set, MiniMax is used; if `GITHUB_TOKEN` is set, GitHub Models is used; otherwise OpenAI is the default.

For the complete configuration reference including all environment variables, see the Admin Guide.

## 4. Core Usage

### Course Structure

The course is organized into 16 lessons, each in its own directory:

| Lesson | Directory | Topic |
|--------|-----------|-------|
| 00 | `00-course-setup/` | Course setup and prerequisites |
| 01 | `01-intro-to-ai-agents/` | Introduction to AI agents |
| 02 | `02-explore-agentic-frameworks/` | Exploring agentic frameworks |
| 03 | `03-agentic-design-patterns/` | Agentic design patterns (transparency, control, consistency) |
| 04 | `04-tool-use/` | Tool use and function calling |
| 05 | `05-agentic-rag/` | Agentic RAG (Retrieval-Augmented Generation) |
| 06 | `06-building-trustworthy-agents/` | Building trustworthy agents |
| 07 | `07-planning-design/` | Planning and task decomposition |
| 08 | `08-multi-agent/` | Multi-agent systems and workflows |
| 09 | `09-metacognition/` | Metacognition in agents |
| 10 | `10-ai-agents-production/` | AI agents in production |
| 11 | `11-agentic-protocols/` | Agentic protocols (MCP) |
| 12 | `12-context-engineering/` | Context engineering |
| 13 | `13-agent-memory/` | Agent memory |
| 14 | `14-microsoft-agent-framework/` | Microsoft Agent Framework deep dive |
| 15 | `15-browser-use/` | Browser use agents |

Each lesson directory contains:

- `README.md` — Conceptual material and explanations
- `code_samples/` — Runnable Python and C# code samples

### Running Python Notebooks

All Python notebooks follow the naming convention `*-python-agent-framework.ipynb`:

1. Ensure your virtual environment is activated
2. Ensure you have run `az login`
3. Open the notebook in VS Code or Jupyter
4. Select the Python 3.12 kernel from your venv
5. Run cells sequentially

> [!NOTE]
> The notebooks use the Microsoft Agent Framework (MAF) with `AzureAIProjectAgentProvider`, which connects to **Azure AI Agent Service v2** (Responses API) via **Microsoft Foundry**.

### Running C# (.NET) Code Samples

C# samples use the `.cs` file extension and can be run directly:

```bash
dotnet run 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs
```

The C# samples declare their NuGet dependencies inline using `#:package` directives:

```csharp
#:package Microsoft.Extensions.AI@10.4.1
#:package Microsoft.Extensions.AI.OpenAI@10.4.1
#:package Microsoft.Agents.AI.OpenAI@1.1.0
```

> [!TIP]
> C# samples use environment variables (`GH_ENDPOINT`, `GH_MODEL_ID`, `GH_TOKEN`) that default to GitHub Models. Set these in your shell or `.env` file.

### Understanding the Agent Framework Patterns

Each lesson demonstrates a specific pattern:

**Lesson 01 — Simple Agent:** Create an agent with a tool function, run it with streaming output.

```csharp
AIAgent agent = openAIClient
    .GetChatClient(github_model_id)
    .AsAIAgent(
        instructions: "You are a helpful AI Agent...",
        tools: [AIFunctionFactory.Create(GetRandomDestination)]
    );

await foreach (var update in agent.RunStreamingAsync("Plan me a day trip"))
{
    Console.Write(update);
}
```

**Lesson 02 — Conversation Threads:** Multi-turn conversations with context preservation using `AgentThread`.

**Lesson 03 — Design Principles:** Transparency, control, and consistency built into agent instructions and tool design.

**Lesson 04 — Tool Use:** Multiple tools with different parameter types (no-param, single-param, multi-param, numeric). Tool composition for complex requests.

**Lesson 07 — Planning:** Structured output with JSON schemas for task decomposition across specialized sub-agents.

**Lesson 08 — Multi-Agent Workflows:** Sequential workflows using `WorkflowBuilder` with `.AddEdge()` to chain agents.

> [!WARNING]
> All notebooks that use Azure AI Foundry require an active `az login` session. If your session expires mid-lesson, re-run `az login` before continuing.

## 5. Common Tasks

### Set Up Azure AI Foundry for the First Time

**Goal:** Create the Azure infrastructure to run the course notebooks.

**Prerequisites:** An Azure subscription.

**Steps:**

1. Go to [ai.azure.com](https://ai.azure.com) and sign in
2. Create a **Hub** (or use an existing one)
3. Inside the Hub, create a **Project**
4. Deploy a model (e.g., `gpt-4o`) from **Models + endpoints** → **Deploy model**
5. Copy the **Project endpoint** from the Overview page
6. Note the **Model deployment name** from Models + endpoints

**Verify:** Your `.env` should contain:

```text
AZURE_AI_PROJECT_ENDPOINT=https://your-project.services.ai.azure.com/api/projects/your-project-id
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
```

### Run a Multi-Agent Workflow (Lesson 08)

**Goal:** Execute a sequential workflow where two agents collaborate.

**Prerequisites:** Azure AI Foundry configured, dependencies installed.

**Steps:**

1. Navigate to `08-multi-agent/code_samples/`
2. Open the Python notebook or C# sample
3. The sample creates a `FrontDesk` agent (travel recommendations) and a `Concierge` agent (reviews for authenticity)
4. The `WorkflowBuilder` chains them: FrontDesk → Concierge
5. Run the workflow with a travel query

**Verify:** You should see output from both agents — the FrontDesk makes a recommendation, and the Concierge reviews it for local authenticity.

### Run the MCP Agent-to-Agent Demo (Lesson 11)

**Goal:** Run the resumable MCP server with travel and research agents.

**Prerequisites:** Dependencies installed, lesson-specific setup complete.

**Steps:**

1. Start the MCP server:

```bash
python -m server.server --port 8006
```

2. In another terminal, start the client:

```bash
python -m client.client --url http://127.0.0.1:8006/mcp
```

3. Available commands in interactive mode:
   - `travel_agent` — Book travel with price confirmation (elicitation)
   - `research_agent` — Research topics with AI summaries (sampling)
   - `long_running_agent` — Test resumption (50 steps, 2 seconds each)
   - `list` — Show available tools
   - `clean-tokens` — Clear resumption tokens
   - `help` — Detailed command help

**Verify:** The travel agent should prompt for price confirmation, and the research agent should provide an AI-generated summary.

### Test Session Resumption

**Goal:** Verify that MCP session resumption works after client disconnection.

**Steps:**

1. Start the server and client as above
2. Run `travel_agent` or `long_running_agent`
3. Interrupt the client mid-execution (Ctrl+C)
4. Restart the client — it automatically resumes from where it left off

**Verify:** Progress continues from the last checkpoint, not from the beginning.

### Run the Hotel Booking Conditional Workflow (Lesson 14)

**Goal:** Execute a conditional workflow that routes based on hotel availability.

**Steps:**

1. Navigate to `14-microsoft-agent-framework/code-samples/`
2. Set one of the provider environment variables (`GITHUB_TOKEN`, `MINIMAX_API_KEY`, or `OPENAI_API_KEY`)
3. Run the sample:

```bash
python hotel_booking_workflow_sample.py
```

4. The workflow tests two cases:
   - Paris (no availability) → routes to alternative suggestion
   - Stockholm (has availability) → routes to booking confirmation

**Verify:** Output shows conditional routing — Paris gets an alternative city, Stockholm gets a booking confirmation.

### Switch Between Model Providers

**Goal:** Use a different LLM provider for the code samples.

The samples that use `OpenAIChatClient` support three providers with automatic detection:

| Provider | Required Variable | Endpoint |
|----------|-------------------|----------|
| MiniMax | `MINIMAX_API_KEY` | `https://api.minimax.io/v1` |
| GitHub Models | `GITHUB_TOKEN` | `https://models.inference.ai.azure.com` |
| OpenAI | `OPENAI_API_KEY` | Default OpenAI endpoint |

Set the appropriate environment variable in your `.env` file. MiniMax is checked first, then GitHub Models, then OpenAI.

> [!NOTE]
> MiniMax models support context windows up to 204K tokens, which can be useful for lessons involving large documents.

## 6. Troubleshooting

### Diagnostic Decision Tree

```text
Notebook fails to run?
├── Import error → Check venv is activated, run pip install -r requirements.txt
├── Authentication error → Run az login, check az account show
├── Model not found → Verify AZURE_AI_MODEL_DEPLOYMENT_NAME in .env
├── Timeout / connection error → Check Azure subscription status and network
├── .NET sample fails → Verify dotnet --version shows 10.0+
└── MCP server won't start → Check port 8006 is available
```

### Error: `DefaultAzureCredential failed`

**Cause:** Azure CLI session expired or not logged in.

**Solution:**
1. Run `az login` (or `az login --use-device-code` in remote environments)
2. Select the correct subscription
3. Verify with `az account show`

**Prevention:** Re-run `az login` at the start of each session.

### Error: `AZURE_AI_PROJECT_ENDPOINT is not set`

**Cause:** Missing `.env` file or variable not populated.

**Solution:**
1. Copy the example: `cp .env.example .env`
2. Fill in `AZURE_AI_PROJECT_ENDPOINT` from the Foundry portal
3. Restart the notebook kernel

**Prevention:** Always verify `.env` contents after initial setup.

### Error: `Model deployment not found`

**Cause:** The model name in `.env` doesn't match an active deployment.

**Solution:**
1. Go to Azure AI Foundry portal → **Models + endpoints**
2. Verify the exact deployment name
3. Update `AZURE_AI_MODEL_DEPLOYMENT_NAME` in `.env`

**Prevention:** Copy the deployment name exactly as shown in the portal.

### Error: `GH_TOKEN is not set` (C# samples)

**Cause:** GitHub Models token not configured for C# samples that use GitHub Models.

**Solution:**
1. Create a GitHub personal access token at GitHub → Settings → Developer settings → Personal access tokens
2. Set `GH_TOKEN` in your environment or `.env`

**Prevention:** Set up GitHub Models credentials before running C# samples from Lessons 01-04.

### Error: `Connection refused` on MCP server

**Cause:** Server not running or port conflict.

**Solution:**
1. Ensure the server is running: `python -m server.server --port 8006`
2. Check if port 8006 is in use: `lsof -i :8006` (Linux/macOS) or `netstat -an | findstr 8006` (Windows)
3. Use a different port: `--port 8007`

**Prevention:** Start the server before the client. Check for port conflicts.

### Error: `Index 'event-descriptions' already exists` (Lesson 11)

**Cause:** Azure AI Search index from a previous run.

**Solution:** This is informational, not an error. The code handles existing indexes gracefully and reuses them.

**Prevention:** No action needed — this message is expected on subsequent runs.

### Notebook kernel dies unexpectedly

**Cause:** Memory exhaustion or incompatible Python version.

**Solution:**
1. Verify Python version: `python --version` (must be 3.12+)
2. Restart the kernel and re-run cells from the top
3. Close other memory-intensive applications

**Prevention:** Use Python 3.12+ and ensure adequate system memory.

> [!WARNING]
> Broken link in README: Issue #525 reported a typo where "agent-framewrok" appeared instead of "agent-framework". This has been fixed, but if you cloned an older version, update your local copy with `git pull`.

> [!CAUTION]
> Do not commit your `.env` file to version control. It may contain API keys and secrets. The repository's `.gitignore` already excludes `.env` files.

## 7. FAQ

**Q: What Azure services do I need to run the course?**

You need an Azure subscription with access to Azure AI Foundry. Create a Hub and Project, then deploy a model (such as `gpt-4o`). For Lesson 5, you also need an Azure AI Search resource. Most authentication is handled through `az login` — no API keys needed for the core lessons.

**Q: Can I run the course without Azure?**

Some lessons (6, 8, 14) support GitHub Models as an alternative provider. Set `GITHUB_TOKEN` and `GITHUB_ENDPOINT` in your `.env`. For Lesson 14, MiniMax and OpenAI are also supported. However, the core lessons using Azure AI Foundry require an Azure subscription.

**Q: Do I need both Python and .NET installed?**

No. Python samples and C# samples are independent. If you only want to use one language, install only that runtime. Python 3.12+ is sufficient for all Python notebooks; .NET 10 SDK is needed only for the C# code samples.

**Q: Why is the repository so large (~3 GB)?**

The repository contains translated content in 40+ languages and translated images. Use a shallow clone (`--depth 1`) or sparse checkout to download only the lessons you need.

**Q: What models are supported?**

The samples work with any model deployed through Azure AI Foundry (e.g., `gpt-4o`, `gpt-4o-mini`). GitHub Models and MiniMax models (`MiniMax-M2.7`) are also supported for specific lessons. The default model is typically `gpt-4o` or `gpt-4o-mini`.

**Q: How do I switch from Azure AI Foundry to GitHub Models?**

Set these environment variables in your `.env`:
- `GITHUB_TOKEN` — your GitHub personal access token
- `GITHUB_ENDPOINT` — `https://models.inference.ai.azure.com` (default)
- `GITHUB_MODEL_ID` — e.g., `gpt-4o-mini`

The `OpenAIChatClient`-based samples auto-detect GitHub Models when `GITHUB_TOKEN` is present.

**Q: What is the Microsoft Agent Framework (MAF)?**

MAF is Microsoft's framework for building AI agents. It provides `AIAgent`, `AgentThread`, `WorkflowBuilder`, and related classes for creating agents with tools, managing conversations, and orchestrating multi-agent workflows. It integrates with Azure AI Foundry, GitHub Models, OpenAI, and other OpenAI-compatible providers.

**Q: What is MCP and how is it used in this course?**

MCP (Model Context Protocol) is a protocol for communication between AI agents and tools. Lesson 11 demonstrates how MCP's streaming, resumability, elicitation (human input), and sampling (AI input) capabilities enable complex agent-to-agent communication systems.

**Q: Can I contribute to this course?**

Yes. The repository accepts contributions. See the course's GitHub page for contribution guidelines. Community issue #503 shows an example of a content contribution proposal.

---

_Generated May 2026 from microsoft/ai-agents-for-beginners at dff1fab. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._