Full Stack AI Agent Template

<p align="center"> <a href="https://github.com/vstorm-co/agenticos"> <img src="assets/agenticos-banner-light.png" width="100%" alt="AgenticOS by Vstorm, the Sovereign Agentic AI Layer: AI agents your whole team can use and improve. Open source (Apache-2.0), self-hosted, built on Pydantic AI, with budgets, approvals, guardrails and activity built in. Links to the AgenticOS repository on GitHub."> </a> </p> <p align="center">_{From the team behind this repo: <a href="https://github.com/vstorm-co/agenticos"><b>AgenticOS</b></a>, the Sovereign Agentic AI Layer. AI agents your whole team can use and improve: open source (Apache-2.0), self-hosted, built on Pydantic AI.}</p> <h1 align="center">Full-Stack AI Agent Template</h1> <p align="center"> <i>Production-ready FastAPI + Next.js project generator with AI agents, RAG, and 20+ enterprise integrations.</i> </p> <p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-features">Features</a> • <a href="#-demo">Demo</a> • <a href="https://vstorm-co.github.io/full-stack-ai-agent-template/">Documentation</a> • <a href="https://pypi.org/project/fastapi-fullstack/">PyPI</a> </p> <p align="center"> <a href="https://pypi.org/project/fastapi-fullstack/"><img src="https://img.shields.io/pypi/v/fastapi-fullstack?color=green&logo=pypi&logoColor=white" alt="PyPI"></a> <a href="https://pepy.tech/projects/fastapi-fullstack"><img src="https://static.pepy.tech/badge/fastapi-fullstack/month" alt="PyPI Downloads"></a> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/stargazers"><img src="https://img.shields.io/github/stars/vstorm-co/full-stack-ai-agent-template?style=flat&logo=github&color=yellow" alt="GitHub Stars"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white" alt="Python 3.11+"></a> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/blob/main/LICENSE"><img src="https://img.shields.io/github/license/vstorm-co/full-stack-ai-agent-template?color=blue" alt="License"></a> <img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Coverage"> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/actions/workflows/ci.yml"><img src="https://github.com/vstorm-co/full-stack-ai-agent-template/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-blueviolet?logo=shieldsdotio&logoColor=white" alt="Security Policy"></a> <a href="https://www.bestpractices.dev/projects/12539"><img src="https://www.bestpractices.dev/projects/12539/badge" alt="OpenSSF Best Practices"></a> <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a> <a href="https://x.com/Kacper95682155"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="X"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/vstorm-co/full-stack-ai-agent-template/main/assets/new3/chat_demo_with_tasks.gif" alt="AI chat with live plan & task checklist" width="100%"> </p> <p align="center"> <b>🤖 5 AI Agent Frameworks</b> <i>(Pydantic AI, Pydantic Deep Agents, LangChain, LangGraph, DeepAgents)</i> <br> <b>📄 RAG Pipeline</b> <i>(Milvus, Qdrant, pgvector, ChromaDB)</i> <br> <b>⚡ FastAPI + Next.js 15</b> <i>(WebSocket streaming, real-time chat UI)</i> <br> <b>🔗 Conversation Sharing</b> <i>(direct sharing, public links, admin browser)</i> <br> <b>🔒 Enterprise-Ready</b> <i>(JWT, OAuth, admin panel, Celery, Docker, K8s)</i> </p> <details> <summary><b>Table of Contents</b></summary>

• Quick Start
• Demo
• Screenshots
• Why This Template
• Features
• Architecture
• AI Agent
• RAG
• Observability
• Django-style CLI
• Generated Project Structure
• Configuration Options
• Comparison
• FAQ
• Documentation
• Contributing

</details>

---

Vstorm OSS Ecosystem

This template is part of a broader open-source ecosystem for production AI agents:

Project	Description
AgenticOS	Open-source (Apache-2.0), self-hosted platform to build, share and govern AI agents across a company.
pydantic-deepagents	The modular agent runtime for Python. Claude Code-style CLI with Docker sandbox, browser automation, multi-agent teams, and /improve.
pydantic-ai-shields	Drop-in guardrails for Pydantic AI agents. 5 infra + 5 content shields.
subagents-pydantic-ai	Declarative multi-agent orchestration with token tracking.
summarization-pydantic-ai	Smart context compression for long-running agents.
pydantic-ai-backend	Sandboxed execution for AI agents. Docker + Daytona.

Want the runtime behind this template's AI agents? pydantic-deepagents powers the pydantic_deep framework option — install it standalone with curl -fsSL .../install.sh | bash.

Browse all projects at github.com/vstorm-co

---

🚀 Quick Start

[!TIP] Want to review every option first? The installation guide covers the interactive wizard, non-interactive flags and presets; fastapi-fullstack templates lists every option.

Installation

# pip
pip install fastapi-fullstack

# uv (recommended)
uv tool install fastapi-fullstack

# pipx
pipx install fastapi-fullstack

From zero to a running app

Three steps. The wizard scaffolds the project, make bootstrap brings up the whole backend, and the frontend runs with a single command:

# 1. Generate your project — just answer the wizard's prompts
fastapi-fullstack

# 2. Backend + PostgreSQL up, migrations applied, default admin seeded
cd my_ai_app
make bootstrap

# 3. Frontend (in a second terminal)
cd frontend && bun install && bun dev

What make bootstrap does (= make dev + make seed): builds the backend Docker image, starts the stack via docker-compose.dev.yml, waits for PostgreSQL (pg_isready), applies Alembic migrations, and seeds admin@example.com / admin123. It's idempotent — re-run it anytime.

Then access:

	URL
