azure-ai-agent-sdk-learning

Azure AI Agent SDK — Complete Learning Repository

A hands-on repository to learn the Azure AI Agent Service SDK from beginner to expert, with both Python and .NET examples. Build, deploy, and orchestrate intelligent AI agents on Azure — complete with tools, RAG, streaming, multi-agent patterns, and production best practices.

Live demo: Open Azure AI Agent SDK Learning

Azure AI Agent SDK — Complete Learning Repository

🎯 What You’ll Learn

Area	Description
Azure AI Agent Service	Understand the fully managed platform for building AI agents on Azure
Build & Deploy Agents	Create agents with tools, ground them in your data, and deploy to production
Orchestration	Coordinate multiple agents for complex workflows
Skill Levels	Progress from Beginner → Intermediate → Expert at your own pace
Dual Language	Every example is available in both Python and .NET

By the end of this learning path, you will be able to design, build, test, and deploy production-grade AI agents using the Azure AI Agent Service SDK.

📋 Prerequisites

Requirement	Details
Azure Subscription	An active subscription with an Azure AI Foundry project created
Python 3.10+	Required for Python examples (download)
.NET 8.0+	Required for .NET examples (download)
Azure CLI	Installed and logged in via `az login` (install guide)
Visual Studio Code	Recommended IDE with Python / C# extensions (download)
Git	For cloning and version control (download)

💡 See SETUP.md for detailed environment setup instructions.

🏗️ Repository Structure

Azure AI Agent SDK/
├── README.md                          # This file — repo overview and learning guide
├── SETUP.md                           # Detailed environment setup instructions
├── Base Instructions.md               # Foundational reference and guidelines
│
├── python/                            # Python SDK examples
│   ├── requirements.txt               # Python dependencies
│   ├── .env.sample                    # Environment variable template
│   ├── beginner/                      # Level 1 examples
│   │   ├── 01_hello_agent.py          # Create your first agent
│   │   ├── 02_agent_with_tools.py     # Add Code Interpreter
│   │   └── 03_file_search_agent.py    # Upload and search files
│   ├── intermediate/                  # Level 2 examples
│   │   ├── 01_function_calling.py     # Custom tool functions
│   │   ├── 02_rag_ai_search.py        # RAG with Azure AI Search
│   │   └── 03_streaming.py            # Real-time streaming responses
│   └── expert/                        # Level 3 examples
│       ├── 01_multi_agent.py          # Multi-agent orchestration
│       ├── 02_openapi_tools.py        # OpenAPI-based tool integration
│       └── 03_production_patterns.py  # Error handling, retries, observability
│
├── dotnet/                            # .NET SDK examples
│   ├── AgentSamples.sln               # Solution file
│   ├── beginner/                      # Level 1 examples
│   ├── intermediate/                  # Level 2 examples
│   └── expert/                        # Level 3 examples
│
├── docs/                              # Additional documentation
│   └── troubleshooting.md             # Common issues and fixes
│
└── presentation/                      # Slide decks and demo materials

🚀 Quick Start

Get your first agent running in under 5 minutes.

Python

# 1. Clone and navigate to the repo
cd "Azure AI Agent SDK/python"

# 2. Create a virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
# source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure your environment
cp .env.sample .env
# Edit .env with your Azure AI Foundry project endpoint and model name

# 5. Log in to Azure
az login

# 6. Run your first agent
python beginner/01_hello_agent.py

.NET

# 1. Navigate to the .NET project
cd "Azure AI Agent SDK/dotnet"

# 2. Restore packages
dotnet restore

# 3. Set your environment variables (or use user-secrets)
# Windows PowerShell:
$env:PROJECT_ENDPOINT = "https://your-project.services.ai.azure.com"
$env:MODEL_DEPLOYMENT_NAME = "gpt-4o"

# 4. Log in to Azure
az login

# 5. Run your first agent
dotnet run --project beginner/HelloAgent

📚 Learning Path

Level 1: Beginner — Scratch to Basics

Start here if you’re new to Azure AI Agent Service. These examples introduce core concepts one at a time.

#	Example	What You’ll Learn
01	Hello Agent	Create your first agent, send a message, and receive a response. Understand agents, threads, messages, and runs.
02	Agent with Tools	Add the Code Interpreter tool so your agent can write and execute Python code for data analysis, math, and chart generation.
03	File Search Agent	Upload files to a vector store and enable the File Search tool so the agent can retrieve and reason over your documents.

Level 2: Intermediate — Building Real Applications

Build on the basics with real-world patterns that power production applications.

#	Example	What You’ll Learn
01	Function Calling	Define custom tool functions that the agent can invoke — connect your agent to live data, APIs, and business logic.
02	RAG with Azure AI Search	Ground your agent in enterprise data using Azure AI Search as a retrieval tool for Retrieval-Augmented Generation.
03	Streaming Responses	Stream agent responses token-by-token for a responsive user experience, handling events and intermediate tool calls.

Level 3: Expert — Production & Scale

Patterns for production-grade agent systems at scale.

#	Example	What You’ll Learn
01	Multi-Agent Orchestration	Coordinate multiple specialized agents that collaborate to solve complex tasks — routing, delegation, and result aggregation.
02	OpenAPI Tools	Connect agents to any external API by providing an OpenAPI/Swagger specification as a tool definition.
03	Production Patterns	Error handling, retry logic, structured logging, observability with Application Insights, graceful degradation, and deployment strategies.

