# azure-samples/get-started-with-ai-agents architecture

> Architecture diagram of the GitHub repository azure-samples/get-started-with-ai-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/get-started-with-ai-agents
- Repository: https://github.com/azure-samples/get-started-with-ai-agents

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Web Browser\n(React SPA)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        ContainerApp["Azure Container App\n(FastAPI + Static Host)"]:::compute
        FastAPI["FastAPI Backend\n(src/api/main.py\nsrc/api/routes.py)"]:::compute
        StaticHost["Static Assets\n(src/api/static/…\nsrc/api/templates/index.html)"]:::compute
        LoggingConf["Logging & Server Config\n(src/gunicorn.conf.py\nsrc/logging_config.py)"]:::infra
        SearchIndexManager["Search Index Manager\n(src/api/search_index_manager.py)"]:::compute
    end

    %% AI Layer
    subgraph "AI Layer"
        AIFoundry["Azure AI Foundry & Agent Service"]:::ai
        ModelEndpoints["Model Endpoints\n(gpt-4o-mini\nembeddings)"]:::ai
    end

    %% Data & Config Layer
    subgraph "Data & Config Layer"
        BlobStorage["Azure Storage Account\n(Blob Storage)"]:::data
        EmbeddingsCSV["Embeddings CSV\n(src/api/data/embeddings.csv\nsrc/data/embeddings.csv)"]:::data
        AISearchService["Azure AI Search Service"]:::data
        KeyVault["Azure Key Vault"]:::infra
        AppConfig["Azure App Configuration"]:::infra
    end

    %% Observability Layer
    subgraph "Observability Layer"
        AppInsights["Application Insights"]:::observability
        LogAnalytics["Log Analytics Workspace"]:::observability
    end

    %% CI/CD & Infra Layer
    subgraph "CI/CD & Infra"
        GitHubActions["GitHub Actions Workflows\n(.github/workflows/ai-evaluation.yaml\n.github/workflows/azure-dev.yml)"]:::infra
        AzureDevCLI["Azure Dev CLI (azd)"]:::infra
        EvalScripts["Local Evaluation Scripts\n(evals/evaluate.py\nevals/eval-queries.json\nevals/eval-action-data-path.json)"]:::infra
        AiredTeaming["AI Red-Teaming Script\n(airedteaming/ai_redteaming.py)"]:::infra
        InfraMain["Infra as Code\n(infra/main.bicep\ninfra/main.parameters.json)"]:::infra
        HostBicep["Container App Module\n(infra/core/host/container-app.bicep)"]:::infra
        AIServiceBicep["AI Services Module\n(infra/core/ai/cognitiveservices.bicep)"]:::infra
        SearchBicep["Search Services Module\n(infra/core/search/search-services.bicep)"]:::infra
        StorageBicep["Storage Module\n(infra/core/storage/storage-account.bicep)"]:::infra
        MonitorBicep["Monitor Modules\n(infra/core/monitor/applicationinsights.bicep\ninfra/core/monitor/loganalytics.bicep)"]:::infra
        SecurityBicep["Security Modules\n(infra/core/security/keyvault.bicep)"]:::infra
        AzureYaml["Deployment Manifests\n(azure.yaml\ndocker-compose.yaml)"]:::infra
    end

    %% Connections
    Browser -->|HTTPS| ContainerApp
    ContainerApp -->|Serves| StaticHost
    ContainerApp -->|Routes| FastAPI
    FastAPI -->|Loads| SearchIndexManager
    FastAPI -->|Reads/Writes| EmbeddingsCSV
    FastAPI -->|Streams| Browser
    ContainerApp -->|Uses Managed Identity| KeyVault
    ContainerApp -->|Uses Managed Identity| AppConfig
    FastAPI -->|Azure SDK| AIFoundry
    AIFoundry -->|Invokes| ModelEndpoints
    FastAPI -->|Query| AISearchService
    FastAPI -->|Blob SDK| BlobStorage
    ContainerApp -->|Emits Telemetry| AppInsights
    ContainerApp -->|Emits Logs| LogAnalytics
    GitHubActions -->|Triggers| InfraMain
    AzureDevCLI -->|Deploys| InfraMain
    GitHubActions -->|Runs| EvalScripts
    GitHubActions -->|Runs| AiredTeaming

    %% Click Events
    click Browser "https://github.com/azure-samples/get-started-with-ai-agents/tree/main/src/frontend/"
    click FastAPI "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/src/api/main.py"
    click FastAPI "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/src/api/routes.py"
    click SearchIndexManager "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/src/api/search_index_manager.py"
    click StaticHost "https://github.com/azure-samples/get-started-with-ai-agents/tree/main/src/api/static/"
    click StaticHost "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/src/api/templates/index.html"
    click EmbeddingsCSV "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/src/api/data/embeddings.csv"
    click EmbeddingsCSV "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/src/data/embeddings.csv"
    click AiredTeaming "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/airedteaming/ai_redteaming.py"
    click EvalScripts "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/evals/evaluate.py"
    click EvalScripts "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/evals/eval-queries.json"
    click EvalScripts "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/evals/eval-action-data-path.json"
    click InfraMain "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/main.bicep"
    click InfraMain "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/main.parameters.json"
    click HostBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/host/container-app.bicep"
    click AIServiceBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/ai/cognitiveservices.bicep"
    click SearchBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/search/search-services.bicep"
    click StorageBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/storage/storage-account.bicep"
    click MonitorBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/monitor/applicationinsights.bicep"
    click MonitorBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/monitor/loganalytics.bicep"
    click SecurityBicep "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/infra/core/security/keyvault.bicep"
    click GitHubActions "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/.github/workflows/ai-evaluation.yaml"
    click GitHubActions "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/.github/workflows/azure-dev.yml"
    click AzureYaml "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/azure.yaml"
    click AzureYaml "https://github.com/azure-samples/get-started-with-ai-agents/blob/main/docker-compose.yaml"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef compute fill:#E8F1FF,stroke:#0B3D91,color:#0B3D91
    classDef data fill:#E6F4EA,stroke:#107C10,color:#107C10
    classDef ai fill:#FFF4E5,stroke:#D27E00,color:#D27E00
    classDef infra fill:#F2F2F2,stroke:#8C8C8C,color:#8C8C8C
    classDef observability fill:#F3E5FF,stroke:#5C2D91,color:#5C2D91
```