Backend API	http://localhost:8000
Docs	http://localhost:8000/docs	OpenAPI / Swagger
Admin	http://localhost:8000/admin	admin@example.com / admin123 (after make seed)
Frontend	http://localhost:3000	make dev-frontend (Docker) or cd frontend && bun install && bun dev (local)

Day-to-day commands

make dev           # bootstrap or restart (no admin re-seed)
make seed          # one-shot admin creation (no-op if admin exists)
make dev-down      # stop everything
make dev-logs      # tail container logs
make dev-rebuild   # force-rebuild backend image (after pyproject.toml changes)
make dev-frontend  # start the Next.js container

After the first make bootstrap, day-to-day you just run make dev (skips admin re-seed). Run make help inside the project for the full list.

<details> <summary><b>Other ways to generate (flags, presets, minimal)</b></summary>

Skip the wizard and pass options directly:

# Non-interactive with explicit options
fastapi-fullstack create my_ai_app --database postgresql --frontend nextjs

# Presets for common scenarios (run `fastapi-fullstack templates` for the full list)
fastapi-fullstack create my_ai_app --preset ai-agent           # AI agent with streaming
fastapi-fullstack create my_ai_app --preset production         # Full production setup
fastapi-fullstack create my_ai_app --preset production-saas    # SaaS: billing, teams, admin

# Bare-bones project (PostgreSQL, no Docker/Redis/CI)
fastapi-fullstack create my_ai_app --minimal

</details>

Keeping your project up to date

Your project doesn't get stranded on the template version you generated from. Pull the latest template improvements into your existing project with a real 3-way merge — your customizations are preserved, conflicts are left for you to resolve in your IDE, and the whole thing lands on a dedicated branch so it's fully reversible:

make upgrade-dry-run     # preview what would change (no changes made)
make upgrade             # apply on a `template-upgrade/v…` branch
# resolve any conflicts in your IDE's 3-way merge editor, then:
make upgrade-finalize    # bump the manifest to the new version

Files only you changed are kept, files only the template changed are updated, and new features/migrations are pulled in. By default an upgrade keeps your existing feature set — to also adopt optional features added since your version, use:

make upgrade-new-features   # prompts Yes/No for each new optional feature

One-off flags (e.g. pinning a target version) go through ARGS, and you can always call the CLI directly instead of make:

make upgrade ARGS=--to=0.3.0
uvx fastapi-fullstack@latest upgrade --with-new-features

See the version-upgrade guide for the full walkthrough (including projects generated before upgrade support existed).

Environments

make target	Compose file	When to use
make dev	docker-compose.dev.yml	Local development with hot-reload + bind-mounted source.
make stage	docker-compose.yml	Production-like build (no bind mounts) running on localhost. Sanity-check before deploy.
make prod	docker-compose.prod.yml	Production. Requires backend/.env (copy from backend/.env.example, fill real secrets) + external Nginx using nginx/nginx.conf.

Each env has matching -down, -logs, -rebuild siblings.

[!NOTE] Windows users: make requires GNU Make. Install via Chocolatey (choco install make) or use WSL2 / Git Bash. The Docker workflow is identical across macOS, Linux, and WSL2.

<details> <summary><b>Local backend (no Docker, for IDE breakpoints)</b></summary>

If you want to run the backend on the host while the database stays in Docker:

cd my_ai_app
make install                                                # uv sync + pre-commit hooks

# Start only infrastructure containers
docker compose -f docker-compose.dev.yml up -d db redis    # add 'milvus etcd minio' if RAG

make db-upgrade                                             # apply migrations
make create-admin                                           # interactive
make run                                                    # uvicorn --reload

</details> <details> <summary><b>Production deploy</b></summary>

# On your server
git clone <your-repo>
cd my_ai_app

cp backend/.env.example backend/.env            # fill in real secrets
# Configure your nginx host using nginx/nginx.conf as reference

make prod                                       # builds + starts + migrates
make prod-logs                                  # tail logs

For frontend deployment to Vercel:

cd frontend && npx vercel --prod

