[Service Name] · LangGraph orchestration

A multi-agent state machine. Nodes are agents, edges are decisions, state is typed. Checkpoints let you pause, inspect, and resume. Human-in-the-loop where the cost of being wrong is high.

Source of truth

Production runs as a FastAPI service on Fly. Postgres stores checkpoints (LangGraph's PostgresSaver). Every graph run is replayable from any checkpoint.

Tech stack

Python 3.13 + LangGraph 0.3+ + LangChain (only the lightweight prompt + tool bindings). Anthropic Claude for reasoning, OpenAI for tool calls when JSON-structured-output is the constraint. FastAPI for the run-orchestration API. PostgreSQL via PostgresSaver for checkpoints. Pydantic v2 for state schemas.

Deploy

fly deploy. Postgres on Fly with the langgraph_checkpoints table created by LangGraph migrations.

File map

• app/graph.py graph definition: nodes, edges, conditional routing
• app/state.py Pydantic State TypedDict (the central state object)
• app/nodes/researcher.py, writer.py, critic.py one file per agent
• app/tools/ shared tools (web search, file read, code interpreter)
• app/api.py FastAPI: POST /runs + GET /runs/{thread_id}/state
• app/checkpoint.py PostgresSaver setup
• prompts/ system prompts per node, version-controlled

.env keys

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• DATABASE_URL
• TAVILY_API_KEY (if you use Tavily for web search)
• MAX_GRAPH_STEPS default 30 (cycle protection)

Hard rules

• State is typed end-to-end. NO untyped dicts in state. Pydantic models or it doesn't ship.
• Every node is pure: same state in -> same state out (modulo LLM nondeterminism). No side effects in nodes; side effects go through tools.
• Conditional edges return a string identifier, never a node function reference. Keeps the graph serializable.
• Checkpoint after every node, not just at end. Mid-graph crashes happen.
• Human-in-the-loop nodes use interrupt() (LangGraph 0.3+). The graph pauses; the API surfaces the interrupt; resume with Command(resume=...).
• Cap graph recursion. Cycle prevention is YOUR job, not LangGraph's.

Recent significant changes

• 2026-05-17: Scaffolded. Locked: LangGraph over building from scratch (the state + checkpoint machinery is non-trivial), Pydantic for state typing, PostgresSaver over in-memory (production survives restarts).

Next session: start here

1. Define your state schema in app/state.py. Start tiny; you can add fields.
2. Write the simplest possible graph: one node, one edge to END. Confirm it runs.
3. Add nodes incrementally. After each, run a fresh thread end-to-end and read the checkpoint history.
4. Add a critic node early. It catches loops + dead ends faster than you will.
5. Build eval/ with 10 representative inputs + expected final-state assertions before adding more nodes.