🚀 Azure AI Foundry & Agents Workshop

End-to-End Azure AI Foundry And Agents Development Laboratory

Master Azure AI Foundry and Agents through hands-on experimentation and real-world applications

---

🎯 Getting Started • 📚 Learning Path • 🔧 Setup Guide • 🛠️ Troubleshooting

---

🎯 Mission Statement

This comprehensive laboratory transforms you from an AI enthusiast into an Azure AI Foundry expert. Through progressive, hands-on modules, you'll master:

1. Setup, Authentication, Quick Start
2. Prompting, Embeddings, RAG
3. Agents – File Search, Bing, Azure Functions, Multi-Agent
4. Model Context Protocol (MCP) with Agents
5. AI Red Teaming & Security Testing
6. Agent Framework – Advanced Agent Development
7. Observability & Evaluation
8. AI Language Services with Low-Code Workflows
9. AI Vision with Low-Code Solutions
10. Content Understanding & Document Classification
11. Responsible AI & Content Safety

🎓 Laboratory Format: One day intensive hands-on experience
🎯 Target Audience: Developers, AI practitioners, and solution architects
💡 Learning Approach: Progressive complexity with real-world applications

---

📁 Repository Structure

agentic-ai-lab/
├── 📚 1. initial-setup/           # Start here - Authentication & environment setup
├── 💬 2. chat-rag/               # Chat completion and RAG fundamentals
├── 🤖 3. agents/                 # AI Agents development and tools (includes multi-agent)
├── 🔌 4. agents-with-mcp/        # Model Context Protocol (MCP) integration
├── 🔴 5. ai-red-teaming-agent/   # AI Red Teaming and Security Testing
├── 🤖⚙️ 6. agent-framework/        # Microsoft Agent Framework for advanced agent development
├── 📊 7. observability-and-evaluations/         # Monitoring, evaluation, and quality assurance
├── 🗣️ 8. ai-language/             # AI Language Services with Logic Apps low-code workflows
├── 👁️ 9. ai-vision/               # AI Vision Services with low-code solutions
├── 📄 10. content-understanding/   # Document classification and content extraction
└── 🛡️ 11. responsible-ai/          # Responsible AI, Content Safety, and PII Detection

---

🚀 Getting Started

Step 1: Repository Setup

# Clone the laboratory repository
git clone https://github.com/microsoft/agentic-ai-lab-dotnet.git
cd agentic-ai-lab

# Verify Python version
dotnet --version  # Should be 10.0.0 or higher

Step 2: Azure AI Foundry Setup

1. Create Azure AI Foundry Resource and Project

   To create an AI Foundry resource in the Azure portal follow these instructions:

   • Select this AI Foundry resource link: https://portal.azure.com/#create/Microsoft.CognitiveServicesAIFoundry

   • On the Create page, provide the following information:

   

   Project details	Description
   Subscription	Select one of your available Azure subscriptions.
   Resource group	The Azure resource group that will contain your Azure AI Foundry resource. You can create a new group or add it to a preexisting group.
   Region	The location of your Azure AI service instance. Different locations may introduce latency, but have no impact on the runtime availability of your resource.
   Name	A descriptive name for your Azure AI Foundry resource. For example, MyAIServicesResource.
   Default Project Name	Keep the default project as it is.

   • Keep other settings for your resource as default, read and accept the conditions (as applicable), and then select Review + create.

2. Deploy Required Models & Services

   Model Type	Recommended Models	Purpose
   Chat/Completion	gpt-4o, gpt-4o-mini	Primary reasoning & conversation
   Text Embeddings	text-embedding-3-large	Vector search & RAG

   • On the left Nav Menu of the foundry portal go to Models+endpoints
   • Click Deploy a model button-->Deploy base model
     • Search for the models in the table above , select a model, click confirm and Deploy and connect
     

3. Configure an Azure Search Service

   • Create an Azure AI Search resource in Azure
   • Connect this resource to your AI Foundry project
     • Navigate to your AI Foundry project → Management Center → Connected Resources → Add Connection → Select Azure AI Search
     

4. Configure Grounding with Bing Search

   • Create a new Grounding with Bing Search resource in Azure
   • Connect this resource to your AI Foundry project
     • Navigate to your AI Foundry project → Management Center → Connected Resources → Add Connection → Select Grounding with Bing Search

5. Create Content Understanding Resource

   • Create an Azure AI Content Understanding multi-service resource following the official documentation
   • Ensure the resource is created in a supported region (westus, swedencentral, australiaeast)

6. Configure Environment Variables

   • Copy .env.example to .env in the root directory and update values accordingly
   • This repository expects the .env file to be in the root directory, if you want to store it elsewhere or name it something else, update the load_dotenv() calls in notebooks
   • Many of the Environment Variables needed can be found in the Overview tab of your Azure AI Foundry project or the connected resources in the Management Center tab
   • For example, AZURE_OPENAI variables-

