Agent Development Guidelines

This document provides guidance for AI coding assistants working with the LangGraph codebase.

Project Structure

LangGraph is organized as a Python monorepo:

libs/langgraph/ — Core graph library
libs/checkpoint/ — Persistence and checkpointing backends
libs/cli/ — Command-line interface tools
libs/sdk/ — Client SDKs for LangGraph Platform
docs/ — Documentation and tutorials
examples/ — Example agent implementations

Development Principles

Graph-First Design

All agent behavior should be expressible as a state graph. Avoid hidden control flow outside of the graph definition. Nodes should be pure functions of state where possible.

State Management

State schemas use TypedDict for type safety
State updates are partial — only return the fields that changed
Use Annotated types with reducers for complex state merging (e.g., message lists)

Testing

Unit tests for individual nodes should mock external dependencies
Integration tests should verify full graph execution with checkpointing
Use langgraph.pregel.testing utilities for graph-level assertions

Error Handling

Nodes should raise specific exceptions, not generic Exception
Graph-level error handling uses on_error edges
Retry logic belongs in the node implementation, not the graph structure

Code Style

Follow PEP 8 with Black formatting
Type hints required on all public APIs
Docstrings in Google style format
Maximum line length: 120 characters

Key Concepts for Contributors

Pregel execution model: LangGraph uses a Pregel-inspired execution model where nodes execute in supersteps and communicate through state channels
Checkpointing: Every superstep boundary creates a checkpoint, enabling resume from any point
Interrupts: Human-in-the-loop is implemented via interrupt nodes that pause execution and persist state

Common Pitfalls

Do not mutate state in place — always return new state dicts
Conditional edges must return a string matching a defined node name or END
Avoid circular imports between langgraph.graph and langgraph.pregel