# skan0779/azure-agent architecture

> Architecture diagram of the GitHub repository skan0779/azure-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skan0779/azure-agent
- Repository: https://github.com/skan0779/azure-agent

## Overview

1. **What this repository is**
   - `azure-agent` is a production-oriented Python AI agent template for Azure.
   - The system is split into an **API service** and a **background worker**, with shared agent/session/graph code under `src/azure_agent`.

2. **Top-level runtime shape**
   - The deployed runtime is meant to run as two containers in Azure Container Apps:
     - `azure-agent-api`: external ingress, HTTP/SSE entrypoint
     - `azure-agent-worker`: internal worker, no ingress
   - Docker and `uv` are used for packaging and execution.

3. **API boundary**
   - The API lives in `src/azure_agent/api`.
   - It is built on **FastAPI** and exposes small operational routes such as:
     - health/ping checks
     - job-related endpoints
   - `api/static` includes bundled Swagger UI assets, so API documentation is served locally without external assets.

4. **Request handling and streaming**
   - The API is the client-facing boundary for chat/job interaction.
   - `middlewares/stream.py` and the README references to FastAPI SSE indicate that responses can be streamed back to clients rather than returned only as one-shot JSON.
   - This makes the API the control plane for session creation, job submission, and streamed agent output.

5. **Job orchestration**
   - `jobs/queue.py` and the README’s Redis Streams entry imply an asynchronous job queue between API and worker.
   - The API likely enqueues work; the worker consumes and processes it.
   - This is the main decoupling boundary for long-running or blocking agent execution.

6. **Worker boundary**
   - `src/azure_agent/worker/main.py` is the background process entrypoint.
   - The worker runs the agent execution loop, consumes queued jobs, and persists state/results back into shared stores.
   - In the Azure deployment model, the worker is horizontally scalable independently of the API.

7. **Agent core and graph execution**
   - `src/azure_agent/graphs/graph.py` and `graphs/schema.py` define the agent workflow as a graph, consistent with **LangGraph**.
   - The graph is the core reasoning/execution engine that routes between model calls, tools, memory updates, and safety middleware.
   - This is the central internal subsystem the API and worker both depend on.

8. **Model, tool, and middleware pipeline**
   - The README shows the agent is designed around:
     - Azure AI Foundry / model-router for model selection
     - Azure OpenAI for generation and summarization
     - Azure AI Content Safety for moderation and prompt shield
     - PII filtering and rate limiting middleware
   - These are not separate services in code, but they are important execution-time boundaries in the agent pipeline.

9. **Retrieval and external tools**
   - `tools/azure_ai_search.py` connects the agent to **Azure AI Search** for RAG.
   - The `examples/azure_ai_search` folder contains the index schema and data-loading scripts, which are part of the operational setup for retrieval.
   - The README also mentions optional **Tavily** web search, so the agent can combine enterprise search with web search.

10. **State, memory, and sessions**
   - Session logic is in `src/azure_agent/session`.
   - The design separates:
     - session identity/keys
     - session schema
     - session manager
     - exceptions
   - The README maps memory to two distinct persistence layers:
     - **short-term memory / checkpointing** in Redis
     - **long-term memory** in PostgreSQL
   - This is a key architectural split: transient conversational state vs durable memory.

11. **Infrastructure integrations**
   - `src/azure_agent/infra` contains the Azure-specific adapters:
     - `key_vault.py` for secrets
     - `redis.py` for Redis connectivity
   - `config/runtime.py` and `config/secrets.py` suggest runtime settings are separated from secret resolution, with Azure Key Vault as the source of truth in deployment.

12. **Prompt management**
   - `src/azure_agent/prompts` supports prompt files that can be loaded from Azure Blob Storage, with local files as fallback.
   - This makes prompts deployable and editable outside the container image, which is important for enterprise operations and iteration.

13. **Deployment and environment preparation**
   - `environments/infra/main.tf` indicates infrastructure provisioning with Terraform.
   - `environments/deploy` contains the Dockerfile and compose setup for building/running containers.
   - `environments/env` defines environment variables and Key Vault secret mapping.
   - Together these define the deployment boundary between code, infrastructure, and runtime configuration.

14. **Observability and operational concerns**
   - The README calls out Langfuse for observability.
   - Combined with health routes and separated API/worker roles, the system is designed for production monitoring, tracing, and operational recovery.

15. **How data flows through the system**
   - A client sends a request to the **API**.
   - The API validates session/state, optionally streams results, and enqueues or triggers work.
   - The **worker** consumes the job, executes the **LangGraph agent**, calls models/tools, updates Redis/Postgres-backed state, and returns/streams output.
   - The agent may retrieve enterprise documents from **Azure AI Search**, use prompt files from **Blob Storage**, and read secrets from **Key Vault**.

