azure-ai-agent-sdk-learning

Setup Guide — Azure AI Agent SDK Learning Repository

This guide walks you through setting up everything you need to run the examples in this repository. Follow the sections relevant to your preferred language (Python, .NET, or both).

Table of Contents

Azure Setup

1. Create an Azure AI Foundry Project

  1. Go to the Azure AI Foundry Portal.
  2. Sign in with your Azure account.
  3. Click + Create project.
  4. Enter a project name (e.g., agent-sdk-learning).
  5. Select or create a Hub (a hub organizes projects and shared resources):
    • Choose your Azure subscription.
    • Select a region (e.g., East US 2, Sweden Central).
    • A new resource group will be created, or select an existing one.
  6. Click Create and wait for provisioning to complete.

💡 Tip: Choose a region that supports the model you plan to deploy (e.g., gpt-4o). Check model availability by region.

2. Deploy a Model

You need a deployed language model for your agents to use. We recommend gpt-4o for the best balance of capability and cost.

  1. In your Azure AI Foundry project, go to Models + endpoints in the left navigation.
  2. Click + Deploy model → Deploy base model.
  3. Select gpt-4o (or gpt-4o-mini for lower cost).
  4. Configure the deployment:
    • Deployment name: gpt-4o (keep it simple — this becomes your MODEL_DEPLOYMENT_NAME).
    • Deployment type: Standard (recommended) or Global Standard.
    • Tokens per minute rate limit: Start with the default; increase if needed.
  5. Click Deploy.

⚠️ Important: Note the exact deployment name — you’ll use it in your environment configuration.

3. Get Your Project Endpoint

  1. In your Azure AI Foundry project, go to Project overview.
  2. Find the Project endpoint — it looks like: 
    https://your-project-name.services.ai.azure.com
  3. Copy this value — it’s your PROJECT_ENDPOINT.

📌 The project endpoint is different from individual model endpoints. The Agent SDK uses the project-level endpoint to manage agents, threads, and runs.

4. Set Up RBAC Permissions

Your Azure identity needs the correct role to use the Agent Service.

# Get your current user's Object ID
az ad signed-in-user show --query id -o tsv

# Assign the "Azure AI User" role on your AI Foundry project
az role assignment create \
  --role "Azure AI User" \
  --assignee "<your-object-id>" \
  --scope "/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.MachineLearningServices/workspaces/<project-name>"

Alternatively, assign the role in the Azure Portal:

  1. Navigate to your AI Foundry project resource in the Azure Portal.
  2. Go to Access control (IAM) → + Add role assignment.
  3. Select Azure AI User and assign it to your user account.

💡 If you created the project, you likely already have Owner or Contributor — but the Azure AI User role is specifically needed for Agent Service operations.

Python Environment Setup

1. Install Python

Download and install Python 3.10 or later from python.org.

Verify your installation:

python --version    # Should show 3.10 or later
pip --version       # Should show pip is installed

2. Create a Virtual Environment

cd "Azure AI Agent SDK/python"

# Create the virtual environment
python -m venv .venv

# Activate it
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Windows (Command Prompt):
.venv\Scripts\activate.bat
# macOS / Linux:
# source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

This installs: | Package | Purpose | |———|———| | azure-ai-projects | Azure AI Agent Service SDK (agents, threads, runs, tools) | | azure-identity | Microsoft Entra ID authentication (DefaultAzureCredential) | | azure-ai-inference | Model inference client (for direct model calls if needed) | | azure-search-documents | Azure AI Search client (for RAG examples) | | python-dotenv | Load environment variables from .env files | | aiohttp | Async HTTP client (required for streaming examples) |

4. Configure Your Environment

# Copy the sample environment file
cp .env.sample .env

# Edit .env with your values
# Windows:
notepad .env
# macOS / Linux:
# nano .env

Fill in your values:

PROJECT_ENDPOINT=https://your-project-name.services.ai.azure.com
MODEL_DEPLOYMENT_NAME=gpt-4o

5. Log In to Azure

The SDK uses DefaultAzureCredential, which picks up your Azure CLI login:

az login

💡 If you have multiple subscriptions, set the correct one:

az account set --subscription "<your-subscription-id>"

.NET Environment Setup

1. Install .NET 8.0 SDK

Download and install the .NET 8.0 SDK from dotnet.microsoft.com.

Verify your installation:

dotnet --version    # Should show 8.0.x or later

2. Restore Packages

cd "Azure AI Agent SDK/dotnet"
dotnet restore

3. Configure Your Environment

You can configure environment variables using user-secrets (recommended for development) or a .env file.

dotnet user-secrets init
dotnet user-secrets set "PROJECT_ENDPOINT" "https://your-project-name.services.ai.azure.com"
dotnet user-secrets set "MODEL_DEPLOYMENT_NAME" "gpt-4o"

Option B: Environment Variables (PowerShell)

$env:PROJECT_ENDPOINT = "https://your-project-name.services.ai.azure.com"
$env:MODEL_DEPLOYMENT_NAME = "gpt-4o"

Option C: Environment Variables (Command Prompt)

set PROJECT_ENDPOINT=https://your-project-name.services.ai.azure.com
set MODEL_DEPLOYMENT_NAME=gpt-4o

4. Log In to Azure

az login

Environment Variables

All examples in this repository use the following environment variables:

Required

Variable Description Example
PROJECT_ENDPOINT Your Azure AI Foundry project endpoint https://my-project.services.ai.azure.com
MODEL_DEPLOYMENT_NAME The name of your deployed model gpt-4o

Optional (for specific examples)

Variable Description Used In
AZURE_SEARCH_ENDPOINT Azure AI Search service endpoint RAG examples (Level 2, Example 02)
AZURE_SEARCH_INDEX_NAME Name of your search index RAG examples (Level 2, Example 02)

🔒 Security: Never commit .env files or secrets to source control. The .env file is listed in .gitignore.

Verification

Run these commands to verify your setup is correct.

Verify Azure Login

# Confirm you're logged in and see your subscription
az account show --query "{name:name, id:id, state:state}" -o table

Verify Python Setup

cd "Azure AI Agent SDK/python"

# Activate the virtual environment
# Windows: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate

# Verify packages are installed
python -c "
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
print('✅ Python SDK installed successfully')
print(f'   azure-ai-projects version: {__import__(\"importlib.metadata\", fromlist=[\"version\"]).version(\"azure-ai-projects\")}')
"

Verify .NET Setup

cd "Azure AI Agent SDK/dotnet"

# Verify the project builds
dotnet build --nologo --verbosity quiet

# If successful, you'll see:
# Build succeeded.

Verify End-to-End Connectivity

# Python — quick connectivity test
cd "Azure AI Agent SDK/python"
python -c "
import os
from dotenv import load_dotenv
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

load_dotenv()
endpoint = os.getenv('PROJECT_ENDPOINT')
if not endpoint:
    print('❌ PROJECT_ENDPOINT not set in .env')
else:
    client = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())
    print(f'✅ Connected to: {endpoint}')
"

Next Steps

Once your setup is verified, head back to the README and start with Level 1: Beginner → 01 Hello Agent.

Happy building! 🚀