██████╗ ██████╗ ██████╗ ███████╗ ████████╗ ██████╗ ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ╚══██╔══╝██╔═══██╗ ██║ ██║ ██║██║ ██║█████╗ ██║ ██║ ██║ ██║ ██║ ██║██║ ██║██╔══╝ ██║ ██║ ██║ ╚██████╗╚██████╔╝██████╔╝███████╗ ██║ ╚██████╔╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═════╝ ██████╗██╗ ██████╗ ██╗ ██╗██████╗ ██╔════╝██║ ██╔═══██╗██║ ██║██╔══██╗ ██║ ██║ ██║ ██║██║ ██║██║ ██║ ██║ ██║ ██║ ██║██║ ██║██║ ██║ ╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝ ╚═════╝╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝
Pre-configured dev environment • Python 3.12 • Azure CLI • Agent Framework • No setup required
An open-source initiative by Code to Cloud
🚀 Start Here · ☁️ Codespaces · 📖 Docs · 💻 Samples · 🏗️ Architecture · 🤝 Contributing
Click to expand
This repository is your comprehensive guide to building production-ready AI agents on Azure with a GitHub-first workflow.
|
Azure AI Foundry |
Agent Framework |
GitHub Actions |
💡 Not Azure DevOps — This repo is GitHub-focused. For Azure DevOps, see Azure DevOps docs.
| Role | What You'll Find |
|---|---|
| AI Engineers | SDK guides, code samples, agent patterns |
| Architects | Reference architectures, landing zones, design checklists |
| DevOps/Platform | IaC templates, deployment pipelines, operational guidance |
| Security Teams | Security best practices, compliance patterns |
⏱️ ~50 minutes from zero to deployed agent
| Step | Guide | Time | What You'll Do |
|---|---|---|---|
| 1 | Prerequisites | 15 min | Install Azure CLI, Python, VS Code |
| 2 | First Agent | 15 min | Build your first AI agent |
| 3 | Deploy | 15 min | Deploy to Azure with azd |
| 4 | Next Steps | 5 min | Multi-agent, observability, production |
💡 Already familiar? Jump to Quick Start or Resources
| Tool | Installation |
|---|---|
| Azure CLI | brew install azure-cli or Download |
| Azure Developer CLI | brew install azd or Download |
| Python 3.10+ | brew install python@3.12 |
| .NET 8+ | brew install dotnet |
# Microsoft Agent Framework (Python)
pip install agent-framework --pre
# Azure AI Foundry SDK
pip install azure-ai-projects azure-identity openai
# GitHub Copilot SDK
pip install github-copilot-sdk# Microsoft Agent Framework (.NET)
dotnet add package Microsoft.Agents.AI --prerelease# Primary: Your Foundry project endpoint (contains models, agents, tools)
export AZURE_AI_FOUNDRY_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
# Optional: If accessing Azure OpenAI directly (legacy pattern)
# export AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com"
# export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o"💡 Foundry-first: Connect to a single Foundry project endpoint to access models, agents, and tools. No need to manage separate Azure OpenAI endpoints.
import asyncio
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
import os
async def main():
# Connect to your Foundry project (single endpoint for everything)
project = AIProjectClient(
endpoint=os.environ["AZURE_AI_FOUNDRY_ENDPOINT"],
credential=DefaultAzureCredential()
)
# Option 1: Use a hosted agent in Foundry (AI Agent Service)
# Agents run inside Foundry with built-in tool orchestration
agent = project.agents.get_agent("my-customer-support-agent")
response = await agent.run("Help me with my order")
# Option 2: Use Agent Framework for local orchestration with Foundry models
from agent_framework.azure import AzureOpenAIResponsesClient
local_agent = AzureOpenAIResponsesClient(
credential=DefaultAzureCredential()
).as_agent(name="LocalAgent", instructions="You are helpful.")
response = await local_agent.run("Hello!")
print(response)
if __name__ == "__main__":
asyncio.run(main())Click to expand file tree
azure-agentic-engineering/
├── 📄 README.md # You are here
├── 📁 docs/
│ ├── 📁 getting-started/ # 🆕 Beginner learning path
│ ├── 📁 architecture/ # Reference architectures
│ ├── 📁 best-practices/ # Development guidelines
│ ├── 📁 deployment/ # Production deployment
│ ├── 📁 sdks/ # SDK decision guides
│ └── 📁 security/ # Security best practices
├── 📁 samples/
│ ├── 📁 agents/ # Agent code examples
│ └── 📁 workflows/ # Multi-agent workflows
├── 📁 infra/
│ └── 📁 bicep/ # Azure IaC templates
└── 📁 .github/
├── 📁 workflows/ # CI/CD pipelines
└── 📄 copilot-instructions.md # Copilot context
🛠️ Developer Tools & SDKs
🤔 "Which SDK should I use?" → Full SDK Decision Guide
| SDK | Purpose | ✅ Use When | ❌ Don't Use When |
|---|---|---|---|
| Agent Framework | Build & orchestrate agents | Multi-agent workflows, graphs | Just chat completions |
| Foundry SDK | Azure AI platform access | Hosted agents, evaluations | Need cloud-agnostic |
| Copilot SDK | Embed Copilot in apps | Developer tools, CLIs | Non-dev domains |
| OpenAI SDK | Direct model inference | Simple chat, compatibility | Need orchestration |
☁️ Platforms & Infrastructure
| Resource | Description | Link |
|---|---|---|
| Microsoft Foundry GitHub | Official Foundry samples and tools | GitHub |
| Azure AI Landing Zones | Enterprise-scale AI infrastructure (Bicep/Terraform) | GitHub |
| Deploy AI in Production | Full-stack production deployment accelerator | GitHub |
| Azure Container Apps | Serverless containers for AI workloads | Docs |
| Azure Kubernetes Service | Enterprise Kubernetes for AI at scale | Docs |
👁️ Observability & Monitoring
| Resource | Description | Link |
|---|---|---|
| Agent 365 Observability | Unified telemetry for agents (OTel-based) | Docs |
| AI Foundry Observability | Tracing and monitoring in Foundry | Docs |
| Azure Monitor | Full-stack monitoring for Azure | Docs |
| Application Insights | APM for AI applications | Docs |
| OpenTelemetry Integration | Distributed tracing for agents | Agent Framework Observability |
🔒 Security & Governance
| Resource | Description | Link |
|---|---|---|
| AI Agent Governance (CAF) | Governance & security across your organization | Docs |
| Foundry Agent Governance | Agent tools governance in AI Foundry | Docs |
| Microsoft Purview | Data governance and compliance | Docs |
| Azure AI Content Safety | Detect harmful content | Docs |
| Microsoft Defender for Cloud | Security posture management | Docs |
| Azure Policy for AI | Governance policies for AI services | Docs |
🔐 Identity & Access
| Resource | Description | Link |
|---|---|---|
| Foundry Authentication | Authentication & authorization in AI Foundry | Docs |
| Microsoft Entra ID | Identity and access management | Docs |
| Managed Identity | Credential-free authentication | Docs |
| Azure Key Vault | Secrets, keys, and certificates | Docs |
| RBAC for AI Services | Role-based access control | Docs |
📊 Management & Operations
| Resource | Description | Link |
|---|---|---|
| Azure Resource Manager | Infrastructure management | Docs |
| Azure Bicep | Infrastructure as Code | Docs |
| Terraform for Azure | Multi-cloud IaC | Registry |
| Azure Cost Management | Monitor and optimize costs | Docs |
🐙 GitHub DevOps for AI
| Resource | Description | Link |
|---|---|---|
| GitHub Actions for Azure | CI/CD workflows for Azure | Marketplace |
| GitHub Copilot SDK | Embed Copilot in developer tools | GitHub |
| Azure Developer CLI (azd) | End-to-end deployment automation | Docs |
| GitHub Codespaces | Cloud dev environments | Docs |
| Copilot for Azure | AI-assisted Azure management | Docs |
📐 Architecture References
| Resource | Description | Link |
|---|---|---|
| Azure Architecture Center | 27+ AI/ML reference architectures | Browse |
| Well-Architected Framework | AI workload best practices | Docs |
| Cloud Adoption Framework | AI adoption guidance | Docs |
| Guide | Description |
|---|---|
| 🆕 Getting Started | Step-by-step beginner learning path (~50 min) |
| Architecture Best Practices | Reference architectures and design patterns |
| Agent Development | Best practices for building agents |
| Production Deployment | Deploying AI applications to production |
| Security Best Practices | Security guidelines for AI applications |
| SDK Reference | Overview of available SDKs |
| Principle | Description |
|---|---|
| 🔒 Security First | Private endpoints, managed identities, RBAC by default |
| 📈 Scalability | Design for horizontal scaling with Azure Container Apps or AKS |
| 🔄 Resilience | Implement retry policies, circuit breakers, graceful degradation |
| 👁️ Observability | OpenTelemetry integration, distributed tracing, structured logging |
| 💰 Cost Awareness | Right-size resources, implement auto-scaling, monitor token usage |
An AI Landing Zone provides the foundational infrastructure for enterprise AI workloads:
┌──────────────────────────────────────────────────────────────────────────┐
│ Platform Landing Zone │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ AI Landing Zone │ │
│ │ │ │
│ │ Consumers ───▶ ┌──────────────┐ │ │
│ │ (Apps) │ API Mgmt │ ◀── AI Gateway policies │ │
│ │ │ (APIM) │ (token limits, LB, auth) │ │
│ │ └──────┬───────┘ │ │
│ │ │ Private Endpoint │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Azure AI Foundry (Private Endpoint) │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ Models │ │ Agents │ │ Tools │ │ │ │
│ │ │ │ (GPT, etc.) │ │ (AI Agent │ │ (MCP, A2A, │ │ │ │
│ │ │ │ │ │ Service) │ │ Functions) │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │
│ │ └──────────┬──────────────┬──────────────┬───────────────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ AI Search │ │ Storage │ │ Content │ │ │
│ │ │ (Private EP) │ │ (Private EP) │ │ Safety │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Key Vault │ │ Monitoring │ │ Defender │ │ │
│ │ │ (Private EP) │ │ (App Insights)│ │ for Cloud │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
| Component | Purpose |
|---|---|
| API Management (APIM) | AI Gateway for token management, load balancing, auth |
| Azure AI Foundry | Unified platform hosting models, agents (AI Agent Service), and tools |
| AI Agent Service | Hosted agents that run inside Foundry with built-in tool orchestration |
| Azure AI Search | RAG and knowledge retrieval (private endpoint) |
| Content Safety | Detect and filter harmful content |
| Storage | Data lake for AI workloads (private endpoint) |
| Key Vault | Secrets management (private endpoint) |
| Monitoring | Observability & logging |
| Networking | Private endpoints & VNets |
| Defender for Cloud | Security posture management |
🔌 When to Use APIM AI Gateway with Azure AI Foundry
📢 New! AI Gateway can now be integrated directly into Microsoft Foundry, enabling governance of AI models, agents, and tools from within your Foundry environment.
The AI Gateway in Azure API Management provides capabilities specifically designed for AI workloads. Use it when you need:
| Capability | What APIM AI Gateway Provides |
|---|---|
| Token Rate Limiting | azure-openai-token-limit policy - limit TPM per consumer, app, or team |
| Token Quotas | Hourly/daily/weekly/monthly/yearly quotas per subscription |
| Load Balancing | Round-robin, weighted, priority-based across multiple Foundry endpoints |
| Semantic Caching | Cache completions based on semantic similarity (reduces costs) |
| Circuit Breaker | Auto-failover when backends return errors or are overloaded |
| Content Safety | Apply Azure AI Content Safety policies to moderate prompts |
| Token Metrics | llm-emit-token-metric policy for observability per consumer |
| PTU Optimization | Prioritize Provisioned Throughput Units before pay-as-you-go |
| Scenario | Use APIM? | Reason |
|---|---|---|
| Multiple apps sharing AI endpoints | ✅ Yes | Prevent one app from consuming all TPM quota |
| Multi-tenant SaaS | ✅ Yes | Token quotas per tenant, usage tracking for billing |
| PTU + PAYG hybrid | ✅ Yes | Priority routing to PTU, overflow to pay-as-you-go |
| Multiple Foundry regions | ✅ Yes | Load balancing, failover across regions |
| Reduce costs with caching | ✅ Yes | Semantic caching avoids redundant API calls |
| Centralized auth (no API keys) | ✅ Yes | Managed identity, OAuth, remove key sprawl |
| Single internal app, direct access | Adds latency; direct Foundry access may suffice | |
| Prototype / dev environment | ❌ No | Unnecessary complexity for early stages |
📖 Learn more:
🚀 Ready to deploy an enterprise AI Landing Zone?
|
Enterprise Bicep/Terraform |
Full Stack (~45 min) |
Reference Patterns |
Microsoft Agent Framework
# pip install agent-framework --pre
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import DefaultAzureCredential
# Uses AZURE_AI_FOUNDRY_ENDPOINT or AZURE_OPENAI_ENDPOINT from environment
agent = AzureOpenAIResponsesClient(
credential=DefaultAzureCredential()
).as_agent(name="MyAgent", instructions="You are helpful.")
response = await agent.run("Hello, Azure AI!")
Azure AI Foundry SDK (Hosted Agents)
# pip install azure-ai-projects azure-identity openai
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
import os
# Connect to Foundry project (single endpoint for models, agents, tools)
project = AIProjectClient(
endpoint=os.environ["AZURE_AI_FOUNDRY_ENDPOINT"],
credential=DefaultAzureCredential()
)
# Access a hosted agent (runs inside Foundry)
agent = project.agents.get_agent("my-agent-name")
response = await agent.run("What can you help me with?")
# Or access models directly via OpenAI-compatible client
openai_client = project.inference.get_azure_openai_client(api_version="2024-10-21")
Deploy with Azure Developer CLI
# Clone the production accelerator
git clone --recurse-submodules \
https://github.com/microsoft/Deploy-Your-AI-Application-In-Production.git
# Deploy (~45 minutes)
cd Deploy-Your-AI-Application-In-Production
azd up# From this repo
cd infra/bicep
az deployment group create -g myRG -f main.bicep -p principalId=$(az ad signed-in-user show --query id -o tsv)Before deploying to production:
- Using
DefaultAzureCredential(no API keys) - Private endpoints enabled
- Key Vault for any secrets
- RBAC with least privilege
- Diagnostic logging enabled
- Content Safety integrated
📖 Security Best Practices Guide
We welcome contributions! See our Contributing Guide for details.
# Quick contribution workflow
git checkout -b feature/my-feature
# Make changes
git commit -m "feat: add my feature"
git push origin feature/my-feature
# Open a Pull RequestThis project is licensed under the MIT License - see the LICENSE file for details.
An open-source initiative helping developers succeed on Microsoft Azure
Built with ❤️ by Code to Cloud for the Azure AI Community
If this repo helped you, consider giving it a ⭐!