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

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)

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

Sparse Checkout (Keep Only Specific Lessons)

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.

---

Create and Activate a Python 3.12 Virtual Environment

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

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

.venv\Scripts\activate          # Windows

Verify your Python version:

python --version

---

Install Python Dependencies

Install all required packages from the requirements.txt file at the repository root:

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

cp .env.example .env

Step 2: Edit .env with Your Values

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.

---

Authenticate with Azure CLI

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

az login

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

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:

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.

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

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:

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.

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