In the Vercel dashboard set BACKEND_URL (server-side), plus NEXT_PUBLIC_API_URL, NEXT_PUBLIC_WS_URL (wss://…) and NEXT_PUBLIC_SITE_URL — the NEXT_PUBLIC_* ones are inlined at build time, so they need a redeploy to take effect.

</details>

Using the Project CLI

Each generated project has a CLI named after your project_slug. For example, if you created my_ai_app:

cd backend

# The CLI command is: uv run <project_slug> <command>
uv run my_ai_app server run --reload     # Start dev server
uv run my_ai_app db migrate -m "message" # Create migration
uv run my_ai_app db upgrade              # Apply migrations
uv run my_ai_app user create-admin       # Create admin user

Use make help to see all available Makefile shortcuts.

---

🎬 Demo

CLI generator — configure and scaffold a full-stack AI project in under 60 seconds:

<table> <tr> <td width="50%">

AI chat — streaming responses, tool calls, reasoning, and ask-user pauses:

</td> <td width="50%">

RAG ingestion — drop a document, watch it get chunked, embedded, and answered against:

</td> </tr> </table>

Generated marketing site — public landing page with hero, pricing, blog, and legal pages (enable_marketing_site):

---

📸 Screenshots

AI Chat

The chat UI streams responses over WebSocket and renders each tool call as a purpose-built card.

<table> <tr> <td width="50%">

Plan & tasks — sticky checklist updating live as the agent works through steps.

</td> <td width="50%">

Subagents — live feed and side panel showing each subagent's status and messages.

</td> </tr> <tr> <td width="50%">

Charts — interactive bar/area/line/pie/scatter charts rendered inline.

</td> <td width="50%">

Code execution — run_python shows code + stdout/result in a collapsible card.

</td> </tr> <tr> <td width="50%">

Ask user — agent pauses to ask clarifying questions; card keeps the full transcript.

</td> <td width="50%">

Reasoning — clean thinking view + answered-question history for long agent turns.

</td> </tr> </table>

Auth & Dashboard

<table> <tr> <td width="50%">

Login — split-screen with Google OAuth + email/password, HTTP-only cookie session.

</td> <td width="50%">

Register — same split-screen layout with confirm-password and terms acceptance.

</td> </tr> <tr> <td width="50%">

Dashboard (light) — stat cards, usage timeline, recent activity, onboarding banner.

</td> <td width="50%">

Dashboard (dark) — same view in dark theme; saved per-device.

</td> </tr> </table>

Teams & Knowledge Bases

<table> <tr> <td width="50%">

Workspaces — list of all orgs with plan tier and role; switch or create new workspace.

</td> <td width="50%">

Team management — workspace profile, member list with roles, invite button.

</td> </tr> <tr> <td width="50%">

Knowledge bases — list of RAG collections; toggle active bases, upload documents.

</td> <td width="50%">

Documents & sync sources — preview files, manage Google Drive/S3 connectors, view run logs.

</td> </tr> </table>

Billing & Usage

<table> <tr> <td width="50%">

Billing overview — current plan, seats, storage usage, Customer Portal link.

</td> <td width="50%">

Usage charts — daily credits-spent + call-count charts, by-model token breakdown.

</td> </tr> <tr> <td width="50%">

Credits — balance, immutable transaction ledger, usage sparkline.

</td> <td width="50%">

Subscription & invoices — plan management, invoice list, payment methods — all via Stripe.

</td> </tr> </table>

Profile & Settings

<table> <tr> <td width="50%">

Profile — avatar upload, display name, email, active sessions with per-device revoke.

</td> <td width="50%">

Account & security — password change, "sign out everywhere", account deletion zone.

</td> </tr> <tr> <td width="50%">

Slash commands — toggle built-ins, create custom prompt shortcuts for the chat palette.

</td> <td width="50%">

Appearance — light/dark/system theme + brand color picker (5 presets, saved per-device).

</td> </tr> </table>

Admin Panel

<table> <tr> <td width="50%">

Overview — workspace-wide metrics (users, sessions, conversations, MRR) + activity feed.

</td> <td width="50%">

User management — search by email/name, roles, status, join date, inspect/suspend actions.

</td> </tr> <tr> <td width="50%">

Conversation browser — filter by status/owner, open any conversation read-only.

</td> <td width="50%">

Message ratings — approval rate, daily chart, filterable rating table with comments.

</td> </tr> <tr> <td width="50%">

Stripe events log — webhook event browser with manual replay for debugging.

</td> <td width="50%">

System health — live readiness checks: API, DB, Redis, vector store, LLM, worker, Stripe.

</td> </tr> </table>

Marketing Site

<table> <tr> <td width="50%">

Pricing — three-tier page with monthly/annual toggle; pulls live Stripe plan data.

</td> <td width="50%">

Blog — engineering blog from MDX files; tags, featured posts, author bylines. No CMS needed.

</td> </tr> </table>

Background Tasks, Observability & Channels

<table> <tr> <td width="50%">

Prefect — self-hosted server with RAG, billing, and email flows on cron schedules.

</td> <td width="50%">

Prefect flow runs — per-run history, task timeline, and retry visibility.

</td> </tr> <tr> <td width="50%">

Logfire — distributed tracing: FastAPI, Pydantic AI, DB, Redis, Celery, HTTPX in one timeline.

</td> <td width="50%">

LangSmith — trace viewer for LangChain/LangGraph: chains, token usage, feedback.

</td> </tr> <tr> <td width="50%">

Telegram bot — multi-bot, polling + webhook, per-thread sessions, group concurrency control.

</td> <td width="50%">

API docs — auto-generated OpenAPI / Swagger UI with schemas, auth, and example payloads.

</td> </tr> </table>

---

🎯 Why This Template

Building AI/LLM applications requires more than just an API wrapper. You need:

• Type-safe AI agents with tool/function calling
• Real-time streaming responses via WebSocket
• Conversation persistence and history management
• Production infrastructure - auth, rate limiting, observability
• Enterprise integrations - background tasks, webhooks, admin panels

This template gives you all of that out of the box, with 20+ configurable integrations so you can focus on building your AI product, not boilerplate.

Perfect For

• 🤖 AI Chatbots & Assistants - Pydantic AI or LangChain agents with streaming responses
• 📊 ML Applications - Background task processing with Celery/Taskiq
• 🏢 Enterprise SaaS - Full auth, admin panel, webhooks, and more
• 🚀 Startups - Ship fast with production-ready infrastructure

AI-Agent Friendly

Generated projects include CLAUDE.md and AGENTS.md files optimized for AI coding assistants (Claude Code, Codex, Copilot, Cursor, Zed). Following progressive disclosure best practices - concise project overview with pointers to detailed docs when needed.

They also ship a ready-to-use .claude/ toolkit that adapts to the options you selected:

• Agent Skills (.claude/skills/) — model-invoked playbooks that auto-trigger when relevant: alembic-migration, pytest-suite, agent-tool (framework-aware), frontend-feature, rag-knowledge, background-task (queue-aware), billing-stripe, and channel-bot. Feature-gated — only the skills that match your stack are generated.
• Slash commands (.claude/commands/) — /add-endpoint, /fix-issue, /review.
• Convention rules (.claude/rules/) — architecture, code style, schemas, exceptions/security, testing, and frontend conventions, loaded automatically.

---

✨ Features

<p align="center"> <a href="https://ai.pydantic.dev"><img src="https://img.shields.io/badge/Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a> <a href="https://python.langchain.com"><img src="https://img.shields.io/badge/LangChain-1C3C3C?logo=langchain&logoColor=white" alt="LangChain"></a> <a href="https://langchain-ai.github.io/langgraph/"><img src="https://img.shields.io/badge/LangGraph-005A9C?logo=langchain&logoColor=white" alt="LangGraph"></a> <a href="https://milvus.io"><img src="https://img.shields.io/badge/Milvus-FF6B35?logoColor=white" alt="Milvus"></a> <a href="https://openai.com"><img src="https://img.shields.io/badge/OpenAI-412991?logo=openai&logoColor=white" alt="OpenAI"></a> <a href="https://anthropic.com"><img src="https://img.shields.io/badge/Anthropic-D4A373?logo=anthropic&logoColor=white" alt="Anthropic"></a> <a href="https://ai.google.dev"><img src="https://img.shields.io/badge/Gemini-4285F4?logo=google&logoColor=white" alt="Google Gemini"></a> <a href="https://openrouter.ai"><img src="https://img.shields.io/badge/OpenRouter-6366F1?logoColor=white" alt="OpenRouter"></a> </p> <p align="center"> <a href="https://fastapi.tiangolo.com"><img src="https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white" alt="FastAPI"></a> <a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js_15-000000?logo=next.js&logoColor=white" alt="Next.js 15"></a> <a href="https://react.dev"><img src="https://img.shields.io/badge/React_19-61DAFB?logo=react&logoColor=black" alt="React 19"></a> <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a> <a href="https://tailwindcss.com"><img src="https://img.shields.io/badge/Tailwind_v4-06B6D4?logo=tailwindcss&logoColor=white" alt="Tailwind CSS"></a> <a href="https://www.sqlalchemy.org"><img src="https://img.shields.io/badge/SQLAlchemy-D71F00?logo=sqlalchemy&logoColor=white" alt="SQLAlchemy"></a> </p> <p align="center"> <a href="https://www.postgresql.org"><img src="https://img.shields.io/badge/PostgreSQL-4169E1?logo=postgresql&logoColor=white" alt="PostgreSQL"></a> <a href="https://redis.io"><img src="https://img.shields.io/badge/Redis-DC382D?logo=redis&logoColor=white" alt="Redis"></a> <a href="https://milvus.io"><img src="https://img.shields.io/badge/Milvus-00A1EA?logoColor=white" alt="Milvus"></a> <a href="https://qdrant.tech"><img src="https://img.shields.io/badge/Qdrant-FF6B6B?logoColor=white" alt="Qdrant"></a> <a href="https://www.trychroma.com"><img src="https://img.shields.io/badge/ChromaDB-FF6F61?logoColor=white" alt="ChromaDB"></a> <a href="https://docs.celeryq.dev"><img src="https://img.shields.io/badge/Celery-37814A?logo=celery&logoColor=white" alt="Celery"></a> <a href="https://www.prefect.io"><img src="https://img.shields.io/badge/Prefect-070E10?logo=prefect&logoColor=white" alt="Prefect"></a> <a href="https://logfire.pydantic.dev"><img src="https://img.shields.io/badge/Logfire-E92063?logo=pydantic&logoColor=white" alt="Logfire"></a> <a href="https://sentry.io"><img src="https://img.shields.io/badge/Sentry-362D59?logo=sentry&logoColor=white" alt="Sentry"></a> <a href="https://prometheus.io"><img src="https://img.shields.io/badge/Prometheus-E6522C?logo=prometheus&logoColor=white" alt="Prometheus"></a> </p> <p align="center"> <a href="https://www.docker.com"><img src="https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white" alt="Docker"></a> <a href="https://kubernetes.io"><img src="https://img.shields.io/badge/Kubernetes-326CE5?logo=kubernetes&logoColor=white" alt="Kubernetes"></a> <a href="https://github.com/features/actions"><img src="https://img.shields.io/badge/GitHub_Actions-2088FF?logo=githubactions&logoColor=white" alt="GitHub Actions"></a> <a href="https://aws.amazon.com/s3/"><img src="https://img.shields.io/badge/S3-569A31?logo=amazons3&logoColor=white" alt="S3"></a> </p>

🤖 AI/LLM First

• 5 AI Frameworks - Pydantic AI, Pydantic Deep Agents, LangChain, LangGraph, DeepAgents
• 5 LLM Providers - OpenAI, Anthropic, Google Gemini, OpenRouter, and any OpenAI-compatible gateway or server
• RAG - Document ingestion, vector search, reranking (Milvus, Qdrant, ChromaDB, pgvector)
• WebSocket Streaming - Real-time responses with full event access
• Rich Chat UI - Specialized tool-call cards (web search, knowledge base, Python, charts, skills), live subagent feed, citation sources panel, plan/task checklist, reasoning view, and in-chat file previews
• Agent Tools - Web search, URL fetch, charts, code execution (run_python), skills, ask_user, plus optional Deep Research (TODO planner + parallel subagents)
• Messaging Channels - Telegram and Slack multi-bot integration with polling, webhooks, per-thread sessions, group concurrency control
• Conversation Sharing - Share conversations with users or via public links, admin conversation browser
• Conversation Persistence - Save chat history to database
• Message Ratings - Like/dislike responses with feedback, admin analytics
• Image Description - Extract images from documents, describe via LLM vision
• Multimodal Embeddings - Provider-aware: OpenAI, Voyage (Anthropic), Gemini (multimodal text + images)
• Document Sources - Local files, API upload, Google Drive, S3/MinIO
• Sync Sources - Per-organization connector management UI (Google Drive, S3/MinIO) with scheduled sync, manual triggers, encrypted credentials, and per-run logs
• Observability - Logfire for Pydantic AI, LangSmith for LangChain/LangGraph/DeepAgents

⚡ Backend (FastAPI)

• FastAPI + Pydantic v2 - High-performance async API
• PostgreSQL (async) - SQLAlchemy 2.0 + Alembic migrations, pgvector-ready
• Authentication - JWT + Refresh tokens, API Keys, OAuth2 (Google)
• Background Tasks - Celery, Taskiq, ARQ, or Prefect
• Django-style CLI - Custom management commands with auto-discovery

🎨 Frontend (Next.js 15)

• React 19 + TypeScript + Tailwind CSS v4
• AI Chat Interface - WebSocket streaming, tool call visualization
• Authentication - HTTP-only cookies, auto-refresh, password reset, magic link
• Marketing Site - hero, pricing, FAQ, blog, contact form, legal pages (PL + EN)
• Billing Dashboard - subscription, payment methods, invoices, credits balance/ledger, and usage charts (Stripe)
• User Settings - profile, API keys CRUD (sk_* tokens), onboarding tracking
• Admin Panel - workspace stats, message-rating analytics, Stripe events browser
• SEO - per-page metadata, OG image, sitemap, robots, manifest, favicons
• Dark Mode + i18n (PL/EN via next-intl, locale-prefixed routes)

🔌 20+ Enterprise Integrations

Category	Integrations
AI Frameworks	Pydantic AI, Pydantic Deep Agents, LangChain, LangGraph, DeepAgents
LLM Providers	OpenAI, Anthropic, Google Gemini, OpenRouter, OpenAI-compatible endpoints
RAG / Vector Stores	Milvus, Qdrant, ChromaDB, pgvector
RAG Sources	Local files, API upload, Google Drive, S3/MinIO, Sync Sources (per-org UI, scheduled)
Embeddings	OpenAI, Voyage, Gemini (multimodal), SentenceTransformers
Background Tasks	Celery, Taskiq, ARQ, Prefect
Billing	Stripe subscriptions (seat-based), credits + usage metering, invoices, Customer Portal
Caching & State	Redis, fastapi-cache2
Security	Per-plan sliding-window rate limiting (per user / org / IP), CORS, SSRF-guarded webhook delivery, httpOnly + SameSite session cookies
Observability	Logfire, LangSmith, Sentry, Prometheus
Admin	SQLAdmin panel with auth
Collaboration	Conversation sharing (direct + link), admin conversation browser
Messaging	Telegram multi-bot (polling + webhook), Slack multi-bot (Events API + Socket Mode)
Events	Webhooks, WebSockets
DevOps	Docker, GitHub Actions, GitLab CI, Kubernetes

🗺️ Architecture Overview

┌──────────────────────────────────────────────────────────────────────────┐
│                         FRONTEND  (Next.js 15)                           │
│  Chat UI · Knowledge Base · Dashboard · Settings · Dark Mode · i18n      │
└──────────────┬───────────────────────────────────────────┬───────────────┘
               │  REST / WebSocket                         │  Vercel
               ▼                                           ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                         BACKEND  (FastAPI)                               │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐     │
│  │                     AI AGENTS                                   │     │
│  │  Pydantic AI · LangChain · LangGraph · DeepAgents               │     │
│  │  ────────────────────────────────────────────────────────────   │     │
│  │  Tools: datetime · web_search (Tavily) · search_knowledge_base  │     │
│  │  Providers: OpenAI · Anthropic · Gemini · OpenRouter            │     │
│  └─────────────────────────────────────────────────────────────────┘     │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐     │
│  │                     RAG PIPELINE                                │     │
│  │                                                                 │     │
│  │  Sources        Parse           Chunk          Embed            │     │
│  │  ─────────      ──────────      ──────────     ──────────────   │     │
│  │  Local files    PyMuPDF         recursive      OpenAI           │     │
│  │  API upload     LiteParse       markdown       Voyage           │     │
│  │  Google Drive   LlamaParse      fixed          Gemini (multi)   │     │
│  │  S3/MinIO       python-docx                    SentenceTransf.  │     │
│  │  Sync Sources                                                   │     │
│  │                                                                 │     │
│  │  Store              Search              Rank                    │     │
│  │  ──────────────     ──────────────      ──────────────          │     │
│  │  Milvus             Vector similarity   Cohere reranker         │     │
│  │  Qdrant             BM25 + vector RRF   CrossEncoder            │     │
│  │  ChromaDB           Multi-collection                            │     │
│  │  pgvector                                                       │     │
│  └─────────────────────────────────────────────────────────────────┘     │
│                                                                          │
│  Auth (JWT/API Key/OAuth) · Rate Limiting · Webhooks · Admin Panel       │
│  Billing (Stripe + credits) · Background Tasks (Celery/Taskiq/ARQ/       │
│  Prefect) · Django-style CLI · Observability (Logfire/LangSmith/         │
│  Sentry/Prometheus)                                                      │
└───────┬──────────────┬──────────────┬──────────────┬─────────────────────┘
        │              │              │              │
        ▼              ▼              ▼              ▼
   PostgreSQL       Redis         Vector DB      LLM APIs
   (async)                        (Milvus/       (OpenAI/
                                  Qdrant/        Anthropic/
                                  ChromaDB/      Gemini)
                                  pgvector)

---

🏗️ Architecture

graph TB
    subgraph Frontend["Frontend (Next.js 15)"]
        UI[React Components]
        WS[WebSocket Client]
        Store[Zustand Stores]
    end

    subgraph Backend["Backend (FastAPI)"]
        API[API Routes]
        Services[Services Layer]
        Repos[Repositories]
        Agent[AI Agent]
    end

    subgraph Infrastructure
        DB[(PostgreSQL)]
        Redis[(Redis)]
        Queue[Celery/Taskiq/ARQ/Prefect]
    end

    subgraph External
        LLM[OpenAI/Anthropic]
        Webhook[Webhook Endpoints]
    end

    UI --> API
    WS <--> Agent
    API --> Services
    Services --> Repos
    Services --> Agent
    Repos --> DB
    Agent --> LLM
    Services --> Redis
    Services --> Queue
    Services --> Webhook

Layered Architecture

The backend follows a clean Repository + Service pattern:

graph LR
    A[API Routes] --> B[Services]
    B --> C[Repositories]
    C --> D[(Database)]

    B --> E[External APIs]
    B --> F[AI Agents]

Layer	Responsibility
Routes	HTTP handling, validation, auth
Services	Business logic, orchestration
Repositories	Data access, queries

See Architecture Documentation for details.

---

🤖 AI Agent

Choose from 5 AI frameworks and 4 LLM providers when generating your project:

# Pydantic AI with OpenAI (default)
fastapi-fullstack create my_app --ai-framework pydantic_ai

# LangGraph with Anthropic
fastapi-fullstack create my_app --ai-framework langgraph --llm-provider anthropic

# DeepAgents with OpenAI
fastapi-fullstack create my_app --ai-framework deepagents

# With RAG enabled
fastapi-fullstack create my_app --rag --database postgresql --task-queue celery

Supported Combinations

Framework	OpenAI	Anthropic	Gemini	OpenRouter	OpenAI-compatible
Pydantic AI	✓	✓	✓	✓	✓
Pydantic Deep Agents	✓	✓	✓	✓	✓
LangChain	✓	✓	✓	-	-
LangGraph	✓	✓	✓	-	-
DeepAgents	✓	✓	✓	-	-

OpenAI-compatible (--llm-provider openai_compatible) reaches any gateway or server that speaks the OpenAI API by its base URL: model routers and LLM gateways (LiteLLM, Requesty, OrcaRouter, Portkey) and self-hosted servers (vLLM, llama.cpp, LM Studio, Ollama). Set OPENAI_COMPATIBLE_BASE_URL, AI_MODEL as the endpoint names it, and OPENAI_COMPATIBLE_API_KEY if it checks one.

Pydantic AI Integration

Type-safe agents with full dependency injection:

# app/agents/assistant.py
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    user_id: str | None = None
    db: AsyncSession | None = None

agent = Agent[Deps, str](
    model="openai:gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
)

@agent.tool
async def search_database(ctx: RunContext[Deps], query: str) -> list[dict]:
    """Search the database for relevant information."""
    # Access user context and database via ctx.deps
    ...

LangChain Integration

Flexible agents with LangGraph:

# app/agents/langchain_assistant.py
from langchain.tools import tool
from langgraph.prebuilt import create_react_agent

@tool
def search_database(query: str) -> list[dict]:
    """Search the database for relevant information."""
    ...

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=[search_database],
    prompt="You are a helpful assistant.",
)

