AgentOS

AgentOS is a full-stack workspace for creating authenticated, user-owned AI assistants that answer questions using conversation history, uploaded documents, and optional MCP tools.

The repository demonstrates API design, asynchronous persistence, authentication, LLM integration, production-oriented RAG controls, guardrails, caching, approvals, MCP connectivity, evaluation, operational metrics, and a responsive Next.js product interface. It is not yet a fully deployed or independently audited production platform; workflow orchestration, CI/CD, dashboards, and cloud deployment remain unimplemented.

What is implemented

• FastAPI application with versioned REST endpoints and generated OpenAPI documentation
• User registration, password hashing, JWT login, and authenticated user lookup
• Owner-scoped create, read, update, and delete operations for AI agents
• Google Gemini text generation and streamed text responses
• PostgreSQL persistence through async SQLAlchemy repositories
• Alembic migrations for users, agents, conversations, messages, documents, and vectorized chunks
• Conversation and message history stored per agent
• PDF and plain-text document upload, extraction, overlapping chunking, and Gemini embeddings
• Similarity search with PostgreSQL and pgvector to add document context to chat prompts
• Docker Compose configuration for a local pgvector-enabled PostgreSQL instance
• Input/output guardrails with prompt-injection blocking, secret redaction, and approval gates
• Redis embedding cache and distributed fixed-window API rate limiting
• MCP Streamable HTTP client integration with authenticated tool discovery/execution
• Human-in-the-loop approval records and resume tokens for sensitive chat actions
• Retrieval thresholds, source citations, multi-page ingestion, and complete chunk persistence
• Online relevance and groundedness evaluation records
• Request IDs, structured request logs, Prometheus metrics, and LLM counters
• Isolated unit tests plus database-backed integration capability
• Responsive Next.js App Router frontend with strict TypeScript, accessible components, dark mode, and Playwright flows

Current status

AgentOS is an early backend prototype under active development.

Area	Status
FastAPI application and health endpoints	Implemented
Registration, JWT login, and protected endpoints	Implemented
User-owned agent CRUD	Implemented
Persisted chat and response streaming	Implemented
PDF/TXT ingestion and vector retrieval	Implemented with validation, thresholds, and citations
Guardrails and human approvals	Implemented
Redis cache and rate limiting	Implemented with safe cache fallback
MCP client integration	Implemented; requires configured MCP servers
Evaluation and observability	Implemented
Automated tests	Unit coverage; full integration requires local services
Frontend	Implemented; live integration requires backend services
LangGraph workflow engine	Not used; services remain the orchestrator
Production deployment and CI/CD	Planned

Remaining production work and integration-test gaps are tracked in the roadmap.

Architecture at a glance

Client
  |
FastAPI routes
  |
Service layer
  |-- authentication and JWT
  |-- agent and conversation workflows
  `-- document ingestion and retrieval
  |
Repository layer
  |
PostgreSQL + pgvector

Agent chat also calls Google Gemini for embeddings and generated responses.
Uploaded PDF/TXT files are stored on the local filesystem.

The code is organized as a modular monolith with routes, services, repositories, SQLAlchemy models, and provider-facing LLM classes kept separate. See architecture and system design for details.

Technology

• Python 3.12
• FastAPI and Uvicorn
• Pydantic Settings
• SQLAlchemy 2 async API and asyncpg
• PostgreSQL with pgvector
• Alembic
• Google Gen AI SDK (Gemini generation and embeddings)
• python-jose, Passlib, and bcrypt
• pypdf
• pytest, pytest-asyncio, and HTTPX
• Docker Compose for the local database

The complete implemented-versus-planned breakdown is in Technology Stack.

Run locally

Prerequisites

• Python 3.12
• uv
• Docker with Docker Compose
• A Google Gemini API key
• Optional MCP servers exposing Streamable HTTP endpoints

1. Start PostgreSQL

cd backend
docker compose up -d

This exposes PostgreSQL on host port 5433 and Redis on 6379.

2. Configure the backend

Create backend/.env with values matching your environment:

APP_NAME=AgentOS
ENVIRONMENT=development
JWT_SECRET_KEY=replace-with-a-long-random-secret
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5433/agentos
GEMINI_API_KEY=your-google-gemini-api-key
REDIS_URL=redis://localhost:6379/0
MCP_SERVER_URLS=https://your-mcp-server.example.com/mcp

Do not commit this file. The root .env.example is currently incomplete for the implemented Gemini integration, so the variables above reflect the settings the application actually reads.

3. Install dependencies and migrate

cd backend
uv sync --dev
uv run alembic upgrade head

4. Start the API

uv run uvicorn app.main:app --reload

5. Start the frontend

cd frontend
copy .env.example .env.local
npm install
npm run dev

Open http://localhost:3000. The frontend only exposes the public backend base URL; backend credentials remain server-side.

Useful local URLs:

• API documentation: http://127.0.0.1:8000/docs
• Root status: http://127.0.0.1:8000/
• Versioned health check: http://127.0.0.1:8000/api/v1/health

API surface

All agent and document operations require a bearer token.

Method	Path	Purpose
POST	/api/v1/auth/register	Create a user
POST	/api/v1/auth/login	Obtain a JWT using OAuth2 form fields (username is the email)
GET	/api/v1/auth/me	Return the authenticated user
POST	/api/v1/agents	Create an agent
GET	/api/v1/agents	List the current user's agents
GET	/api/v1/agents/{agent_id}	Get an owned agent
PUT	/api/v1/agents/{agent_id}	Update an owned agent
DELETE	/api/v1/agents/{agent_id}	Delete an owned agent
POST	/api/v1/agents/{agent_id}/chat	Chat and persist the exchange
POST	/api/v1/agents/{agent_id}/chat/stream	Stream a chat response as plain text
POST	/api/v1/agents/{agent_id}/documents	Upload a PDF or TXT document
GET	/api/v1/agents/{agent_id}/documents	List an agent's documents
DELETE	/api/v1/agents/documents/{document_id}	Delete an owned document and its chunks/file
GET	/api/v1/approvals	List the current user's approval requests
POST	/api/v1/approvals/{approval_id}/decision	Approve or reject a pending action
GET	/api/v1/integrations/mcp/tools	Discover configured MCP tools
POST	/api/v1/integrations/mcp/tools/call	Execute an MCP tool as developer/admin
GET	/metrics	Prometheus metrics (excluded from OpenAPI)

Tests

With the database running and backend/.env configured:

cd backend
uv run pytest

The isolated suite covers startup, authentication service behavior, guardrails, chunking, and evaluation. Database, Redis, Gemini, and MCP integration tests require their respective local/external services.

Documentation

• Documentation index
• Architecture
• System design
• Technology stack
• Repository structure
• Roadmap and known limitations

Why this project is useful

AgentOS shows an end-to-end slice of applied AI backend engineering: authentication, ownership boundaries, relational data modeling, asynchronous data access, external model integration, document processing, embeddings, vector retrieval, streaming, migrations, and API contracts. The remaining work is documented openly so reviewers can distinguish implemented engineering from intended direction.