Despliega una app AI en producción en 5 minutos: FastAPI + Next.js + 20 integraciones

Estás empezando un nuevo proyecto de AI. Necesitas un backend FastAPI con auth, un frontend Next.js con chat en streaming, soporte WebSocket, migraciones de base de datos, caching con Redis, deployment con Docker y un agente Pydantic AI con soporte de tools.

Abres un directorio vacío. Dos semanas después, has conectado 15 bibliotecas, corregido 30 problemas de configuración y escrito cero lógica de negocio.

TL;DR

• fastapi-fullstack create my_app genera un stack de producción completo — backend FastAPI, frontend Next.js, Docker, CI/CD — con un solo comando.
• 20+ integraciones listas para usar: Pydantic AI, LangChain, JWT auth, PostgreSQL, Redis, WebSocket streaming, Logfire, Sentry, Celery, Kubernetes y más.
• Los presets coinciden con arquitecturas comunes: --preset ai-agent para apps de chat AI, --preset production para deployments enterprise, o elige opciones individuales.
• La CLI genera proyectos completos y ejecutables — no archivos vacíos con comentarios TODO. Los tests pasan, Docker compila, el servidor arranca.
• Todo es intercambiable. Empieza con SQLite, cambia a PostgreSQL. Empieza con Pydantic AI, agrega LangChain. La arquitectura soporta migración incremental.

Hemos repetido este proceso demasiadas veces. Después del décimo proyecto en el que copiamos el mismo sistema de auth, el mismo handler WebSocket, el mismo setup de Docker Compose y el mismo pipeline de CI, construimos un template. Luego lo convertimos en una herramienta CLI.

fastapi-fullstack create my_app — y obtienes el stack completo, configurado, testeado y listo para deploy.

La CLI: Un comando, stack completo

pip install fastapi-fullstack
fastapi-fullstack create my_app --preset ai-agent

Eso genera un proyecto completo con:

Backend: FastAPI + agente Pydantic AI + WebSocket streaming + JWT auth + PostgreSQL + Redis + migraciones Alembic + rate limiting + panel de admin + Logfire observability

Frontend: Next.js 15 + React 19 + TypeScript + Tailwind CSS v4 + Zustand + TanStack Query + WebSocket chat UI + dark mode

DevOps: Docker + Docker Compose + multi-stage builds + health checks + Makefile

Qué incluye: 20+ integraciones

Presets: Elige tu stack

# Production - todo lo que necesitas
fastapi-fullstack create my_app --preset production

# AI Agent - optimizado para apps de agentes
fastapi-fullstack create my_app --preset ai-agent

# Custom - elige exactamente lo que quieras
fastapi-fullstack create my_app \
  --database postgresql \
  --auth jwt \
  --ai-framework pydantic_ai \
  --llm-provider openai \
  --redis \
  --websockets \
  --admin-panel \
  --sentry

El preset ai-agent te da PostgreSQL, WebSocket streaming, persistencia de conversaciones y un agente Pydantic AI completamente configurado con soporte de tools.

El agente AI: Pydantic AI con Streaming

El agente generado está listo para producción con dependency injection y soporte de tools:

@dataclass
class Deps:
    user_id: str | None = None
    user_name: str | None = None
    metadata: dict[str, Any] = field(default_factory=dict)


class AssistantAgent:
    def __init__(self, model_name=None, temperature=None, system_prompt=None):
        self.model_name = model_name or settings.AI_MODEL
        self.temperature = temperature or settings.AI_TEMPERATURE
        self.system_prompt = system_prompt or DEFAULT_SYSTEM_PROMPT

    def _create_agent(self) -> Agent[Deps, str]:
        model = OpenAIChatModel(
            self.model_name,
            provider=OpenAIProvider(api_key=settings.OPENAI_API_KEY),
        )

        agent = Agent[Deps, str](
            model=model,
            model_settings=ModelSettings(temperature=self.temperature),
            system_prompt=self.system_prompt,
        )
        self._register_tools(agent)
        return agent

    def _register_tools(self, agent):
        @agent.tool
        async def current_datetime(ctx: RunContext[Deps]) -> str:
            """Get the current date and time."""
            return get_current_datetime()

Agrega tus propios tools extendiendo _register_tools(). El agente usa el patrón deps — el contexto del usuario fluye a través de RunContext[Deps] hacia cada llamada de tool.

WebSocket Streaming: Token por token

El endpoint WebSocket transmite las respuestas del agente en tiempo real:

@router.websocket("/ws/chat")
async def chat_websocket(websocket: WebSocket, user = Depends(get_current_user_ws)):
    await manager.connect(websocket)
    conversation_history = []

    try:
        while True:
            data = await websocket.receive_json()
            user_message = data.get("message", "")

            async with agent.iter(
                user_message,
                deps=deps,
                message_history=model_history,
            ) as agent_run:
                async for node in agent_run:
                    if Agent.is_model_request_node(node):
                        async with node.stream(agent_run.ctx) as stream:
                            async for event in stream:
                                if isinstance(event, PartDeltaEvent):
                                    await manager.send_event(
                                        websocket, "text_delta",
                                        {"content": event.delta.content_delta},
                                    )

                    elif Agent.is_call_tools_node(node):
                        async with node.stream(agent_run.ctx) as stream:
                            async for event in stream:
                                if isinstance(event, FunctionToolCallEvent):
                                    await manager.send_event(
                                        websocket, "tool_call",
                                        {"tool_name": event.part.tool_name},
                                    )

            await manager.send_event(websocket, "complete", {})

    except WebSocketDisconnect:
        manager.disconnect(websocket)

El frontend recibe eventos text_delta, tool_call, tool_result y complete. Los text deltas se renderizan token por token. Las llamadas a tools muestran un indicador visual. Es la misma experiencia de streaming que ves en ChatGPT.

Autenticación JWT: Login, registro, refresh

El sistema de auth está completo — no es un stub:

@router.post("/login", response_model=Token)
async def login(
    form_data: OAuth2PasswordRequestForm,
    user_service: UserSvc,
    session_service: SessionSvc,
):
    user = await user_service.authenticate(
        form_data.username, form_data.password
    )
    access_token = create_access_token(subject=str(user.id))
    refresh_token = create_refresh_token(subject=str(user.id))

    await session_service.create_session(
        user_id=user.id,
        refresh_token=refresh_token,
    )
    return Token(
        access_token=access_token,
        refresh_token=refresh_token,
    )

Hashing de contraseñas con Bcrypt. JWT access tokens (30 min). Refresh tokens (7 días). Tracking de sesiones. El frontend maneja el auto-refresh de forma transparente.

Comandos CLI estilo Django

El proyecto generado incluye una CLI de administración:

# Servidor
uv run my_app server run --reload
uv run my_app server routes

# Base de datos
uv run my_app db migrate -m "Add users table"
uv run my_app db upgrade

# Usuarios
uv run my_app user create-admin --email admin@example.com

# Celery
uv run my_app celery worker
uv run my_app celery beat

Más un Makefile para operaciones comunes:

make install       # Instalar dependencias
make run           # Iniciar servidor de desarrollo
make db-migrate    # Crear migración
make db-upgrade    # Aplicar migraciones
make docker-up     # Iniciar todos los servicios
make test          # Ejecutar tests

Docker: Builds de producción multi-stage

El Dockerfile generado usa multi-stage builds para un tamaño de imagen mínimo:

# Fase de build
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project --no-dev

# Fase de runtime
FROM python:3.12-slim
COPY --from=builder /app/.venv /app/.venv
RUN adduser --disabled-password appuser
USER appuser

HEALTHCHECK --interval=30s --timeout=10s \
    CMD python -c "import httpx; httpx.get('http://localhost:8000/api/v1/health')"

Usuario no-root. Health checks. Cache de build para rebuilds rápidos. El archivo Docker Compose conecta PostgreSQL, Redis, Celery worker, Celery beat y monitoreo con Flower.

Frontend: Next.js 15 + React 19

El frontend es un setup moderno de Next.js:

• Zustand para gestión de estado
• TanStack Query para fetching de datos de la API
• WebSocket chat UI con streaming token por token
• JWT auth con auto-refresh
• Dark mode incluido
• Tailwind CSS v4 para estilos
• Playwright para tests e2e

Conclusiones clave

• No construyas boilerplate. JWT auth, WebSocket streaming, configuraciones Docker, pipelines CI — son problemas resueltos. Usa un template que los implemente bien para que puedas enfocarte en la lógica de negocio.
• Los presets coinciden con arquitecturas comunes. --preset ai-agent te da exactamente lo que las apps de chat AI necesitan. --preset production agrega integraciones enterprise.
• La CLI genera, no scaffoldea. Obtienes un proyecto completo y ejecutable — no archivos vacíos con comentarios TODO. Los tests pasan. Docker compila. El servidor arranca.
• Todo es intercambiable. Empieza con SQLite, cambia a PostgreSQL. Empieza con Pydantic AI, agrega LangChain. La arquitectura soporta migración incremental.
• Proyectos reales nos enseñaron lo que se necesita. Este template no es teórico — fue extraído de deployments en producción. Cada integración está ahí porque un cliente la necesitó.

Pruébalo tú mismo

full-stack-fastapi-nextjs-llm-template — Generador de proyectos listo para producción para aplicaciones AI/LLM con FastAPI + Next.js + 20+ integraciones.

pip install fastapi-fullstack
fastapi-fullstack create my_app --preset ai-agent