WebSocket Streaming

Both frameworks use the same WebSocket endpoint with real-time streaming:

@router.websocket("/ws")
async def agent_ws(websocket: WebSocket):
    await websocket.accept()

    # Works with both PydanticAI and LangChain
    async for event in agent.stream(user_input):
        await websocket.send_json({
            "type": "text_delta",
            "content": event.content
        })

Observability

Each framework has its own observability solution:

Framework	Observability	Dashboard
Pydantic AI	Logfire	Agent runs, tool calls, token usage
LangChain	LangSmith	Traces, feedback, datasets

See AI Agent Documentation for more.

---

📄 RAG (Retrieval-Augmented Generation)

Enable RAG to give your AI agents access to a knowledge base built from your documents.

Vector Store Backends

Backend	Type	Docker Required	Best For
Milvus	Dedicated vector DB	Yes (3 services)	Production, large scale
Qdrant	Dedicated vector DB	Yes (1 service)	Production, simple setup
ChromaDB	Embedded / HTTP	No	Development, prototyping
pgvector	PostgreSQL extension	No (uses existing PG)	Already have PostgreSQL

Document Ingestion (CLI)

# Local files
uv run my_app rag-ingest /path/to/document.pdf --collection docs
uv run my_app rag-ingest /path/to/folder/ --recursive

