🧩 LangGraph Interrupt Workflow Template

⚡ A production-ready, provider-agnostic template for building human-in-the-loop AI workflows with LangGraph v1. Pause an agent mid-execution, ask a human to approve / edit / redirect, then resume exactly where it left off — with a polished Next.js chat UI on top.

Runs with zero configuration. Clone it and go — a built-in mock model lets you explore the full interrupt flow without any API keys. Add a provider when you're ready.

One click → a ready-to-run dev container with Python, Node, and all dependencies installed.

✨ Why this template?

Most "agent" demos run start-to-finish with no human control. Real-world systems — approvals, content review, high-stakes tool calls — need a human in the loop. This template shows three complementary ways to do that with the latest LangGraph:

All three use the same primitive: interrupt() pauses the graph, persists state, and waits for Command(resume=...).

🔀 Two engines, one UI

The chat app ships with a live Workflow ↔ Agent toggle so you can compare the two control paradigms on the same screen:

Both share the same provider-agnostic LLM, web_search tool, and long-term memory.

🚀 Features

• 🧩 Human-in-the-loop, done right — multiple interrupt points, resume with approve/edit/redirect.
• 🔀 Parallel research (Send) — a planner fans out concurrent sub-researchers (map-reduce) via Command(goto=[Send(...)]), with live progress streaming.
• 🧠 Long-term memory — a LangGraph Store remembers a user's topics & preferences across sessions, not just within a thread.
• ⏪ Time travel — rewind to any past checkpoint and fork a different path; the original run is preserved.
• 🔌 Provider-agnostic — OpenAI, Anthropic, Google, Groq, Mistral, IBM watsonx, Ollama… via LangChain's init_chat_model. One env var to switch.
• 🆓 Zero-config demo — a streaming-capable mock model runs the whole app with no API keys.
• 💾 Durable execution — optional AsyncSqliteSaver checkpointer; workflows survive server restarts.
• 🤖 Latest agent stack — LangGraph v1.2 + LangChain v1, create_agent, and HumanInTheLoopMiddleware.
• 📡 Streaming — Server-Sent Events stream progress and the final answer to the UI.
• 🔭 LangGraph Studio ready — langgraph.json registers all graphs for langgraph dev.
• 🎨 Modern UI — Next.js 15 + React 19 chat interface with live progress and a rewind panel.
• ✅ Tested & CI'd — pytest suite + GitHub Actions for backend and frontend.

🏗️ Architecture

┌──────────────────┐     HTTP / SSE      ┌──────────────────┐         ┌────────────────────┐
│   Frontend       │ ──────────────────► │   Backend        │ ──────► │   LangGraph        │
│   Next.js 15     │ ◄────────────────── │   FastAPI        │ ◄────── │   workflow         │
│ • Chat UI        │                     │ • /start /resume │         │ • interrupt()      │
│ • Interrupt cards│                     │ • /stream (SSE)  │         │ • checkpointer     │
│ • Live progress  │                     │ • lifespan graph │         │ • resume via Command│
└──────────────────┘                     └──────────────────┘         └────────────────────┘

⚡ Quick Start (zero config)

# 1. Backend
cd backend
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # works as-is with the built-in mock model
python main.py                  # http://localhost:8000  (docs at /docs)

# 2. Frontend (new terminal)
cd frontend
npm install
npm run dev                     # http://localhost:3000

Open http://localhost:3000, ask a question, and watch the workflow pause for your input at each interrupt.

Use a real LLM

Edit backend/.env and set a model + matching API key:

LLM_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-...
# or: LLM_MODEL=claude-sonnet-4-5  LLM_PROVIDER=anthropic  ANTHROPIC_API_KEY=...

That's it — the workflow and agent automatically use it.

🧠 How interrupts work

from langgraph.types import interrupt, Command

async def format_selection_interrupt(state):
    # Pause and ask the human. State is persisted automatically.
    choice = interrupt("How should I format the final answer?")
    return {"format_choice": choice}

# Later, from your API:
await graph.ainvoke(Command(resume="executive"), config)   # resumes exactly here

1. A node calls interrupt(payload) → execution pauses, state is checkpointed.
2. The API returns the interrupt payload to the UI (requires_input: true).
3. The user picks an option; the API calls ainvoke(Command(resume=choice)).
4. The graph continues from the interrupted node with the user's input.

The modern agent pattern (HITL middleware)

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware

agent = create_agent(
    model,
    tools=[web_search],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"web_search": True})],
    checkpointer=checkpointer,
)

