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:

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

Clone the Repository

Full Clone

git clone https://github.com/microsoft/ai-agents-for-beginners.git
cd ai-agents-for-beginners

Shallow Clone (recommended)

git clone --depth 1 https://github.com/microsoft/ai-agents-for-beginners.git
cd ai-agents-for-beginners

Sparse Checkout (specific lessons only)

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

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

Install Python Dependencies

Create a virtual environment first:

python3.12 -m venv venv

Activate it:

Linux / macOS

source venv/bin/activate

Windows (Command Prompt)

venv\Scripts\activate

Windows (PowerShell)

.\venv\Scripts\Activate.ps1

Install all dependencies:

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 or later:

dotnet --list-sdks

10.0.100 [/usr/share/dotnet/sdk]

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

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

Install Azure CLI

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

Verify Installation

python --version

Python 3.12.x

pip list | grep agent-framework

agent-framework    x.y.z

az account show --query name -o tsv

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
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
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:

cp .env.example .env

The two required variables for most lessons:

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

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.

Lesson-Specific Variables

Some lessons require additional configuration:

Lesson 5 — Agentic RAG (Azure AI Search):

Lessons 6 & 8 — GitHub Models:

Lesson 14 — MiniMax Provider (optional):

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:

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:

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:

#: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.

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 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:

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:

python -m server.server --port 8006

2. In another terminal, start the client:

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:

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:

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

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.