# Google Drive (service account)
uv run my_app rag-sync-gdrive --collection docs --folder-id <drive_folder_id>

# S3/MinIO
uv run my_app rag-sync-s3 --collection docs --prefix reports/ --bucket my-bucket

Embedding Providers

Provider	Model	Dimensions	Multimodal
OpenAI	text-embedding-3-small	1536	-
Voyage	voyage-3	1024	-
Gemini	gemini-embedding-exp-03-07	3072	Text + Images
SentenceTransformers	all-MiniLM-L6-v2	384	-

Features

• Document parsing - PDF (PyMuPDF with tables, headers/footers, OCR), DOCX, TXT, MD + 130+ formats via LlamaParse
• Image description - Extract images from documents, describe via LLM vision API (opt-in)
• Chunking - RecursiveCharacterTextSplitter with configurable size/overlap
• Reranking - Cohere API or local CrossEncoder for improved search quality
• Agent integration - All 5 AI frameworks get a search_knowledge_base tool automatically

---

📊 Observability

Logfire (for Pydantic AI)

Logfire provides complete observability for your application - from AI agents to database queries. Built by the Pydantic team, it offers first-class support for the entire Python ecosystem.

graph LR
    subgraph Your App
        API[FastAPI]
        Agent[Pydantic AI]
        DB[(Database)]
        Cache[(Redis)]
        Queue[Celery/Taskiq]
        HTTP[HTTPX]
    end

    subgraph Logfire
        Traces[Traces]
        Metrics[Metrics]
        Logs[Logs]
    end

    API --> Traces
    Agent --> Traces
    DB --> Traces
    Cache --> Traces
    Queue --> Traces
    HTTP --> Traces

