# How to Set Up AI Agents for Beginners Locally: Complete Setup Guide

> Learn to set up AI agents for beginners locally. Follow our complete guide to clone the repo, install dependencies, authenticate, and run notebooks for a hands on AI experience.

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

---

**Clone the microsoft/ai-agents-for-beginners repository with a shallow checkout, create a Python 3.12 virtual environment, install dependencies from [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt), authenticate with `az login`, configure your `.env` file, and launch Jupyter to run the lesson notebooks.**

The **AI Agents for Beginners** repository from Microsoft is an open-source educational course that teaches AI agent fundamentals, design patterns, and production-ready deployments using the **Microsoft Agent Framework (MAF)** and **Azure AI Foundry**. Setting up the project locally requires cloning the course materials, configuring a Python environment, and establishing Azure credentials so you can execute the interactive Jupyter notebooks. The following steps are derived directly from the [`README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/README.md) in the root and the detailed instructions in [`00-course-setup/README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/00-course-setup/README.md).

## Prerequisites

Before starting, ensure you have the following tools installed:

- **Python 3.12+** (required to match the pinned dependencies in [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt))
- **Git** (for cloning the repository)
- **Azure CLI** (for key-less authentication using **AzureCliCredential**)

## Clone the Repository

To avoid downloading the full ~3 GB commit history and translation assets, use a **shallow clone** with `--depth 1`.

```bash

# Replace <your-username> with your GitHub username or fork URL

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git
cd ai-agents-for-beginners

```

Alternatively, perform a **sparse checkout** to fetch only specific lesson folders (e.g., the setup guide and Lesson 01):

```bash
git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git
cd ai-agents-for-beginners
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

```

The root [`README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/README.md) explains these cloning strategies to minimize disk usage and download time.

## Create and Activate a Python Virtual Environment

The notebooks target **Python 3.12**. Create an isolated environment inside the cloned repository:

**macOS/Linux:**

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

```

**Windows PowerShell:**

```bash
py -3.12 -m venv venv
.\venv\Scripts\Activate.ps1

```

The [`00-course-setup/README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/00-course-setup/README.md) emphasizes using Python 3.12 specifically to ensure compatibility with the package versions listed in [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt).

## Install Dependencies from requirements.txt

With the virtual environment activated, install the project dependencies:

```bash
pip install -r requirements.txt

```

This command installs all packages required to run the MAF-based notebooks and Azure SDK integrations.

## Configure Azure Authentication

The notebooks rely on **AzureCliCredential** for key-less authentication. Install the Azure CLI if you haven't already, then sign in:

```bash

# Install Azure CLI (Linux/macOS example)

curl -sL https://aka.ms/installazurecli | bash

# Sign in interactively

az login

# For headless environments (e.g., GitHub Codespaces)

az login --use-device-code

```

As documented in [`00-course-setup/README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/00-course-setup/README.md), the `az login` step is mandatory because the Python code uses the Azure CLI's cached credentials to connect to Azure AI Foundry without hardcoding API keys.

## Set Up Environment Variables via .env

Copy the provided template and configure your project-specific settings:

```bash
cp .env.example .env

```

Edit the `.env` file to include your Azure AI Foundry endpoint and model deployment name:

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

```

Depending on which lessons you plan to run, you may also need to add variables for **Azure AI Search** (for RAG), **GitHub Models**, or **MiniMax**, as detailed in the Course Setup guide lines 30-73.

## Verify Your Environment

Run a quick sanity check to confirm Python path and Azure configuration:

```bash
python -c "import sys, os; print('Python', sys.version); print('Env loaded', 'AZURE_AI_PROJECT_ENDPOINT' in os.environ)"
az account show

```

If both commands return valid output without errors, your environment is ready.

## Launch and Run Lesson Notebooks

Start Jupyter from the repository root:

```bash
jupyter notebook

```

Navigate to a lesson folder, such as `01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb`, and execute the cells sequentially. The notebooks automatically detect the virtual environment, load variables from `.env`, and use your Azure CLI credentials to connect to the MAF services.

All lesson notebooks follow the naming convention `*-python-agent-framework.ipynb` as specified in the setup documentation.

## Summary

- **Clone efficiently** using `--depth 1` or sparse checkout to save disk space.
- **Use Python 3.12** exclusively to match the [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt) specifications.
- **Authenticate via Azure CLI** (`az login`) to enable key-less credential access for the notebooks.
- **Configure `.env`** with your Azure AI Foundry endpoint and model deployment name before running lessons.
- **Launch Jupyter** from the repo root to ensure the environment and variables load correctly.

## Frequently Asked Questions

### What Python version is required for AI Agents for Beginners?

The course requires **Python 3.12 or higher**. The [`00-course-setup/README.md`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/00-course-setup/README.md) explicitly states this requirement because the dependencies in [`requirements.txt`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/requirements.txt) are pinned to versions compatible with Python 3.12.

### Can I run the notebooks without Azure?

No. The notebooks are built around the **Microsoft Agent Framework (MAF)** and **Azure AI Foundry**, which require Azure credentials. However, you can use **GitHub Models** or **MiniMax** as alternative model providers for certain lessons, though Azure authentication is still recommended for the full course experience.

### How do I avoid downloading the entire repository history?

Use a **shallow clone** with `git clone --depth 1` or a **sparse checkout** using `git clone --filter=blob:none --sparse` followed by `git sparse-checkout set` to download only specific lesson folders. This reduces the download from ~3 GB to under 100 MB.

### Why does the setup require `az login` instead of API keys?

The repository follows Azure security best practices by using **AzureCliCredential**, which retrieves tokens from your Azure CLI session. This eliminates the need to store sensitive API keys in code or environment files, as the SDK automatically handles token refresh and authentication when you run `az login`.