How skan0779/azure-agent works
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: app.py API app · graph.py Agent graph · manager.py Session manager · main.py Worker entry
Components 21
Runtime
Deployed application processes and request/job flow
- API entry · HTTP/SSE entrypoint for clients
src/azure_agent/api/main.py - API app · FastAPI application wiring and middleware
src/azure_agent/api/app.py - Health routes · Health and ping endpoints
src/azure_agent/api/routes/health.py - Job routes · Job submission and status endpoints
src/azure_agent/api/routes/job.py - Stream middleware · Streaming response support for long-running output
src/azure_agent/middlewares/stream.py - Worker entry · Background job consumer and executor
src/azure_agent/worker/main.py - Job queue · Asynchronous decoupling between API and worker
src/azure_agent/jobs/queue.py - Swagger assets · Bundled API documentation assets
src/azure_agent/api/static
Core agent
Shared agent logic used by both API and worker
- Agent graph · Core execution graph for model/tool routing
src/azure_agent/graphs/graph.py - Graph schema · Graph state and node definitions
src/azure_agent/graphs/schema.py - Session manager · Session lifecycle and persistence coordination
src/azure_agent/session/manager.py - Session schema · Session state and data contracts
src/azure_agent/session/schema.py - Session keys · Session identity and lookup keys
src/azure_agent/session/keys.py
Platform
Azure integrations, persistence, prompts, and deployment
- Redis adapter · Redis connectivity for queueing and checkpointing
src/azure_agent/infra/redis.py - Key Vault · Secret resolution from Azure Key Vault
src/azure_agent/infra/key_vault.py - Runtime config · Non-secret runtime configuration
src/azure_agent/config/runtime.py - Secret config · Secret and vault-backed configuration
src/azure_agent/config/secrets.py - Prompts · Local and blob-backed prompt files
src/azure_agent/prompts - AI Search tool · Azure AI Search retrieval integration
src/azure_agent/tools/azure_ai_search.py - Deploy env · Docker and compose runtime packaging
environments/deploy - Terraform · Azure infrastructure provisioning
environments/infra/main.tf
Connections 22
- 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