Component	What You See
Pydantic AI	Agent runs, tool calls, LLM requests, token usage, streaming events
FastAPI	Request/response traces, latency, status codes, route performance
PostgreSQL	Query execution time, slow queries, connection pool stats
Redis	Cache hits/misses, command latency, key patterns
Celery/Taskiq	Task execution, queue depth, worker performance
HTTPX	External API calls, response times, error rates

LangSmith (for LangChain)

LangSmith provides observability specifically designed for LangChain applications:

Feature	Description
Traces	Full execution traces for agent runs and chains
Feedback	Collect user feedback on agent responses
Datasets	Build evaluation datasets from production data
Monitoring	Track latency, errors, and token usage

LangSmith is automatically configured when you choose LangChain:

# .env
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-api-key
LANGCHAIN_PROJECT=my_project

Configuration

Enable Logfire and select which components to instrument:

fastapi-fullstack new
# ✓ Enable Logfire observability
#   ✓ Instrument FastAPI
#   ✓ Instrument Database
#   ✓ Instrument Redis
#   ✓ Instrument Celery
#   ✓ Instrument HTTPX

Usage

# Automatic instrumentation in app/main.py
import logfire

logfire.configure()
logfire.instrument_fastapi(app)
logfire.instrument_asyncpg()
logfire.instrument_redis()
logfire.instrument_httpx()

