LangGraph & Deep Agents Reference Architecture

Architecture

Production multi-agent applications require a deterministic control plane to coordinate autonomous model decisions, isolate scratchpad memory, persist state across process restarts, and enforce human approval boundaries.

The LangGraph & Deep Agents Reference Architecture compiles agentic workflows into Bulk Synchronous Parallel (BSP) Pregel state machines:

Probabilistic models contribute judgment during supervisor routing and worker tool selection, while deterministic software owns graph state channels, reducers (add_messages), checkpoint persistence, and security approval gates.

Topology Comparison

| Topology | State Isolation | Parallel Execution | Debuggability | Complexity | Best For | |---|---|---|---|---|---| | Supervisor Routing | High (Isolated worker subgraphs) | Yes (Concurrent fan-out) | High (Superstep traces) | Medium | 2–5 specialized worker agents | | Hierarchical Sub-Supervisors | Very High (Nested team state) | Yes (Multi-tier parallel) | Medium (Sub-tree traces) | High | 10+ distinct domain tools | | Decentralized Swarms | Low (Shared context buffer) | No (Sequential hand-off) | Low (Non-deterministic path) | Low | Peer brainstorming |

State Isolation & Context Hygiene

As tasks progress, sub-agent tool execution logs (API payloads, DOM trees, compiler logs) inflate context windows and cause model hallucination.

To maintain context hygiene:

• Parent Graph State: Retains global user intent, supervisor routing decisions, and unified response messages.
• Worker Subgraph Scratchpad: Ephemeral memory allocated solely for worker tool iterations.
• Message Handoffs: Worker subgraphs return concise summaries back to the supervisor via channel reducers, discarding raw tool execution logs before global prompt assembly.

Durable Checkpointing & Human-in-the-Loop

High-consequence side effects (financial transactions, infrastructure changes, code deployment) require durable state persistence and explicit human authorization.

CheckpointRecord = AsyncPostgresSaver.serialize(ThreadID, SuperstepIndex, ChannelState)

1. Interrupt Gates: Configure interrupt_before=["execute_action"] on sensitive nodes.
2. State Serialization: Pregel serializes active state to Postgres via JSONPlusSerializer.
3. Human Inspection & Modification: Operators review pending state and can approve or update state variables via graph.update_state().
4. Asynchronous Resumption: Execution resumes from the exact thread checkpoint without re-running prior model inference calls.

Failure Defenses & Safeguards

• Recursion Limits: Enforce recursion_limit: 25 on all Pregel.invoke() calls to prevent runaway cyclic routing.
• Race-Free Reducers: Use pure channel reducers (add_messages) to merge parallel subgraph outputs atomically during barrier flushes.
• Tool Injection Interceptors: Validate all tool inputs against strict Zod schemas before passing arguments to execution boundaries.

Decisions

| Decision | Required evidence | Review trigger | |---|---|---| | Isolate worker scratchpad memory from global parent graph state. | Trace inspection showing sub-agent scratchpad discarded at exit | Context token bill exceeding budget | | Require Postgres checkpointer persistence for all HITL interrupt gates. | Database audit showing serialized thread checkpoints | Unhandled worker process restart during approval | | Enforce strict recursion limits and barrier flushes on cyclic graphs. | Integration test verifying termination at max supersteps | Agent loop exceeding step threshold |

Alternatives and trade-offs

Flat supervisor routing provides clear auditability and low latency for 2–5 sub-agents. Decentralized swarms reduce orchestrator token costs but sacrifice deterministic governance and replayability.

Failure modes

• Worker scratchpad logs leaking into the parent supervisor prompt window.
• Un-serializable objects (socket handles, DB connections) stored in graph state.
• Supervisor ping-ponging between two workers without reaching termination.

Operational checklist

• [ ] Every Pregel graph has an explicit recursion_limit configured.
• [ ] High-consequence tool nodes enforce interrupt_before approval gates.
• [ ] Postgres checkpointer connection pool handles asynchronous worker restarts.
• [ ] Subgraph channel reducers use pure functions without side effects.

Connected practice

• Labs: /labs/agent-loop-tool-selection
• System breakdowns: /systems/inside-langgraph

Sources

• langgraph-repo
• anthropic-effective-agents
• anthropic-trustworthy-agents