Architecture Overview
High-level system architecture of Agent Studio
Architecture Overview
Agent Studio follows a clean architecture pattern with clear separation between domain logic, infrastructure, and presentation layers.
System Diagram
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENTS │
│ Dashboard (Next.js) │ API Consumers │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ API LAYER (FastAPI) │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Auth │ │ Agents │ │ Workflows │ │ Tools │ │ Calls │ │
│ │ Router │ │ Router │ │ Router │ │ Router │ │ Router │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ │ Middleware │ │
│ │ Rate Limit │ Auth │ Logging │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────────────────┐ ┌─────────────┐ ┌─────────────────────────┐
│ CORE DOMAIN │ │ WORKER │ │ PROVIDERS │
│ ┌─────────────────┐ │ │ (LiveKit) │ │ ┌─────────────────┐ │
│ │ Workflow Runner │ │ │ │ │ │ STT: Deepgram │ │
│ │ Tool Executor │ │ │ Handles │ │ │ Sarvam │ │
│ │ Context Manager │ │ │ Voice │ │ ├─────────────────┤ │
│ │ Handoff Logic │ │ │ Sessions │ │ │ TTS: Cartesia │ │
│ └─────────────────┘ │ │ │ │ │ Sarvam │ │
└─────────────────────────┘ └─────────────┘ │ ├─────────────────┤ │
│ │ LLM: Gemini │ │
│ │ OpenAI │ │
│ └─────────────────┘ │
└─────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ LiveKit │ │
│ │ (Primary) │ │ (Cache) │ │ (WebRTC) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Component Responsibilities
API Layer (src/agent_studio/api/)
- HTTP request handling
- Authentication (JWT + API Keys)
- Rate limiting
- Request validation
- OpenAPI documentation
Core Domain (src/agent_studio/core/)
- Business logic (no framework dependencies)
- Workflow orchestration
- Tool execution engine
- Context management
- Handoff detection
Providers (src/agent_studio/providers/)
- STT/TTS/LLM/VAD abstractions
- Registry pattern for provider management
- BYOK credential handling
Worker (src/agent_studio/worker/)
- LiveKit agent process
- Voice session management
- Real-time audio streaming
Database (src/agent_studio/db/)
- SQLAlchemy ORM models
- Repository pattern
- Alembic migrations
Request Flow
API Request
- Request hits FastAPI router
- Middleware processes (auth, rate limit, logging)
- Dependency injection provides services
- Business logic executes
- Response returned
Voice Call Flow
- Call initiated via API
- LiveKit room created with metadata
- Worker picks up job
- Workflow runner builds agents
- Agents execute with handoffs
- Call ends, results persisted
Deployment Topology
┌──────────────────────────────────────────────────────────────┐
│ Load Balancer │
└──────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ API Pod │ │ API Pod │ │ API Pod │
│ (FastAPI)│ │ (FastAPI)│ │ (FastAPI)│
└──────────┘ └──────────┘ └──────────┘
│ │ │
└───────────────┼───────────────┘
▼
┌──────────────────────────────────────────┐
│ Worker Pool │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │Worker 1│ │Worker 2│ │Worker N│ │
│ └────────┘ └────────┘ └────────┘ │
└──────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Redis │ │ LiveKit │
│ (Primary)│ │ Cluster │ │ Server │
└──────────┘ └──────────┘ └──────────┘