How azure-samples/get-started-with-ai-agents works
Project type and purpose
• This is a full-stack, web-based chat application (“Agents Using Azure AI Foundry”)
• Frontend: React/TypeScript SPA
• Backend: Python FastAPI (uvicorn/gunicorn) in a container
• Infra as Code: Azure Bicep templates for Container Apps, Storage, AI Foundry, AI Services, Monitoring
• Features: AI agent with file-based retrieval, semantic search, built-in tracing/monitoring, CI/CD evaluation, red-teaming
File structure
Top-level directories:
• infra/… (Bicep modules for core infra: AI, database, gateway, host, monitor, networking, security, storage)
• src/api/… (Python entry point, routes, search index manager, static assets, templates)
• src/frontend/… (React app, components, theming, build config)
• evals/… (local evaluation scripts, test queries)
• airedteaming/… (AI Red-Teaming script)
• scripts/… (credential and env setup)
• docker-compose.yaml, azure.yaml, pyproject.toml, requirements.txt
Extract architectural insights from README
• User input → Azure Container App hosts the API + static frontend
• Managed Identity secures access to Azure resources
• AI Agent leverages Azure AI Foundry Project + Azure AI Agent Service (model deployments)
• Knowledge retrieval via OpenAI file search or Azure AI Search Index
• Monitoring via Application Insights, Azure Monitor, Log Analytics
• Deployment via Azure Developer CLI (azd), GitHub Codespaces, Dev Containers, local dev
a. Main components
• Client: Web browser running React SPA
• Azure Container App: hosts FastAPI backend + serves compiled React static files
• Azure AI Foundry Project & Agent Service: model endpoints (gpt-4o-mini, embeddings, agent orchestrator)
• Azure AI Search Service (optional): semantic vector index for retrieval
• Azure Storage Account: blob store for uploaded files, embeddings.csv
• Monitoring & Logging: Application Insights, Azure Monitor + Log Analytics Workspace
• Identity & Config: Managed Identity, Key Vault, Azure App Configuration
• CI/CD: GitHub Actions (ai-evaluation), Azure Developer CLI workflows
b. Relationships and data flow
1. User → React UI → HTTP(S) request to FastAPI endpoints
2. Backend retrieves credentials/config from Key Vault / App Config
3. Backend invokes:
– Azure AI Agent Service (agent.runThread)
– File search API or AI Search index query
4. Agent Service calls model endpoints, fetches context, returns generated message + citations
5. Backend streams response back to client
6. Backend emits telemetry (traces, metrics) to Application Insights / Log Analytics
7. CI/CD pipeline runs evals/evaluate.py and ai-red-teaming.py against live agent
c. Architectural patterns and principles
• Separation of concerns: UI vs. API vs. infra resources
• Infrastructure as code: modular Bicep files for reusable resource definitions
• Managed Identity for least-privilege access
• Asynchronous streaming for chat responses
• Pluggable retrieval: file search vs. vector search
• Observability-first: tracing hooks in routes, continuous evaluation
d. Key technologies and frameworks
• Frontend: React, Vite, TypeScript
• Backend: FastAPI, Uvicorn/Gunicorn, Python, Azure SDKs
• Infra: Azure Bicep, Azure Developer CLI (azd)
• AI Services: Azure AI Agent Service, Azure AI Search, OpenAI embeddings
• Monitoring: Application Insights, Azure Monitor, Log Analytics
• CI/CD: GitHub Actions (including ai-evaluation.yaml)