# Manual spans for custom logic
with logfire.span("process_order", order_id=order.id):
    await validate_order(order)
    await charge_payment(order)
    await send_confirmation(order)

For more details, see Logfire Documentation.

---

🛠️ Django-style CLI

Each generated project includes a powerful CLI inspired by Django's management commands:

Built-in Commands

# Server
my_app server run --reload
my_app server routes

# Database (Alembic wrapper)
my_app db init
my_app db migrate -m "Add users"
my_app db upgrade

# Users
my_app user create --email admin@example.com --superuser
my_app user list

Custom Commands

Create your own commands with auto-discovery:

# app/commands/seed.py
from app.commands import command, success, error
import click

@command("seed", help="Seed database with test data")
@click.option("--count", "-c", default=10, type=int)
@click.option("--dry-run", is_flag=True)
def seed_database(count: int, dry_run: bool):
    """Seed the database with sample data."""
    if dry_run:
        info(f"[DRY RUN] Would create {count} records")
        return

    # Your logic here
    success(f"Created {count} records!")

Commands are automatically discovered from app/commands/ - just create a file and use the @command decorator.

my_app cmd seed --count 100
my_app cmd seed --dry-run

---

📁 Generated Project Structure

my_project/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI app with lifespan
│   │   ├── api/
│   │   │   ├── routes/v1/       # Versioned API endpoints
│   │   │   ├── deps.py          # Dependency injection
│   │   │   └── router.py        # Route aggregation
│   │   ├── core/                # Config, security, middleware
│   │   ├── db/models/           # SQLAlchemy 2.0 models
│   │   ├── schemas/             # Pydantic schemas
│   │   ├── repositories/        # Data access layer
│   │   ├── services/            # Business logic
│   │   ├── agents/              # AI agents with centralized prompts
│   │   ├── rag/                 # RAG module (vector store, embeddings, ingestion)
│   │   ├── commands/            # Django-style CLI commands
│   │   └── worker/              # Background tasks
│   ├── cli/                     # Project CLI
│   ├── tests/                   # pytest test suite
│   └── alembic/                 # Database migrations
├── frontend/
│   ├── src/
│   │   ├── app/                 # Next.js App Router
│   │   ├── components/          # React components
│   │   ├── hooks/               # useChat, useWebSocket, etc.
│   │   └── stores/              # Zustand state management
│   └── e2e/                     # Playwright tests
├── docker-compose.yml
├── Makefile
└── README.md

Generated projects include version metadata in pyproject.toml for tracking:

[tool.fastapi-fullstack]
generator_version = "0.1.5"
generated_at = "2024-12-21T10:30:00+00:00"

---

⚙️ Configuration Options

Core Options

Option	Values	Description
Database	postgresql, none	Async PostgreSQL (SQLAlchemy 2.0 + Alembic)
ORM	sqlalchemy, sqlmodel	SQLModel for simplified syntax
Auth	jwt, api_key, both, none	JWT includes user management
OAuth	none, google	Social login
AI Framework	pydantic_ai, pydantic_deep, langchain, langgraph, deepagents	Choose your AI agent framework
LLM Provider	openai, anthropic, google, openrouter, openai_compatible, all	OpenRouter and OpenAI-compatible only with Pydantic AI / Pydantic Deep Agents
RAG	--rag	Enable RAG with vector database
Vector Store	milvus, qdrant, chromadb, pgvector	pgvector uses existing PostgreSQL
Background Tasks	none, celery, taskiq, arq, prefect	Distributed queues / orchestration
Frontend	none, nextjs	Next.js 15 + React 19