Try it from the CLI:

cd backend && python agent.py "What are the latest advances in solid-state batteries?"

Approve / edit / reject workflow

A second example (backend/approval_workflow.py, UI at /approval) shows the three canonical human actions on a single interrupt:

• Approve → send the draft as-is
• Edit → send the human's revised version
• Reject + feedback → the AI redrafts using the feedback, then pauses again

response = interrupt({"type": "approval", "draft": draft, "actions": ["approve", "edit", "reject"]})
# resume with: Command(resume={"action": "reject", "feedback": "Make it shorter"})

🧪 Advanced LangGraph features

The research workflow is also a tour of LangGraph's more powerful primitives:

Parallel research with Send (map-reduce). A planner node splits the question into sub-questions and fans them out to concurrent workers, combining Command (state update + dynamic routing) with Send (one task per item):

return Command(
    goto=[Send("sub_researcher", {"sub_query": q}) for q in sub_queries],
    update={"sub_queries": sub_queries},
)

Each worker streams a progress event (get_stream_writer) so the UI shows "Researched: …" live; results aggregate through a reset-aware reducer.

Cross-thread long-term memory (Store). Pass a user_id and the assistant remembers across sessions — a brand-new thread recalls prior topics/preferences:

graph = build_research_graph(checkpointer=saver, store=InMemoryStore())
# in a node:  await store.aput(("memories", user_id), key, {"text": note})

Time travel (rewind & fork). List checkpoints and resume from any past one down a different path — without losing the original run:

async for snap in graph.aget_state_history(config): ...   # GET /history/{thread_id}
# resume from a past checkpoint -> POST /fork
graph.astream(Command(resume=new_choice),
              config={"configurable": {"thread_id": tid, "checkpoint_id": cid}})

🔭 Visualize with LangGraph Studio

pip install "langgraph-cli[inmem]"
langgraph dev          # opens LangGraph Studio with the research, approval, and agent graphs

langgraph.json registers all three graphs so you can step through interrupts visually.

📡 API reference

⚙️ Configuration

All configuration is via environment variables (see backend/.env.example).

🐳 Docker

cp backend/.env.example backend/.env   # configure as needed
docker compose up --build
# Frontend → http://localhost:3000   Backend → http://localhost:8000

Compose runs the backend (with a durable SQLite checkpoint volume) and the Next.js frontend as separate services.

🎨 Customizing for your use case

This template ships a research assistant example to demonstrate the patterns. To adapt it:

1. Define your state in backend/graph.py (ResearchState).
2. Add nodes, calling interrupt(...) wherever you need a human decision.
3. Wire edges in build_research_graph().
4. Add tools in backend/tools.py and expose them to the agent.
5. Swap the LLM by changing env vars — no code changes needed.

Great fits: content review & approval, data-processing pipelines, quality control, configuration wizards, customer-support escalation, and any workflow needing human oversight.

🧪 Testing

cd backend
USE_MOCK_LLM=true pytest -v     # fast, offline, no API keys

📁 Project structure

langgraph-interrupt-workflow-template/
├── backend/
│   ├── main.py                # FastAPI app (lifespan-managed graphs, SSE streaming)
│   ├── graph.py               # Multi-step human-in-the-loop research workflow
│   ├── approval_workflow.py   # Approve / edit / reject workflow
│   ├── agent.py               # create_agent + HumanInTheLoopMiddleware example
│   ├── memory.py              # Cross-thread long-term memory (Store)
│   ├── llm.py                 # Provider-agnostic LLM factory + offline mock model
│   ├── tools.py               # Example web_search tool (Tavily / mock)
│   ├── test_main.py           # Pytest suite
│   ├── requirements.txt
│   └── .env.example
├── frontend/                  # Next.js 15 + React 19 UI
│   ├── app/page.tsx           # Research assistant chat
│   ├── app/approval/page.tsx  # Approve / edit / reject UI
│   └── Dockerfile
├── .devcontainer/             # GitHub Codespaces / VS Code dev container
├── langgraph.json             # LangGraph Studio config (research + approval + agent)
├── .github/workflows/ci.yml
├── Dockerfile                 # Backend image
├── docker-compose.yml         # Backend + frontend services
└── README.md

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md. Fork → branch → PR.

📝 License

MIT — see LICENSE.

🔗 Resources

• LangGraph docs · What's new in v1
• Human-in-the-loop guide
• create_agent · FastAPI · Next.js