MAF - AG-UI Azure Agent Template

A structured and production-ready template for AI agent development. It combines the Microsoft Agent Framework, AG-UI, CopilotKit UI, and Azure services in a clean structure. The design keeps the frontend, agent logic, tools, and observability separate, so you can build agent-driven apps with minimal setup.

🌟 What is this?

This is a starter template for building AI chat applications with:

• AG-UI Protocol - Standard protocol for AI agent communication (CopilotKit ↔ Agent Framework)
• Azure-native - Built with Azure Services (OpenAI, Cosmos DB, Container Apps, Application Insights, etc.)
• Agent Workflow - Multi-agent orchestration with tools and MCP (Model Context Protocol) integration
• Modern Architecture - Clean separation of concerns with modular folder structure
• Production Features - Auth, persistence, observability, security middleware, CI/CD included

Demo Use Case

The template demonstrates a simple flight price assistant that:

1. Queries flight prices between cities
2. Generates charts/tables for visualization (via MCP Tools)

⚠️ Architecture Note: The example uses two agents (Flight → Chart) to illustrate workflow composition. In real applications, responsibilities can be combined or extended based on system needs.

✨ Features

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              CopilotKit Chat UI                      │    │
│  │         (port 3000)                                  │    │
│  └──────────────────────┬──────────────────────────────┘    │
└─────────────────────────┼───────────────────────────────────┘
                          │ AG-UI Protocol
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Backend (FastAPI)                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              /copilotkit endpoint                    │    │
│  │         (port 8000)                                  │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │           Microsoft Agent Framework                  │    │
│  │                                                      │    │
│  │  ┌─────────────┐  workflow  ┌─────────────┐         │    │
│  │  │ Flight Agent│ ─────────▶ │ Chart Agent │         │    │
│  │  │  (Tool A)   │            │  (Tool B)   │         │    │
│  │  └─────────────┘            └─────────────┘         │    │
│  │                                                      │    │
│  │  Note: Two agents used to demo workflow feature.     │    │
│  │  Single agent with both tools works too!             │    │
│  └─────────────────────────────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │              Azure Cosmos DB                         │    │
│  │         (Conversation Persistence)                   │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Azure Services                            │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐   │
│  │ Azure OpenAI │ │  Cosmos DB   │ │ Application Insights│   │
│  │   (LLM)      │ │ (NoSQL)      │ │   (Monitoring)      │   │
│  └──────────────┘ └──────────────┘ └────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

📁 Project Structure

maf/
├── main.py                     # FastAPI entry point
├── src/
│   ├── services/               # 🧠 Core business logic
│   │   ├── agent.py            #    Agent definitions & CopilotKit integration
│   │   ├── tools.py            #    Tool implementations (flight query, chart)
│   │   └── workflow.py         #    Multi-agent workflow orchestration
│   ├── db/                     # 💾 Database layer
│   │   ├── cosmos.py           #    Cosmos DB connection (Azure Identity)
│   │   └── cosmos_chat_store.py#    Chat message persistence for Agent Framework
│   ├── schemas/                # 📋 Data models (Pydantic)
│   │   └── flight.py           #    Flight data schema
│   ├── middleware.py           # 🛡️ Security middleware (prompt injection detection)
│   └── exceptions.py           # ⚠️ Global exception handling
├── tests/                      # 🧪 Unit tests (pytest)
├── frontend/                   # 🎨 Next.js + CopilotKit
│   └── src/app/
│       ├── layout.tsx          #    App layout with CopilotKit provider
│       ├── page.tsx            #    Chat UI component
│       └── api/copilotkit/     #    API route (proxy to backend via AG-UI)
├── terraform/                  # 🏗️ Infrastructure as Code
│   ├── main.tf                 #    Azure resource definitions
│   ├── variables.tf            #    Configurable variables
│   ├── outputs.tf              #    Resource outputs (URLs, keys, etc.)
│   └── README.md               #    Terraform usage guide
├── docker-compose.yml          # 🐳 Local development (one command)
└── Dockerfile                  # 📦 Backend container

🚀 Quick Start

Prerequisites

• Python 3.13 + uv
• Docker & Docker Compose
• Azure CLI (az login)
• Azure OpenAI resource

1. Clone and Configure

git clone https://github.com/xxyckiki/MAF-AGUI-Azure-Template.git
cd MAF-AGUI-Azure-Template

# Copy environment variables
cp .env.example .env

# Edit .env with your Azure OpenAI settings

2. Start with Docker Compose

docker-compose up --build

This starts:

• Backend: http://localhost:8000
• Frontend: http://localhost:3000

3. Open the App

Visit http://localhost:3000 and start chatting!

💻 Development

Backend

uv sync                              # Install dependencies
uv run uvicorn main:app --reload     # Run server
uv run pytest -v                     # Run tests

Frontend

cd frontend
npm install --legacy-peer-deps       # Install dependencies
npm run dev                          # Run dev server

☁️ Azure Deployment

Option 1: Terraform (Recommended - One Command Deployment)

Deploy entire infrastructure with Terraform:

cd terraform

# Configure variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your subscription ID

# Deploy
terraform init
terraform plan
terraform apply

# Get all configuration values (API keys, endpoints, etc.)
terraform output

See terraform/README.md for detailed instructions.

Option 2: Manual Deployment

This template can also be deployed manually using Azure Portal or CLI.

Azure Resources

📚 Tech Stack

• Microsoft Agent Framework - AI Agent orchestration
• CopilotKit - React chat UI + AG-UI protocol
• FastAPI - Python web framework
• Next.js - React framework
• Azure OpenAI - LLM backend
• Azure Cosmos DB - NoSQL database
• OpenTelemetry - Observability

📄 License

Apache 2.0