🔧 Key Concepts

Understanding these core concepts is essential for working with the Azure AI Agent Service SDK.

Agents

An Agent is a purpose-built AI entity with a specific model, instructions, and set of tools. Agents are stateless — they don’t retain memory between runs unless you use threads.

📖 Agents documentation

Threads

A Thread is a conversation session between a user and an agent. Threads persist messages and provide context for the agent across multiple interactions.

📖 Threads documentation

Messages

Messages are the individual inputs (user) and outputs (assistant) within a thread. Messages can include text, images, and file references.

📖 Messages documentation

Runs

A Run represents a single invocation of an agent on a thread. The run processes messages, invokes tools, and produces a response.

📖 Runs documentation

Tools

Tools extend agent capabilities beyond text generation:

Tool	Description
Code Interpreter	Execute Python code in a sandboxed environment for math, data analysis, and chart generation
File Search	Search over uploaded documents using vector similarity
Function Calling	Invoke custom functions you define — connect to any API or business logic
Azure AI Search	Enterprise RAG with your own search index for grounded answers
OpenAPI	Call external APIs defined by OpenAPI/Swagger specifications

📖 Tools documentation

Azure AI Foundry and Projects

Azure AI Foundry is the platform for building AI applications on Azure. A Project is a workspace within Foundry that organizes your models, agents, data, and evaluations.

📖 Azure AI Foundry documentation

Model Deployment and Selection

Agents require a deployed language model (e.g., gpt-4o, gpt-4o-mini). Models are deployed within your Azure AI Foundry project and referenced by deployment name.

📖 Model deployment guide

🛠️ Recommended Tools & Resources

Microsoft Resources

Resource	Link
Azure AI Foundry Portal	https://ai.azure.com
Microsoft Learn — Develop AI Agents	https://learn.microsoft.com/training/paths/develop-ai-agents-azure/
Azure AI Agent Service Documentation	https://learn.microsoft.com/azure/ai-services/agents/
Python SDK Reference	https://learn.microsoft.com/python/api/overview/azure/ai-projects-readme
.NET SDK Reference	https://learn.microsoft.com/dotnet/api/azure.ai.projects
GitHub Labs — Azure AI Agents	https://github.com/Azure/azure-ai-agents-labs
Azure SDK for Python (source)	https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects
Azure SDK for .NET (source)	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects

Open Source Tools That Help

Tool	What It Does
LangChain	Orchestration framework for LLM applications — complements Azure agents for complex chains and pipelines
Semantic Kernel	Microsoft’s open-source agent framework with planners, plugins, and memory — integrates natively with Azure
Promptflow	Low-code prompt engineering, evaluation, and deployment toolkit from Microsoft
LiteLLM	Unified API proxy for 100+ LLM providers — useful for testing and local development
Weights & Biases / MLflow	Experiment tracking and evaluation for agent performance and prompt tuning
Streamlit / Gradio	Rapid UI prototyping for agent demos and internal tools
pytest / xUnit	Testing frameworks for validating agent behavior, tool calls, and response quality

🏢 Architecture Overview

The Azure AI Agent Service follows a layered architecture:

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
│              (Python SDK / .NET SDK)                     │
├─────────────────────────────────────────────────────────┤
│                Azure AI Foundry Project                  │
│         (Endpoint, Authentication, RBAC)                 │
├─────────────────────────────────────────────────────────┤
│                     Agent Service                        │
│  ┌───────────┐  ┌───────────┐  ┌──────────────────┐    │
│  │   Agent    │  │  Thread   │  │       Run        │    │
│  │ (model +   │  │ (messages │  │ (execution +     │    │
│  │  tools +   │  │  + state) │  │  tool calls +    │    │
│  │  instruct) │  │           │  │  response)       │    │
│  └───────────┘  └───────────┘  └──────────────────┘    │
├─────────────────────────────────────────────────────────┤
│                       Tools                              │
│  ┌────────────┐ ┌───────────┐ ┌───────────────────┐    │
│  │   Code     │ │   File    │ │    Function       │    │
│  │ Interpreter│ │  Search   │ │    Calling        │    │
│  └────────────┘ └───────────┘ └───────────────────┘    │
│  ┌────────────┐ ┌───────────────────────────────────┐  │
│  │  Azure AI  │ │        OpenAPI Tools              │  │
│  │   Search   │ │   (External API Integration)      │  │
│  └────────────┘ └───────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Flow:

Your application creates an Agent with a model, instructions, and tools via the SDK.
A Thread is created to represent a conversation session.
Messages are added to the thread (user input).
A Run is initiated — the agent processes messages, optionally invokes tools, and generates a response.
The response message is appended to the thread and returned to your application.

Authentication uses Microsoft Entra ID (via DefaultAzureCredential) — no API keys required.

🐛 Troubleshooting

Running into issues? Check the Troubleshooting Guide for solutions to common problems, including:

Authentication and credential errors
Model deployment and quota issues
SDK version compatibility
Tool execution failures
Network and firewall configuration

📄 License

This project is licensed under the MIT License.

Built with ❤️ for learning Azure AI Agent Service