Main entry points: [`src/azure_agent/api/app.py`](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/app.py) (API app), [`src/azure_agent/graphs/graph.py`](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/graphs/graph.py) (Agent graph), [`src/azure_agent/session/manager.py`](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/manager.py) (Session manager), [`src/azure_agent/worker/main.py`](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/worker/main.py) (Worker entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_api_main["API entry<br/>FastAPI app<br/>[main.py]"]
  node_api_app["API app<br/>ASGI setup<br/>[app.py]"]
  node_api_health["Health routes<br/>ops routes<br/>[health.py]"]
  node_api_job["Job routes<br/>job API<br/>[job.py]"]
  node_stream_mw["Stream middleware<br/>SSE middleware<br/>[stream.py]"]
  node_worker_main["Worker entry<br/>worker process<br/>[main.py]"]
  node_job_queue["Job queue<br/>Redis Streams queue<br/>[queue.py]"]
  node_api_static["Swagger assets<br/>static docs"]
end

subgraph group_core["Core agent"]
  node_agent_graph{{"Agent graph<br/>LangGraph flow<br/>[graph.py]"}}
  node_graph_schema["Graph schema<br/>workflow schema<br/>[schema.py]"]
  node_session_mgr["Session manager<br/>session control<br/>[manager.py]"]
  node_session_schema["Session schema<br/>session model<br/>[schema.py]"]
  node_session_keys["Session keys<br/>keying<br/>[keys.py]"]
end

subgraph group_platform["Platform"]
  node_redis_infra[("Redis adapter<br/>cache adapter<br/>[redis.py]")]
  node_kv_infra[("Key Vault<br/>secret adapter<br/>[key_vault.py]")]
  node_runtime_cfg["Runtime config<br/>settings<br/>[runtime.py]"]
  node_secret_cfg["Secret config<br/>secret mapping<br/>[secrets.py]"]
  node_prompt_store["Prompts<br/>prompt loading"]
  node_search_tool["AI Search tool<br/>retrieval tool<br/>[azure_ai_search.py]"]
  node_deploy_env["Deploy env<br/>container setup"]
  node_infra_tf["Terraform<br/>infra provisioning<br/>[main.tf]"]
end

node_api_main -->|"creates"| node_api_app
node_api_app -->|"mounts"| node_api_health
node_api_app -->|"mounts"| node_api_job
node_api_app -->|"uses"| node_stream_mw
node_api_app -->|"serves"| node_api_static
node_api_job -->|"enqueues"| node_job_queue
node_worker_main -->|"consumes"| node_job_queue
node_worker_main -->|"executes"| node_agent_graph
node_agent_graph -->|"defined by"| node_graph_schema
node_agent_graph -->|"updates"| node_session_mgr
node_session_mgr -->|"stores"| node_session_schema
node_session_mgr -->|"indexes"| node_session_keys
node_session_mgr -->|"persists"| node_redis_infra
node_job_queue -->|"backed by"| node_redis_infra
node_runtime_cfg -->|"separates"| node_secret_cfg
node_secret_cfg -->|"loads from"| node_kv_infra
node_agent_graph -->|"retrieves via"| node_search_tool
node_agent_graph -->|"loads prompts"| node_prompt_store
node_deploy_env -->|"packages"| node_api_main
node_deploy_env -->|"packages"| node_worker_main
node_infra_tf -->|"provisions"| node_kv_infra
node_infra_tf -->|"provisions"| node_redis_infra

click node_api_main "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/main.py"
click node_api_app "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/app.py"
click node_api_health "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/routes/health.py"
click node_api_job "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/routes/job.py"
click node_stream_mw "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/middlewares/stream.py"
click node_worker_main "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/worker/main.py"
click node_job_queue "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/jobs/queue.py"
click node_agent_graph "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/graphs/graph.py"
click node_graph_schema "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/graphs/schema.py"
click node_session_mgr "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/manager.py"
click node_session_schema "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/schema.py"
click node_session_keys "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/keys.py"
click node_redis_infra "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/infra/redis.py"
click node_kv_infra "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/infra/key_vault.py"
click node_runtime_cfg "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/config/runtime.py"
click node_secret_cfg "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/config/secrets.py"
click node_prompt_store "https://github.com/skan0779/azure-agent/tree/main/src/azure_agent/prompts"
click node_search_tool "https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/tools/azure_ai_search.py"
click node_api_static "https://github.com/skan0779/azure-agent/tree/main/src/azure_agent/api/static"
click node_deploy_env "https://github.com/skan0779/azure-agent/tree/main/environments/deploy"
click node_infra_tf "https://github.com/skan0779/azure-agent/blob/main/environments/infra/main.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_main,node_api_app,node_api_health,node_api_job,node_stream_mw,node_worker_main,node_job_queue,node_api_static toneBlue
class node_agent_graph,node_graph_schema,node_session_mgr,node_session_schema,node_session_keys toneAmber
class node_redis_infra,node_kv_infra,node_runtime_cfg,node_secret_cfg,node_prompt_store,node_search_tool,node_deploy_env,node_infra_tf toneMint
```

## Components

### Runtime

Deployed application processes and request/job flow

- [API entry](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/main.py): FastAPI app · HTTP/SSE entrypoint for clients · `src/azure_agent/api/main.py`
- [API app](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/app.py): ASGI setup · FastAPI application wiring and middleware · `src/azure_agent/api/app.py`
- [Health routes](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/routes/health.py): ops routes · Health and ping endpoints · `src/azure_agent/api/routes/health.py`
- [Job routes](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/api/routes/job.py): job API · Job submission and status endpoints · `src/azure_agent/api/routes/job.py`
- [Stream middleware](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/middlewares/stream.py): SSE middleware · Streaming response support for long-running output · `src/azure_agent/middlewares/stream.py`
- [Worker entry](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/worker/main.py): worker process · Background job consumer and executor · `src/azure_agent/worker/main.py`
- [Job queue](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/jobs/queue.py): Redis Streams queue · Asynchronous decoupling between API and worker · `src/azure_agent/jobs/queue.py`
- [Swagger assets](https://github.com/skan0779/azure-agent/tree/main/src/azure_agent/api/static): static docs · Bundled API documentation assets · `src/azure_agent/api/static`

### Core agent

Shared agent logic used by both API and worker

- [Agent graph](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/graphs/graph.py): LangGraph flow · Core execution graph for model/tool routing · `src/azure_agent/graphs/graph.py`
- [Graph schema](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/graphs/schema.py): workflow schema · Graph state and node definitions · `src/azure_agent/graphs/schema.py`
- [Session manager](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/manager.py): session control · Session lifecycle and persistence coordination · `src/azure_agent/session/manager.py`
- [Session schema](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/schema.py): session model · Session state and data contracts · `src/azure_agent/session/schema.py`
- [Session keys](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/session/keys.py): keying · Session identity and lookup keys · `src/azure_agent/session/keys.py`

### Platform

Azure integrations, persistence, prompts, and deployment

- [Redis adapter](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/infra/redis.py): cache adapter · Redis connectivity for queueing and checkpointing · `src/azure_agent/infra/redis.py`
- [Key Vault](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/infra/key_vault.py): secret adapter · Secret resolution from Azure Key Vault · `src/azure_agent/infra/key_vault.py`
- [Runtime config](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/config/runtime.py): settings · Non-secret runtime configuration · `src/azure_agent/config/runtime.py`
- [Secret config](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/config/secrets.py): secret mapping · Secret and vault-backed configuration · `src/azure_agent/config/secrets.py`
- [Prompts](https://github.com/skan0779/azure-agent/tree/main/src/azure_agent/prompts): prompt loading · Local and blob-backed prompt files · `src/azure_agent/prompts`
- [AI Search tool](https://github.com/skan0779/azure-agent/blob/main/src/azure_agent/tools/azure_ai_search.py): retrieval tool · Azure AI Search retrieval integration · `src/azure_agent/tools/azure_ai_search.py`
- [Deploy env](https://github.com/skan0779/azure-agent/tree/main/environments/deploy): container setup · Docker and compose runtime packaging · `environments/deploy`
- [Terraform](https://github.com/skan0779/azure-agent/blob/main/environments/infra/main.tf): infra provisioning · Azure infrastructure provisioning · `environments/infra/main.tf`

## Connections

- API entry → API app: creates · Bootstraps the FastAPI application
- API app → Health routes: mounts · Registers operational health endpoints
- API app → Job routes: mounts · Registers job control endpoints
- API app → Stream middleware: uses · Enables streaming responses
- API app → Swagger assets: serves · Exposes local Swagger UI assets
- Job routes → Job queue: enqueues · Submits work for background processing
- Worker entry → Job queue: consumes · Reads pending jobs from the queue
- Worker entry → Agent graph: executes · Runs the agent workflow
- Agent graph → Graph schema: defined by · Workflow structure and state definitions
- Agent graph → Session manager: updates · Reads and writes session state
- Session manager → Session schema: stores · Uses session data contracts
- Session manager → Session keys: indexes · Resolves session identity and lookup keys
- Session manager → Redis adapter: persists · Uses Redis-backed short-term state
- Job queue → Redis adapter: backed by · Queue and checkpoint infrastructure
- Runtime config → Secret config: separates · Runtime settings and secret resolution are distinct
- Secret config → Key Vault: loads from · Resolves secrets through Key Vault
- Agent graph → AI Search tool: retrieves via · Agent can query enterprise search
- Agent graph → Prompts: loads prompts · Uses deployable prompt templates
- Deploy env → API entry: packages · Builds the API container runtime
- Deploy env → Worker entry: packages · Builds the worker container runtime
- Terraform → Key Vault: provisions · Creates supporting Azure resources
- Terraform → Redis adapter: provisions · Creates shared runtime dependencies