---

📚 Learning Path

Follow this structured learning path to master Azure AI Foundry:

🎯 Phase 1: Foundation (Start Here)

Location: 1. initial-setup/

Notebook	Description
🚀 Quick Start	First AI model interaction

💬 Phase 2: Chat & RAG Fundamentals

Location: 2. chat-rag/

Notebook	Description
💬 Basic Chat Completion	Foundation models and prompting
🔍 Embeddings	Vector representations and similarity
📚 Basic RAG	Retrieval-Augmented Generation

🤖 Phase 3: AI Agents Development

Location: 3. agents/

Notebook	Description
🤖 Agent Basics	Fundamental agent concepts
💻 Code Interpreter	Code execution capabilities
📄 File Search	Document processing
🌐 Bing Grounding	Web search integration
🔍 Agents + AI Search	Enterprise search integration
⚡ Agents + Azure Functions	Serverless integration
👥 Multi-Agent Solution	Collaborative AI systems

🔌 Phase 4: Model Context Protocol (MCP) Integration

Location: 4. agents-with-mcp/

Implementation	Description
🔌 MCP Inventory Agent	Complete working implementation of agents that connect to MCP servers for dynamic tool discovery. Features an intelligent inventory management agent for a cosmetics retailer with automated restock and clearance recommendations. Includes both client and server implementations with interactive chat interface.

🔴 Phase 5: AI Red Teaming & Security Testing (Coming Soon)

Location: 5. ai-red-teaming-agent/

Implementation	Description
🔴 AI Red Teaming Agent	Advanced AI security testing and vulnerability assessment using red teaming methodologies. Features automated adversarial prompt generation, safety evaluation, and comprehensive security analysis of AI systems.

🤖⚙️ Phase 6: Microsoft Agent Framework

Location: 6. agent-framework/

The Microsoft Agent Framework is an open-source development kit that unifies and extends Semantic Kernel and AutoGen into the next-generation foundation for AI agent development. Built by the same teams, it offers two primary capabilities: AI Agents for autonomous decision-making with tool integration and conversation management, and Workflows for orchestrating complex multi-agent processes with type safety and checkpointing. Currently in public preview, it combines AutoGen's simple abstractions with Semantic Kernel's enterprise features while adding robust workflow capabilities.

📖 Official Documentation • 🔗 GitHub Repository • 📚 Complete Guide

🤖 Azure AI Agents (agents/azure_ai_agents/)

Notebook	Description
🤖 Basic Agent Usage	Fundamental agent concepts with automatic lifecycle management
⚙️ Explicit Settings	Agent creation with explicit configuration patterns
🔄 Existing Agent Management	Working with pre-existing agents using agent IDs
💬 Thread Management	Conversation thread continuity and management
🔧 Function Tools	Comprehensive function tool integration patterns
💻 Code Interpreter	Python code execution and mathematical problem solving
📄 File Search	Document-based question answering with file uploads
🌐 Bing Grounding	Web search integration using Bing Grounding

🔌 Model Context Protocol (agents/mcp/)

Implementation	Description
🔌 Azure AI with MCP	Hosted MCP tools with Azure AI Foundry agents (basic, multi-tool, thread-based examples)
🖥️ Agent as MCP Server	Expose Agent Framework agents as MCP servers
🔐 MCP API Key Auth	API key authentication patterns for MCP servers

🔄 Workflows (workflows/)

Category	Description
📚 Start Here	Foundational workflow concepts, executors, edges, agents, streaming
🎯 Orchestration	Sequential and concurrent agent coordination patterns
💾 Checkpointing	State persistence for long-running workflows
👤 Human-in-the-Loop	Interactive approval and feedback patterns
🧠 Magentic	AI-driven multi-agent planning and execution

🛡️ Middleware (middleware/)

Notebook	Description
🔧 Agent & Run Level	Middleware fundamentals and scoping
🔨 Function-Based	Function-based middleware patterns
🏗️ Class-Based	Class-based middleware with inheritance
🎨 Decorator Middleware	@agent_middleware and @function_middleware decorators
💬 Chat Middleware	Message interception and modification
⚠️ Exception Handling	Error handling and recovery patterns
🛑 Termination	Early termination and control flow
🔄 Result Override	Streaming and non-streaming result modification
📦 Shared State	State management with middleware containers

🧠 Context Providers (context_providers/)

Notebook	Description
💾 Azure AI Memory	Agent memory with user fact extraction, tone detection, and persistent context

🧵 Threading & Conversation Management (threads/)

