langgraph-assistant-ui-starter

A starter template for building AI agent apps with FastAPI + LangGraph backend and Next.js + assistant-ui frontend.

Features:

• LangGraph agent with tool use (web search, web scraping, Python code execution)
• SSE streaming with thinking indicators, tool traces, and status updates
• Thread management with sidebar (create, rename, delete, switch)
• Regeneration support (re-run assistant responses)
• Dark mode support
• Mobile-responsive layout
• Deploy-ready with Render blueprint

Architecture

┌──────────────────────┐     SSE      ┌──────────────────────┐
│   Next.js Frontend   │◄────────────►│   FastAPI Backend    │
│                      │              │                      │
│  assistant-ui        │   REST API   │  LangGraph Agent     │
│  LocalRuntime        │◄────────────►│  MemorySaver         │
│  Thread management   │              │  In-memory threads   │
└──────────────────────┘              └──────────────────────┘
                                              │
                                       ┌──────┴──────┐
                                       │   Tools     │
                                       │  - Search   │
                                       │  - Scrape   │
                                       │  - Python   │
                                       └─────────────┘

Quick Start

1. Backend

cd backend
cp .env.example .env
# Edit .env with your API keys

Configure your LLM in app/agent/llms.py — uncomment one of the examples (Anthropic, OpenAI, Google, Groq).

Then install an LLM provider package. For example:

# Pick one:
uv add langchain-anthropic    # Claude
uv add langchain-openai       # GPT
uv add langchain-google-genai # Gemini
uv add langchain-groq         # Groq

Start the backend:

uv sync
uv run uvicorn app.main:app --reload

Backend runs at http://localhost:8000. Verify: curl http://localhost:8000/health

2. Frontend

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

Frontend runs at http://localhost:3000.

Project Structure

├── backend/
│   ├── app/
│   │   ├── main.py                    # FastAPI app, CORS, health check
│   │   ├── agent/
│   │   │   ├── __init__.py            # get_agent() singleton
│   │   │   ├── agent.py              # Agent class (stream, invoke, thread ops)
│   │   │   ├── state.py              # AgentState (MessagesState + user_id)
│   │   │   ├── nodes.py              # LLM node with retry logic
│   │   │   ├── graph.py              # LangGraph workflow (analyst → tools → loop)
│   │   │   ├── llms.py               # ⚙️  Configure your LLM here
│   │   │   ├── context/
│   │   │   │   ├── builder.py         # System prompt builder
│   │   │   │   └── prompts/
│   │   │   │       └── system.md      # ⚙️  Customize the system prompt
│   │   │   └── tools/
│   │   │       ├── search.py          # Tavily web search
│   │   │       ├── python_sandbox.py  # Python code execution
│   │   │       └── firecrawl.py       # Web scraping
│   │   ├── routers/
│   │   │   ├── chat.py               # POST /api/chat (SSE streaming)
│   │   │   └── threads.py            # Thread CRUD endpoints
│   │   ├── threads/
│   │   │   └── store.py              # In-memory thread store
│   │   ├── schemas/                   # Pydantic models
│   │   └── utils/
│   │       └── title_generator.py     # Auto-generate thread titles
│   ├── pyproject.toml
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── layout.tsx             # Root layout
│   │   │   ├── page.tsx               # Renders ChatLayout
│   │   │   └── globals.css            # Theme + prose styling
│   │   ├── components/
│   │   │   ├── chat/
│   │   │   │   ├── ChatLayout.tsx     # Sidebar + Thread
│   │   │   │   ├── RuntimeProvider.tsx # SSE adapter
│   │   │   │   └── Thread.tsx         # Chat UI
│   │   │   ├── Sidebar.tsx            # Thread list
│   │   │   └── ToastProvider.tsx
│   │   ├── contexts/
│   │   │   ├── ThreadContext.tsx       # Thread lifecycle state
│   │   │   └── ThemeContext.tsx        # Light/dark theme
│   │   └── utils/
│   │       └── constants.ts           # API_BASE_URL
│   └── package.json
├── render.yaml                         # Render deploy blueprint
└── README.md

Customizing

System Prompt

Edit backend/app/agent/context/prompts/system.md to change the agent's behavior and instructions.

Tools

Add new tools in backend/app/agent/tools/ following the existing pattern:

1. Create a new file with a @tool decorated async function
2. Import it in backend/app/agent/nodes.py
3. Add it to the TOOLS list

Models

Edit backend/app/agent/llms.py to change the LLM provider or model.

Theme

Edit the CSS variables in frontend/src/app/globals.css to customize colors.

Adding Auth

To add authentication:

1. Backend: Add a dependencies.py with your auth middleware (e.g., JWT validation)
2. Backend: Add Depends(get_user) to router endpoints in chat.py and threads.py
3. Backend: Replace DEFAULT_USER_ID with the authenticated user's ID
4. Frontend: Add your auth provider wrapper in layout.tsx
5. Frontend: Add auth token to fetch headers in RuntimeProvider.tsx and Sidebar.tsx

Adding a Database

To replace the in-memory store with a database:

1. Backend: Add asyncpg (or your ORM) to pyproject.toml
2. Backend: Create DB models and CRUD functions (replace threads/store.py)
3. Backend: Replace MemorySaver in agent.py with AsyncPostgresSaver from langgraph-checkpoint-postgres
4. Backend: Add DB initialization in the lifespan function in main.py

Deployment

Render

1. Push to GitHub
2. Go to Render Dashboard → New → Blueprint
3. Connect your repo, select render.yaml
4. Fill in environment variables
5. Deploy

Other platforms

The backend is a standard FastAPI app and the frontend is a standard Next.js app — they can be deployed anywhere that supports Python and Node.js respectively.