전체 스택 AI 에이전트 템플릿

무엇인가요 – 완전한 프로덕션 준비된 웹앱(FastAPI 백엔드 + Next.js 프론트엔드)을 사전에 AI 에이전트 기능, 검색 증강 생성(RAG), 인증, 청구, 관찰성, 배포 도구와 함께 구성하는 명령줄 생성기입니다. 생성된 프로젝트는 Docker로 로컬에서 실행하거나 Kubernetes에 배포할 수 있으며, 채팅, 팀/워크스페이스 관리, 지식 기반 인게이션, 관리 대시보드를 위한 풍부한 UI를 제공합니다.

---

🎯 핵심 목적

이 템플릿은 개발자가 전체 스택 AI 에이전트 SaaS를 몇 분 안에 시작한 후, 일반적인 구조(인증, DB, RAG, CI, 모니터링 등)를 다시 구성하는 데 시간을 쓰지 않고 도메인 전용 로직에 집중할 수 있도록 합니다.

---

🚀 빠른 시작 (README에서)

1. 생성기 설치

   pip install fastapi-fullstack   # 또는 `uv tool install fastapi-fullstack`
   

2. 프로젝트 생성 – 인터랙티브 마법사에 응답하거나 플래그를 전달:

   fastapi-fullstack               # `my_ai_app` 생성
   

3. 스택 부트스트랩

   cd my_ai_app
   make bootstrap                 # Docker 이미지 빌드, DB 시작, 마이그레이션 실행, 관리자 시드 생성
   

4. UI 실행 (다른 터미널에서)

   cd frontend && bun install && bun dev   # 또는 `make dev-frontend`
   

5. 서비스 열기:
   • API 문서: http://localhost:8000/docs
   • 관리자 UI: http://localhost:8000/admin (admin@example.com / admin123)
   • 프론트엔드: http://localhost:3000

---

🛠️ 주요 기능 (목록 기준)

카테고리	제공되는 기능
AI 에이전트 프레임워크	5개의 런타임 지원 – Pydantic AI, Pydantic Deep Agents, LangChain, LangGraph, DeepAgents.
RAG 파이프라인	즉시 사용 가능한 벡터 스토어(Milvus, Qdrant, pgvector, ChromaDB)와 자동 청크화 및 임베딩 기능.
웹 스택	WebSocket 스트리밍을 지원하는 FastAPI 15 백엔드, Next.js 15 프론트엔드, 실시간 채팅 UI.
대화 공유	공개 링크, 관리자 전용 브라우저 보기, 채팅 세션 내보내기/공유 기능.
기업용 준비	JWT + OAuth, 관리자 패널, Celery 작업 큐, Docker 및 Kubernetes 구성, 환경별 구성 파일.
관찰성	내장된 사용량 대시보드, 토큰 단위 회계, Stripe 청구 통합, 활동 로그.
CLI 및 Django 스타일 관리	서버, DB 마이그레이션, 사용자 생성 등에 사용할 수 있는 my_ai_app 명령어 생성.
업그레이드 경로	make upgrade 명령어로 업스트림 템플릿 변경 사항을 기존 프로젝트에 병합하면서 사용자 코드 손실 없이 유지.
확장성	기능 플래그(e.g., enable_marketing_site)를 통해 마케팅 랜딩 페이지, SaaS 청구, 팀 워크스페이스 등을 추가 가능.

---

📂 생성된 프로젝트 구조 (개요)

my_ai_app/
├─ backend/          # FastAPI 앱, Pydantic 모델, Celery 워커
│   ├─ app/
│   ├─ alembic/      # DB 마이그레이션
│   ├─ Dockerfile
│   └─ Makefile
├─ frontend/         # Next.js (React) UI, Tailwind, WebSocket 클라이언트
│   ├─ pages/        # 채팅, 대시보드, 관리자, 청구 등
│   ├─ components/
│   └─ Dockerfile
├─ docker-compose.dev.yml   # 개발 스택 (db, redis, milvus, …)
├─ docker-compose.prod.yml  # 프로덕션 스택
└─ makefile          # 개발, 프로덕션, 업그레이드 등의 단축 명령어

이 리포지토리는 또한 PyPI 패키지(fastapi-fullstack)를 함께 제공하여 스크래핑 로직을 포함합니다.

---

🤖 AI 에이전트 세부 정보

• 에이전트 코드는 백엔드에 위치하며 생성 시 선택 가능 (예: pydantic_deep).
• 에이전트는 응답 스트리밍, 도구 호출, 사용자 확인을 위한 일시 정지(ask_user), Python 스크립트 실행, 하위 에이전트 생성이 가능합니다.
• UI는 각 도구 호출을 카드로 렌더링하고, 실시간 계획 및 작업 체크리스트를 표시하며, 차트나 코드 출력을 인라인으로 시각화합니다.

---

📚 문서 및 생태계

• 문서 사이트 – https://vstorm-co.github.io/full-stack-ai-agent-template/ (설치, 업그레이드 가이드, API 참조).
• Vstorm 오픈소스 생태계의 일부 – AgenticOS, pydantic-deepagents, pydantic-ai-shields와 같은 연결된 프로젝트는 기반 런타임, 가드레일, 샌드박스 기능을 제공합니다.
• CI 배지에서 100 % 테스트 커버리지 확인 가능; OpenSSF 최고 실천 배지로 성숙한 오픈소스 프로세스를 확인할 수 있습니다.

---

🏁 언제 사용할까?

• AI 어시스턴트 제품(고객 지원 봇, 데이터 분석가, 코드 어시스턴트 등)을 위한 완성된 SaaS 템플릿이 필요할 때.
• 인증, 다중 테넌트 워크스페이스, Stripe 청구와 같은 기업용 기능을 처음부터 구현하지 않고도 필요할 때.
• 스택을 항상 최신 상태로 유지하고, 나중에 업그레이드하기 위해 단일 명령어를 선호할 때.

---

📦 패키징 방식

• 생성기는 PyPI를 통해 fastapi-fullstack으로 배포되며, pip, uv, pipx로 설치 가능합니다.
• 생성된 앱은 Docker로 컨테이너화되며, 선택적으로 Kubernetes 매니페스트 포함.

---

📌 TL;DR

vstorm-co/full-stack-ai-agent-template은 실제 프로덕션 수준의 프로젝트로, 완전한 FastAPI + Next.js 앱을 AI 에이전트, RAG, 인증, 청구, 배포 기능과 함께 생성합니다. AI 에이전트 SaaS 제품을 개발하는 팀을 대상으로 하며, 생성된 코드에 대한 명확한 업그레이드 경로를 제공합니다.