---
id: kb-010
title: Technical Documentation - Agent Backend (atomsAgent)
scope:
  type: project
  id: 4sgm
purpose: technical-documentation-backend
tags:
  - backend
  - architecture
  - documentation
topics:
  - engineering
  - python
  - fastapi
version: 1
created: 2025-11-26
updated: 2025-11-26
author: droid-agent
status: final
related_ids:
  - kb-011
  - kb-012
external_refs: []
---

# Technical Documentation - Agent Backend (atomsAgent)

## Architecture Overview

atomsAgent is a production-ready FastAPI service that exposes Claude models on Google Vertex AI with an OpenAI-compatible API. It enables SaaS applications to integrate Claude with custom system prompts, MCP tools, and multi-tenant support.

### System Architecture
- **Framework**: FastAPI 0.121.3 with async/await patterns.
- **AI Models**: Claude on Google Vertex AI (4.5 Sonnet/Haiku, 3.7 Sonnet/Haiku).
- **Database**: Supabase PostgreSQL with Row-Level Security (RLS).
- **Authentication**: WorkOS JWT with a 5-minute permission cache.
- **MCP Integration**: HTTP-based MCP server composition with OAuth support.

---

## File Structure

- **src/atomsAgent/**: Main source code (163 Python files).
  - **api/routes/**: 21 route modules for OpenAI compatibility, MCP management, and more.
  - **services/**: 48 business logic modules for AI clients, prompt orchestration, and storage.
  - **db/**: Database layer with auto-generated Pydantic models and repository patterns.
  - **mcp/**: Integration logic for MCP server composition.
  - **auth/**: JWT validation and permission caching.
  - **cache/**: Redis/Upstash caching layer.
  - **cli/**: Typer-based command-line interface.

---

## Core Services

| Service | Purpose |
|---------|---------|
| **ClaudeAgentClient** | Main Claude API wrapper with streaming support. |
| **PromptOrchestrator** | Resolves a 4-level hierarchy (Platform → Org → User → Workflow). |
| **MCPComposer** | Aggregates multiple MCP servers into a single interface. |
| **ChatHistoryService** | Manages session and message persistence in Supabase. |
| **VertexEmbeddingService** | Generates embeddings via Vertex AI. |
| **SandboxManager** | Executes code in isolated, secure environments. |

---

## API Endpoints

- **OpenAI-Compatible**: `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`.
- **MCP Management**: `/atoms/mcp/register`, `/atoms/mcp/servers`, `/atoms/mcp/tools`.
- **Agent Management**: `/atoms/agents`, `/atoms/conversations`, `/atoms/threads`.
- **Platform Admin**: `/atoms/platform/prompts`, `/atoms/platform/system-prompts`.
- **Global**: `/health`, `/ready`, `/metrics`.

---

## Prompt Orchestration Hierarchy

The system resolves system prompts through four levels of overrides:
1. **Platform**: Default prompt for all users (defined in config).
2. **Organization**: Custom prompts per organization (Supabase).
3. **User**: User-specific customizations (Supabase).
4. **Workflow**: Context-specific overrides (Config/Database).

Final Prompt = Platform + Organization + User + Workflow