Presets

Preset	Description
--preset production	Full production setup with Redis, Sentry, Kubernetes, Prometheus
--preset ai-agent	AI agent with WebSocket streaming and conversation persistence
--minimal	Minimal project with no extras

Integrations

Select what you need:

fastapi-fullstack new
# ✓ Redis (caching/sessions)
# ✓ Rate limiting (per user/org/IP, Redis or in-memory)
# ✓ Pagination (fastapi-pagination)
# ✓ Admin Panel (SQLAdmin)
# ✓ AI Agent (Pydantic AI or LangChain)
# ✓ Webhooks
# ✓ Sentry
# ✓ Logfire / LangSmith
# ✓ Prometheus
# ... and more

---

🔄 Comparison

vs. Manual Setup

Setting up a production AI agent stack manually means wiring together 10+ tools yourself:

# Without this template, you'd need to manually:
# 1. Set up FastAPI project structure
# 2. Configure SQLAlchemy + Alembic migrations
# 3. Implement JWT auth with refresh tokens
# 4. Build WebSocket streaming for AI responses
# 5. Integrate Pydantic AI/LangChain with tool calling
# 6. Set up RAG pipeline (parsing, chunking, embedding, vector store)
# 7. Configure Celery + Redis for background tasks
# 8. Build Next.js frontend with auth and chat UI
# 9. Write Docker Compose for all services
# 10. Add observability, rate limiting, admin panel...

# With this template:
pip install fastapi-fullstack
fastapi-fullstack
# Done. All of the above, configured and working.

vs. Alternatives

Feature	This Template	full-stack-fastapi-template	create-t3-app
AI Agents (5 frameworks)	✅	❌	❌
RAG Pipeline (4 vector stores)	✅	❌	❌
WebSocket Streaming	✅	❌	❌
Conversation Persistence	✅	❌	❌
LLM Observability (Logfire/LangSmith)	✅	❌	❌
FastAPI Backend	✅	✅	❌
Next.js Frontend	✅ (v15)	❌	✅
JWT + OAuth Authentication	✅	✅	✅ (NextAuth)
Background Tasks (Celery/Taskiq/ARQ/Prefect)	✅	✅ (Celery)	❌
Billing & Credits (Stripe + usage metering)	✅	❌	❌
Admin Panel	✅ (SQLAdmin)	❌	❌
Async PostgreSQL (SQLAlchemy 2.0 + pgvector)	✅	✅	Prisma
Docker + K8s	✅	✅	❌
Interactive CLI Wizard	✅	❌	✅
Django-style Commands	✅	❌	❌
Document Sources (GDrive, S3, API)	✅	❌	❌
AI-Agent Friendly (CLAUDE.md)	✅	❌	❌

---

❓ FAQ

<details> <summary><b>How is this different from full-stack-fastapi-template?</b></summary>

full-stack-fastapi-template by @tiangolo is a great starting point for FastAPI projects, but it focuses on traditional web apps. This template is purpose-built for AI/LLM applications — it adds AI agents (5 frameworks), RAG with 4 vector stores, WebSocket streaming, conversation persistence, LLM observability, and a Next.js chat UI out of the box.

</details> <details> <summary><b>Can I use this without AI/LLM features?</b></summary>

Yes. The AI agent and RAG modules are optional. You can use this as a pure FastAPI + Next.js template with auth, admin panel, background tasks, and all other infrastructure — just skip the AI framework selection during setup.

</details> <details> <summary><b>What Python and Node.js versions are required?</b></summary>

Python 3.11+ and Node.js 18+ (for the Next.js frontend). We recommend using uv for Python and bun for the frontend.

</details> <details> <summary><b>Can I add integrations after project generation?</b></summary>

The generated project is plain code — no lock-in or runtime dependency on the generator. You can add, remove, or modify any integration manually. The template just gives you a well-structured starting point.

</details> <details> <summary><b>Can I use a different LLM provider than the one I selected?</b></summary>

Yes. The LLM provider is configured via environment variables (AI_MODEL, OPENAI_API_KEY, etc.). You can switch providers by changing the .env file and the model name — no code changes needed for Pydantic AI (which supports all providers natively).

</details>

---

📚 Documentation

Document	Description
Architecture	Repository + Service pattern, layered design
Frontend	Next.js setup, auth, state management
AI Agent	Pydantic AI, tools, WebSocket streaming
Observability	Logfire integration, tracing, metrics
Deployment	Docker, Kubernetes, production setup
Development	Local setup, testing, debugging
Changelog	Version history and release notes

---

Star History

---

🙏 Inspiration

This project is inspired by:

• full-stack-fastapi-template by @tiangolo
• fastapi-template by @s3rius
• FastAPI Best Practices by @zhanymkanov
• Django's management commands system

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

<a href="https://github.com/vstorm-co/full-stack-ai-agent-template/graphs/contributors"> <img src="https://contrib.rocks/image?repo=vstorm-co/full-stack-ai-agent-template" alt="Contributors" /> </a>

---

📄 License

MIT License - see LICENSE for details.

---

<div align="center">

Need help implementing this in your company?

<p>We're <a href="https://vstorm.co"><b>Vstorm</b></a> — an Applied Agentic AI Engineering Consultancy<br>with 30+ production AI agent implementations.</p> <a href="https://vstorm.co/contact-us/"> <img src="https://img.shields.io/badge/Talk%20to%20us%20%E2%86%92-0066FF?style=for-the-badge&logoColor=white" alt="Talk to us"> </a>

<br><br>

Made with ❤️ by <a href="https://vstorm.co"><b>Vstorm</b></a>

</div>