Notebook	Status	Description
💬 Azure AI Thread Serialization	✅	Service-managed threads with cloud storage (~50 bytes serialization)
🔧 Custom Message Store	✅ Tested	Custom ChatMessageStoreProtocol implementation (converted from Python script)
📦 Redis Message Store	⚠️ Requires Redis	Distributed conversation storage with 5 comprehensive examples
🔄 Suspend/Resume Threads	✅ Tested	Service-managed & in-memory thread persistence patterns (converted from Python script)

📊 Observability (observability/)

Notebook	Description
👁️ Agent Observability	Trace LLM calls, tool executions, token usage with Application Insights
💬 Chat Client Observability	Monitor Azure AI chat clients with multiple tools

🎨 Development UI (devui/)

Implementation	Description
🌐 In-Memory Mode	Quick-start web interface for testing agents
📁 Sample Agents	Pre-built examples: Foundry agent, weather agent, spam workflow, fanout workflow

📊 Phase 7: Quality & Operations (Coming Soon)

Location: 7. observability-and-evaluations/

Notebook	Description
👁️ Observability	Monitoring and telemetry
📈 Evaluation	Quality assessment and benchmarking

🗣️ Phase 8: AI Language Services with Low-Code Workflows (Coming Soon)

Location: 8. ai-language/

Implementation	Description
🔤 AI Language Service Lab	Low-code Logic Apps for PII removal, language detection, and translation. Build workflow solutions for processing multilingual customer feedback with privacy compliance and centralized analytics.

👁️ Phase 9: AI Vision Services with Low-Code Solutions (Coming Soon)

Location: 9. ai-vision/

Implementation	Description
👀 AI Vision Lab Guide	Azure AI Vision low-code exercises including OCR, face detection, image analysis, and video indexing using Vision Studio
📓 AI Vision Services Notebook	Hands-on Jupyter notebook for computer vision capabilities

📄 Phase 10: Content Understanding & Document Classification (Coming Soon)

Location: 10. content-understanding/

Implementation	Description
📄 Content Understanding Lab Guide	Azure AI Content Understanding for document classification and field extraction from bundled PDF files
📓 Classifier Notebook	Hands-on Jupyter notebook for building document classifiers and analyzers
🐍 Content Understanding Client	Python client implementation for Azure AI Content Understanding API
📋 Sample Data	Sample PDF documents for testing classification and extraction workflows

🛡️ Phase 11: Responsible AI & Content Safety (Coming Soon)

Location: 11. responsible-ai/

Implementation	Description
🛡️ Responsible AI Lab Guide	Comprehensive exploration of AI safety including manual and automated evaluations, content safety filters, PII detection and masking
📊 Evaluation Data	Manual and automated evaluation datasets for AI model testing
🛡️ Content Safety Data	Bulk datasets for text and image moderation testing
📚 Sample Documents	Corporate documents for PII detection and content analysis exercises

---

🔧 Environment Setup

📋 System Requirements

Essential Components:

• 🐍 .NET 10+ - Latest LTS version
• ☁️ Azure Subscription - Active subscription with Azure AI Foundry access
• 💻 Visual Studio Code - Recommended development environment
• 🛠️ Azure CLI - For resource management
• 📦 Git - Version control

Knowledge Prerequisites:

• ✅ Intermediate .NET / C# programming skills
• ✅ Basic understanding of machine learning concepts
• ✅ Familiarity with REST APIs and web services
• ✅ Experience with Azure services (recommended)

🔧 Development Environment Setup

Visual Studio Code (Recommended)

# Install required extensions
code --install-extension ms-dotnettools.vscode-dotnet-pack

---

🛠️ Troubleshooting & Support

⚡ Common Issues & Solutions

Azure Authentication Issues:

# Recommended: Use Azure CLI authentication
az login --tenant YOUR_TENANT_ID
az account show

# Alternative: Clear cached credentials and re-login
az account clear
az login --tenant YOUR_TENANT_ID
az account show

Note: If you see deprecation warnings about the Azure Account extension in VS Code, use az login in the terminal instead. The Azure Account extension for VS Code has been deprecated in favor of Azure CLI authentication.

📚 Additional Resources

• 📖 Azure AI Foundry Documentation
• 🎥 Video Tutorials
• 💡 Best Practices Guide
• 🔍 GitHub Issues - Report bugs or request features

---

🤝 Community & Contributions

🌟 Ways to Contribute

• 📝 Documentation: Improve clarity and add examples
• 🐛 Bug Reports: Help us identify and fix issues
• 💡 Feature Requests: Suggest new capabilities and improvements
• 🔄 Pull Requests: Contribute code and enhancements

📋 Contribution Guidelines

Please review our Contributing Guide for:

• Code style and formatting standards
• Testing requirements and procedures
• Pull request process and review criteria
• Community guidelines and expectations

---

📄 License & Attribution

License: MIT License
Repository: github.com/microsoft/agentic-ai-lab-dotnet