A hands-on learning repository for building stateful applications and agent workflows with LangGraph. Progress from your first compiled graph to conditional routing, reducers, dynamic fan-out, tool execution, checkpoint replay, human approval, durable jobs, and multi-agent orchestration.
65 independent, runnable labs: 20 beginner, 20 intermediate, 20 advanced, and five capstones. Each project includes Python source, a polished Streamlit interface, sample data, automated tests, cross-platform setup instructions, architecture explanations, debugging exercises, and interview questions with answer guidance.
The advanced projects explore practical engineering decisions around persistence, concurrency, idempotency, authorization, caching, timeouts, cost budgets, observability, and release gates. The learning portal helps you find projects by topic and practice explaining their mechanisms and tradeoffs. Default workflows run locally without model API keys; optional service integrations and deployment boundaries are documented separately.
Use Python 3.12. Run these commands from the repository root.
Windows PowerShell:
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
.venv\Scripts\python.exe -m streamlit run portal.pymacOS/Linux:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt
.venv/bin/python -m streamlit run portal.pyThe portal searches by project code and topic, shows launch commands, and includes outcome-prediction and interview self-assessment exercises. No API key is needed for its default local workflows.
cd 01_Beginner/B01_Hello_Graph
python -m venv .venv
# Windows: .venv\Scripts\python.exe -m pip install -r requirements.txt
# Windows: .venv\Scripts\python.exe -m streamlit run app.py
# macOS/Linux:
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m streamlit run app.pyCopy the project’s .env.example to .env only when configuring optional service access. Each lab contains all its own code and data; copying one folder outside this repository is supported. Keep credentials out of source control. Optional service modes are explicitly selected and never silently substituted for failed account requests.
| File | Purpose |
|---|---|
| app.py | Complete backend and graphical interface |
| requirements.txt | Pinned direct dependencies |
| sample_data/examples.json | Three executable input/output contracts |
| tests/test_app.py | Acceptance, invalid-input, and form tests; additional failure contracts where relevant |
| INSTRUCTIONS.md | Windows/macOS/Linux setup, execution, examples, and testing |
| EXPLANATION.md | Architecture, input fields, imports, complete core, and operational boundaries |
| EXERCISES.md | Extensions and deliberate debugging tasks |
| INTERVIEW.md | Mechanism, tradeoff, failure, scaling, and evidence questions with answer guidance |
| TROUBLESHOOTING.md | Concrete recovery actions |
- Beginner: learn one mechanism, run three contracts, explain every result field.
- Intermediate: compose mechanisms, inspect failure paths, and compare design alternatives.
- Advanced: reason about correctness under restarts, concurrent users, changing datasets, resource limits, privacy, and operational load.
- Capstone: integrate the pipeline and defend its acceptance criteria.
See topic coverage, interview practice, study plan, and API compatibility.
365 passing automated tests, a clean hashed installation, 6 standalone lab tests, and representative desktop/mobile browser checks. See validation evidence for scope and limitations.
python scripts/validate_repository.py
python -m pytest -q --junitxml=docs/test-results.xml
python -m pip checkValidation results are recorded in docs/VALIDATION.md. Local execution, SDK contract fixtures, live account responses, and managed deployments are treated as separate kinds of evidence. In constrained cloud command sandboxes, asynchronous SDK evaluation may need an execution context that supports its runtime facilities. The installed SDK also emits beta/dependency deprecation warnings; see the compatibility guide.
The graph labs execute the installed LangGraph runtime. Deterministic nodes isolate orchestration behavior without requiring a model account. Production identity, distributed storage, arbitrary-code isolation, and managed deployments require their own integration checks.
- B01 · Your first graph — StateGraph compilation and invocation
- B02 · A state contract — typed state versus runtime validation
- B03 · Update only what changes — partial node state updates
- B04 · A pipeline with clear stages — explicit sequential dependencies
- B05 · Route by policy — conditional edges and routing invariants
- B06 · Merge updates deliberately — Annotated reducers and accumulation
- B07 · Messages with identity — add_messages and message roles
- B08 · A bounded tool node — tool schemas and controlled graph execution
- B09 · Repeat with a stopping rule — graph loops and termination
- B10 · Read node updates — updates stream deltas
- B11 · Read evolving state — values stream snapshots
- B12 · Architecture you can inspect — compiled graph inspection
- B13 · The last state is available — checkpointer and thread configuration
- B14 · Two threads, separate histories — thread-scoped checkpoint lookup
- B15 · Checkpoints on disk — SQLite checkpoint durability
- B16 · Stop before the node — static interrupt_before checkpoints
- B17 · Ask before proceeding — interrupt payload and Command resume
- B18 · Update and route together — Command update and goto
- B19 · A graph inside a graph — compiled subgraph composition
- B20 · Configuration outside state — Runtime context versus mutable state
- I01 · Two branches, one result — parallel branches and explicit join
- I02 · Map a changing workload — dynamic Send fan-out and reduction
- I03 · Replay from a known point — checkpoint history and replay configuration
- I04 · Edit a saved state — update_state with as_node
- I05 · Compare two futures — branching from immutable checkpoint history
- I06 · Two decisions, one policy — separate interrupt stages and composite approval
- I07 · Memory beyond one thread — InMemoryStore namespaces
- I08 · Validate before orchestration — Pydantic validation at the graph boundary
- I09 · Async work without shared mutation — ainvoke and asynchronous node boundaries
- I10 · Retry the right failure — RetryPolicy and transient errors
- I11 · One operation, one receipt — idempotency keys and stored receipts
- I12 · An explicit fallback path — fallback routing without hiding failure
- I13 · A visible tool-call protocol — ToolNode and tools_condition loop
- I14 · Validate before invoking tools — tool allowlists and argument validation
- I15 · Edit without duplicating turns — message replacement and RemoveMessage
- I16 · A scoped specialist handoff — explicit specialist handoffs
- I17 · Ground the response — retrieval, provenance, and abstention
- I18 · Execute an explicit plan — bounded plan execution
- I19 · Keep a bounded context — bounded context and role boundaries
- I20 · Test behavior, not topology alone — behavioral evaluation for graph workflows
- A01 · A job that resumes — durable stepwise execution
- A02 · Evolve persisted application state — versioned payload migration
- A03 · A durable memory namespace — durable namespaced memory and SQL parameters
- A04 · Reject a lost update — optimistic version checks
- A05 · Record intent before dispatch — transactional outbox and idempotent dispatch
- A06 · Approval needs permission — authorization before interrupt resume
- A07 · A timeout is an outcome — async cancellation and timeout reporting
- A08 · Cache the right state — CachePolicy and pure-node input keys
- A09 · Stop an overlong graph — GraphRecursionError as a resource guard
- A10 · An exportable graph — graph exports and functional HTTP validation
- A11 · Authenticate before authorizing — authentication versus authorization
- A12 · Filter before exposing data — pre-execution tenant filtering
- A13 · Follow execution across spans — RunTree hierarchy and trace privacy
- A14 · Stop before spending the budget — pre-step budget enforcement
- A15 · Preserve partial evidence on failure — partial stream evidence and explicit failure
- A16 · A functional workflow — functional entrypoint and task boundaries
- A17 · Reusable specialist graphs — specialist subgraph contracts
- A18 · Verify what you saved — content hashes and artifact provenance
- A19 · Evaluate before release — dataset-driven release gates
- A20 · Measure every stage — node-level observability and privacy
- C01 · Support with a review boundary — durable support routing and review
- C02 · Evidence before publishing — retrieval provenance and publication gating
- C03 · A research and critique team — parallel specialist evidence and critique
- C04 · A recoverable batch pipeline — dynamic batch work and idempotent results
- C05 · An observable release workflow — end-to-end evaluation and release observability