# How to Run AI Agent Examples from the ai-agents-for-beginners Repository

> Learn to run AI agent examples from the microsoft ai-agents-for-beginners repository. Follow our 10-step guide covering setup, configuration, and launching notebooks.

- Repository: [Microsoft/ai-agents-for-beginners](https://github.com/microsoft/ai-agents-for-beginners)
- Tags: how-to-guide
- Published: 2026-04-22

---

**Complete the Microsoft AI Agents for Beginners course setup in 10 steps: clone with shallow history, configure Python 3.12, install dependencies, set Azure AI Foundry credentials, authenticate via Azure CLI, and launch Jupyter notebooks.**

The **ai-agents-for-beginners** repository from Microsoft is a hands-on course featuring dozens of Jupyter notebooks that demonstrate the **Microsoft Agent Framework (MAF)** with **Azure AI Foundry**. This guide walks you through the exact steps to run these AI agent examples locally, with precise commands and file paths from the source code.

---

## Clone the Repository Efficiently

The full repository includes over 3 GB of translation assets. Use **shallow clone** or **sparse checkout** to download only what you need.

### Shallow Clone (Recommended for Most Users)

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

```

### Sparse Checkout (Keep Only Specific Lessons)

```bash
cd ai-agents-for-beginners
git sparse-checkout init --cone
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents 02-explore-agentic-frameworks

```

This approach skips the `translations/` folder entirely. Both methods are documented in [`00-course-setup/README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/00-course-setup/README.md).

---

## Create and Activate a Python 3.12 Virtual Environment

The course requires **Python 3.12**. Create an isolated environment to avoid dependency conflicts.

```bash
python3.12 -m venv .venv
source .venv/bin/activate        # macOS/Linux

.venv\Scripts\activate          # Windows

```

Verify your Python version:

```bash
python --version

```

---

## Install Python Dependencies

Install all required packages from the [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt) file at the repository root:

```bash
pip install -r requirements.txt

```

This installs the **Azure SDKs**, the **agent-framework** package, **Jupyter**, and other dependencies needed to run the AI agent examples.

---

## Configure Azure AI Foundry Credentials

The notebooks connect to **Azure AI Foundry** for model inference. You need two values: your **project endpoint** and **model deployment name**.

### Step 1: Copy the Example Environment File

```bash
cp .env.example .env

```

### Step 2: Edit `.env` with Your Values

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

```

These values are available in your **Azure AI Foundry** project settings. The `.env.example` file and setup instructions are located in [`00-course-setup/README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/00-course-setup/README.md).

---

## Authenticate with Azure CLI

The notebooks use `AzureCliCredential` to authenticate without storing secret keys. Sign in:

```bash
az login

```

For headless environments (SSH, CI/CD), use device code flow:

```bash
az login --use-device-code

```

This authentication step is required before running any notebook that connects to Azure AI Foundry.

---

## Launch Jupyter and Run the AI Agent Examples

Start the Jupyter notebook server:

```bash
jupyter notebook

```

This opens the browser interface. Navigate to a lesson folder and open a notebook:

| Notebook | Path | Description |
|----------|------|-------------|
| First Python Agent | `01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb` | Basic agent with Azure AI Foundry |
| Multi-Provider Agent | `02-explore-agentic-frameworks/code_samples/02-python-agent-framework.ipynb` | Switching providers (MiniMax, etc.) |
| RAG Agent | `05-agentic-rag/code_samples/05-python-agent-framework.ipynb` | Retrieval-Augmented Generation with Azure AI Search |
| Multi-Agent Workflow | `08-multi-agent/code_samples/workflows-agent-framework/python/01.python-agent-framework-workflow-ghmodel-basic.ipynb` | Multi-agent orchestration |

Click **Run** (▶️) on each cell to execute. The final cell in each notebook prints the response from the Azure AI Foundry service.

---

## Minimal Working Example

This Python snippet demonstrates the core pattern used across all notebooks: load environment variables, create an `AzureAIProjectAgentProvider`, and call the model.

```python
import os
from dotenv import load_dotenv
from azure.identity import AzureCliCredential
from agent_framework import AzureAIProjectAgentProvider, Agent

# Load .env values

load_dotenv()

project_endpoint = os.getenv("AZURE_AI_PROJECT_ENDPOINT")
model_name = os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME")

# Azure CLI authentication

credential = AzureCliCredential()

# Create provider for Azure AI Foundry

provider = AzureAIProjectAgentProvider(
    endpoint=project_endpoint,
    deployment_name=model_name,
    credential=credential,
)

# Build and run a simple agent

agent = Agent(name="EchoAgent", provider=provider)
response = agent.chat("Hello, I am an AI agent! Tell me a fun fact.")
print(response)

```

All notebooks in **ai-agents-for-beginners** follow this structure, varying only the **system prompt** and **workflow logic** to demonstrate different agent design patterns.

---

## Summary

Running the **ai-agents-for-beginners** examples requires these key steps:

- **Clone efficiently** with `--depth 1` or sparse checkout to avoid 3 GB of translation files
- **Use Python 3.12** in a dedicated virtual environment
- **Install dependencies** from [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt)
- **Configure Azure AI Foundry** credentials in `.env` (endpoint and deployment name)
- **Authenticate via Azure CLI** (`az login`) for secure, keyless access
- **Launch Jupyter** and execute notebooks from `01-intro-to-ai-agents/` through `08-multi-agent/`

---

## Frequently Asked Questions

### Do I need an Azure subscription to run the examples?

Yes. The notebooks connect to **Azure AI Foundry** for model inference. You need an active Azure subscription with access to the **Azure AI Foundry** service and a deployed model (such as GPT-4o). The `AzureCliCredential` approach eliminates the need to store API keys locally.

### Can I run the notebooks without Jupyter?

Yes. You can convert any notebook to a Python script and execute it directly:

```bash
jupyter nbconvert --to script 01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb --stdout | python

```

This is useful for automated testing or headless environments where browser-based Jupyter is not available.

### What if I don't want to download the full repository?

Use **sparse checkout** to download only specific lesson folders. After the initial clone, run:

```bash
git sparse-checkout init --cone
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents 02-explore-agentic-frameworks

```

This excludes the `translations/` folder (approximately 3 GB) while preserving the code you need to run the ai-agents-for-beginners examples.