Orchestrate multi-agent workflows with LangGraph, FastAPI and React, on any LLM provider.
A full-stack reference implementation for building AI applications on stateful, multi-agent graphs. Pick a workflow, pick a model from OpenAI, Gemini, Claude, DeepSeek, OpenRouter, Grok, Groq or a local Ollama instance, and watch every agent step stream into the browser in real time.
- Three production-style orchestration patterns: supervisor/worker routing, a write-and-critique reflection loop, and plan-and-execute.
- Provider-agnostic: switch models per run. OpenAI-compatible vendors share one code path, so adding another is a few lines.
- Real-time streaming: each node's output is pushed to the UI over Server-Sent Events as the graph runs.
- Stateful by design: conversations are checkpointed per
thread_id, so runs can be inspected and continued. - Bring your own key: use server-side keys from
.env, or paste one in the UI per run (never stored or logged). - Safe loops: every cyclic graph has an iteration cap, configurable per run.
- Testable without API keys: graph logic is covered by tests that use a fake chat model.
- One-command deploy: Docker Compose for the full stack, GitHub Actions for CI.
flowchart LR
UI["React UI<br/>(Vite + TypeScript)"] -- "POST /workflows/{id}/stream" --> API["FastAPI"]
API -- "SSE: start, node, final" --> UI
API --> Factory["LLM factory"]
API --> Graph["LangGraph workflow"]
Graph --> CP[("Checkpointer<br/>thread state")]
Factory --> P1["OpenAI"]
Factory --> P2["Gemini"]
Factory --> P3["Anthropic"]
Factory --> P4["DeepSeek / Grok / Groq<br/>OpenRouter / Ollama"]
Graph -. "uses" .-> Factory
Each request builds a fresh graph around the chosen model and shares one checkpointer. This keeps API keys out of
checkpointed state, while conversation state still persists by thread_id.
|
Supervisor team flowchart TD
S([supervisor]) --> R[researcher]
S --> C[coder]
S --> W[writer]
S --> V[reviewer]
R & C & W & V --> S
S --> F[finalizer]
|
Write and critique flowchart TD
W[writer] --> C{critic}
C -- revise --> W
C -- approved --> E([end])
|
Plan and execute flowchart TD
P[planner] --> X[executor]
X -- more steps --> X
X -- done --> S[synthesizer]
|
All three share one AgentState (backend/app/agents/state.py) with an add_messages reducer for the conversation
plus route, plan, iteration and final_answer fields.
git clone https://github.com/javaidgithub/langgraph-agent-studio.git
cd langgraph-agent-studio
cp .env.example .env # add at least one provider key (or enter one in the UI)
docker compose up --build- UI: http://localhost:3000
- API docs: http://localhost:8000/docs
Requires Python 3.11+ and Node 20+.
make install # backend venv + frontend deps
cp .env.example .env
make backend # terminal 1, http://localhost:8000
make frontend # terminal 2, http://localhost:5173Set these in .env (all optional; you can also supply a key per run from the UI).
| Variable | Purpose |
|---|---|
OPENAI_API_KEY |
OpenAI |
GOOGLE_API_KEY |
Google Gemini |
ANTHROPIC_API_KEY |
Anthropic |
DEEPSEEK_API_KEY |
DeepSeek |
OPENROUTER_API_KEY |
OpenRouter (hundreds of models behind one key) |
XAI_API_KEY |
xAI Grok |
GROQ_API_KEY |
Groq |
OLLAMA_BASE_URL |
Local Ollama, default http://localhost:11434/v1 |
CORS_ORIGINS |
JSON list of allowed browser origins |
LOG_LEVEL |
DEBUG, INFO, WARNING... |
The model list in the UI is a set of suggestions. The model field accepts any model id your provider supports.
Interactive docs live at /docs. Base path: /api/v1.
| Method | Path | Description |
|---|---|---|
GET |
/health |
Liveness check |
GET |
/providers |
Supported providers, suggested models, and whether the server holds a key |
GET |
/workflows |
Available workflows and their agents |
GET |
/workflows/{id}/graph |
Mermaid source for a compiled graph |
POST |
/workflows/{id}/stream |
Run and stream steps as Server-Sent Events |
POST |
/workflows/{id}/run |
Run to completion, return answer and all steps |
GET |
/workflows/{id}/threads/{thread_id} |
Inspect checkpointed state of a conversation |
Example
curl -N -X POST http://localhost:8000/api/v1/workflows/supervisor/stream \
-H "Content-Type: application/json" \
-d '{
"input": "Compare REST and GraphQL for a mobile backend",
"llm": { "provider": "deepseek", "model": "deepseek-chat", "temperature": 0.2 }
}'Stream events
| Event | Payload |
|---|---|
start |
{ thread_id, workflow } |
node |
{ node, agent, content, route, plan, iteration, elapsed_ms } |
final |
{ thread_id, final_answer, elapsed_ms } |
error |
{ message } |
Pass the same thread_id in a later request to continue a conversation with its prior context.
langgraph-agent-studio/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI app, CORS, error handling
│ │ ├── api/ # Routers: health, providers, workflows
│ │ ├── core/ # Settings, logging, domain errors
│ │ ├── schemas/ # Pydantic request/response models
│ │ ├── services/
│ │ │ ├── providers.py # Provider catalogue
│ │ │ ├── llm_factory.py # Provider -> LangChain chat model
│ │ │ └── runner.py # Runs a graph, emits SSE events
│ │ └── agents/
│ │ ├── state.py # Shared AgentState
│ │ ├── prompts.py # Every agent's system prompt
│ │ ├── registry.py # Workflow registry
│ │ ├── checkpoint.py # Checkpointer (swap for SQLite/Postgres)
│ │ └── graphs/ # supervisor, reflection, plan_execute
│ ├── tests/ # Fake-LLM graph tests and API tests
│ ├── Dockerfile
│ └── requirements*.txt
├── frontend/
│ ├── src/
│ │ ├── api/client.ts # Typed client and SSE reader
│ │ ├── hooks/useWorkflowRun.ts # Run state machine
│ │ └── components/ # SettingsPanel, Composer, Timeline, FinalAnswer
│ ├── Dockerfile
│ └── nginx.conf # Serves the UI and proxies /api (SSE-safe)
├── .github/workflows/ci.yml
├── docker-compose.yml
├── Makefile
└── .env.example
- Create
backend/app/agents/graphs/my_workflow.pywithbuild(llm, checkpointer, max_iterations)returning a compiledStateGraph. - Register it in
backend/app/agents/registry.py.
The API and UI list it automatically. Test it with GenericFakeChatModel; see tests/test_graphs.py.
If the vendor is OpenAI-compatible, add one ProviderSpec to backend/app/services/providers.py with its base URL
and a matching *_api_key field in core/config.py. Otherwise add a branch in llm_factory.py.
State is held in memory by default. Replace InMemorySaver in agents/checkpoint.py with
langgraph-checkpoint-sqlite or langgraph-checkpoint-postgres. No other code changes are needed.
make test # pytest: graph logic with a fake LLM, API contract and streaming
make lint # ruff
make typecheck # tsc + production build- API keys typed into the UI are sent to your backend for that one request, wrapped in
SecretStr, and never persisted or logged. - Run the backend behind HTTPS if you expose it publicly, since keys travel in the request body.
- This project has no authentication. Add it (for example an API-key or OAuth dependency on the routers) before deploying to a shared environment.
- Restrict
CORS_ORIGINSto your real frontend origin in production.
- Per-agent model selection (for example a cheap model for routing, a strong one for writing)
- Tool use: web search and code execution agents
- Human-in-the-loop approval steps using LangGraph interrupts
- Persistent checkpointing with Postgres
- Run history view in the UI
Issues and pull requests are welcome. See CONTRIBUTING.md.
MIT © javaidgithub