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

Clone the microsoft/ai-agents-for-beginners repository with a shallow checkout, create a Python 3.12 virtual environment, install dependencies from 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 in the root and the detailed instructions in 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)
• 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.

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

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

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

Windows PowerShell:

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

The 00-course-setup/README.md emphasizes using Python 3.12 specifically to ensure compatibility with the package versions listed in requirements.txt.

Install Dependencies from requirements.txt

With the virtual environment activated, install the project dependencies:

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:

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

cp .env.example .env

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

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:

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:

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 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 explicitly states this requirement because the dependencies in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}