LangGraph tutorial: build cyclic agents with state

LangChain Inc. Released LangGraph in 2024. It solves a specific problem: standard linear chains cannot handle stateful, cyclic agent workflows. This framework replaces simple request-response patterns with a graph architecture where State objects preserve conversation history across complex node interactions.

Instead of a straight line, the library uses graph data structures. Agents loop back for self-correction or branch conditionally based on real-time data. You will see how the `add_messages` function appends data to shared state, ensuring zero context loss. We will build a resume and job matching agent that leverages these integrated data sources. This guide provides the technical foundation to implement conditional routing logic effectively.

LangGraph as a Stateful Orchestration Framework for Cyclic AI Workflows

LangGraph as a Cyclic Directed Graph Framework

Linear execution chains hit a wall when an agent needs to think, check its work, and try again. LangGraph replaces that linear constraint with a cyclic directed graph. This shift enables iterative processing loops, allowing agents to perform self-correction and multi-step tool use that standard chains forbid.

The core is the State object, typically defined via Python's `TypedDict`. It carries context as it passes between nodes. Unlike transient query models, this design ensures conversation history and variables persist. A checkpointer mechanism saves state after every step. This prevents data loss during long-running agents or human-in-the-loop interrupts.

Explicit state definition creates a constraint. Developers gain granular control over execution flow but must manually schema every data exchange. This increases initial setup complexity compared to higher-level abstractions that hide state management. Omitting this rigor leads to agents that lose context or repeat work in production. The industry is pivoting toward these resilient, stateful agents. Builders must weigh the engineering overhead of strict schemas against the operational stability of persistent, checkpointed workflows.

Deploying Stateful Agents with TypedDict and Checkpointers

The TypedDict state structure passes context between nodes. The checkpointer mechanism persists data after every step. This architecture enables long-running agents to survive process restarts and maintain memory across sessions without data loss. By design, the framework allows agents to pause for human-in-the-loop interrupts, resuming exactly where execution stopped once input is received.

Substantial enterprises including Klarna, Uber, and J.P. Morgan trust this approach for building production-grade agents that handle complex workflows. These organizations use the shared state model to coordinate multi-agent systems where multiple specialized nodes read and write to a single source of truth.

Relying on shared state introduces coupling. If one node corrupts the State object, downstream nodes fail unpredictably. Builders must define strict schemas using `TypedDict` to prevent type errors during runtime. The cost of this durability is increased storage usage, as every step writes to disk rather than holding data in memory. For AI Agents News readers, understanding this limitation is vital when designing systems that require both durability and strict data consistency.

Low-Level Orchestration Control vs Higher-Level Abstractions

LangGraph operates as a low-level orchestration framework. It distinguishes itself from higher-level abstractions by providing direct control over state and execution flow. Think of it as a "full control panel" compared to simpler flowchart capabilities. It enables complex feedback loops that linear chains cannot support. Developers must decide if their use case requires this granular management or if a standard linear workflow suffices.

Flexibility demands increased engineering labor for initial setup and maintenance. Higher-level tools accelerate generic tasks yet often fail when bespoke logic dictates the information flow. Organizations requiring precise tool usage coordination benefit from the explicit graph structure. Simple query-response bots may not justify the complexity. The decision rests on whether the application demands iterative refinement or straightforward execution. See Substack.com/p/ for scenarios where linear processing proves insufficient.

Architectural Mechanics of Nodes Edges and Conditional Routing Logic

Python Units as Graph Nodes in LangGraph

LangChain Inc. Released LangGraph in 2024, establishing a distinct framework for stateful agent workflows. A LangGraph node operates as a discrete Python unit accepting the global State and returning specific updates. The State object holds application context, storing conversation messages alongside necessary variables.

These atomic execution blocks change raw functions into graph-aware components. They adhere to a strict input-output contract where the State object passes between them. Static pipeline steps simply process data. These units modify shared context, such as appending conversation history via the `add_messages` reducer.

Flexible Routing via Conditional Edges and State Changes

Conditional edges evaluate the current State object to determine the next execution path. They act as decision points within the workflow. Unlike Normal Edges that connect nodes sequentially, these flexible pathways inspect message content or variables to route logic branches. This mechanism prevents rigid linear chains by allowing the graph to loop back for refinement or jump to specialized tools based on real-time data. The framework supports cyclic directed graphs, enabling loops and iterative processing impossible in standard linear chains.

The routing function receives the full State dictionary and returns a string identifier for the target node. This approach addresses specific architectural gaps found in previous components like LCEL and AgentExecutor, enabling more complex agent behaviors.

Nodes sometimes return partial state updates. This leaves the routing function without the necessary context to make a valid decision. The framework requires that every possible return value from the conditional function maps to an existing node or the END terminal. This strict binding ensures the agent lifecycle remains predictable even with complex branching. Designing state schemas with explicit routing flags simplifies these conditional checks.

State Persistence Failures and Checkpointing Risks

LangGraph is architected specifically for long-running agents that maintain context over extended periods and multiple interaction turns. When a Conditional Edge routes execution based on stale data, the graph may enter invalid states if the State object was not correctly updated by the preceding node. This failure mode can break human-in-the-loop interrupts, as the system cannot reconstruct the context required to resume paused tasks.

By enabling long-running agents, the framework shifts cost considerations from simple token usage to sustained state management and memory storage, which impacts cloud storage and database costs.

The promise of persistent state remains theoretical during load spikes without proper configuration. Implementing strong error handling within node functions helps guarantee durability and predictable behavior.

Constructing a Resume and Job Matching Agent with Integrated Data Sources

Defining Pydantic Models for Resume and Job Data Structures

Creating Pydantic models inside a dedicated `modules` folder sets the rigid schema needed for stateful agent orchestration. Developers create a `resume.py` file to hold classes like `WorkExperience`, `Education`, and `Resume`, which standardize input validation before data enters the graph. The `Resume` class includes a `mock` method returning sample data for a user named Jeff, featuring roles at Company X and Company Y alongside specific language proficiencies.

Parallel definitions in `job.py` structure employment opportunities. Salary fields might span from $100,000 to $120,000 to test numeric filtering logic. This approach converts unstructured text into typed objects so the shared state schema remains consistent across nodes. Static mock objects limit the agent to predefined scenarios until flexible parsing for PDFs or web scrapers replaces these fixtures. Conditional edges may fail to route correctly when encountering malformed job requirements or missing education fields without this strict typing. Such structural rigor prevents downstream hallucination by constraining the large language model to verified data points in production systems.

Integrating Expert and Tools Nodes with LangGraph MessagesState

Connecting the Expert node to OpenAI's GPT-4o and the Tools node requires explicit state definitions to preserve context across cycles. Builders define a `State` schema using `MessagesState`, which mandates that every function returns an updated dictionary containing the full conversation history. This structure enforces a strict contract where the Expert node processes user queries against retrieved resume data for Jeff, while the Tools node fetches job listings without losing prior interaction details.

This TypedDict-set state ensures that context flows reliably between the LLM and external data sources, unlike implicit passing in earlier frameworks. The graph executes by passing this shared state object sequentially, allowing the model to reason over specific fields like professional summary or skills. Rigid state schemas increase initial boilerplate code and require precise type alignment between Pydantic models and graph inputs. Graph execution will fail on validation errors if developers do not map tool outputs exactly to state keys. Stability wins over rapid prototyping speed in this trade-off for production systems. The resulting architecture supports complex multi-turn reasoning where the agent iteratively refines job matches based on accumulated context.

Validating State Schemas and Node File Organization

Verify the Pydantic schema in `modules/resume.py` matches the graph's State definition before execution. Misaligned field names between the Resume model and the shared state cause silent data loss during node transitions. Developers must confirm that the `mock` method returns typed objects for Jeff, including roles at Company X and Company Y, rather than raw dictionaries.

A single type error loops indefinitely in the cyclic nature of LangGraph, consuming resources until the process crashes. Strict initial contracts matter because state persists across iterations in this cyclic flow. Treat the state definition as a binding interface; any deviation breaks the TypedDict-set state contract required for reliable orchestration. AI Agents News recommends validating these schemas statically to prevent runtime failures in production graphs.

Step-by-Step Implementation of a Production-Ready LangGraph Application

Defining the LangGraph State Schema

Context lives inside the State object, holding conversation messages and variables for the application. Developers declare this structure using a Python `TypedDict` to establish the exact data shape passed between nodes. Information flows from node to node as the State travels with it. Each node returns an updated State once processing finishes. A link is provided for more information on States at langchain-ai.github.io

The schema usually declares a `messages` key annotated with `add_messages`. New LLM outputs append to the history list instead of overwriting prior turns. The `add_messages` built-in function determines list updates when new data enters the State. This configuration creates a persistent memory layer where the LangGraph framework manages context retention automatically. Complex workflows become possible because the shared data structure preserves conversation history across multiple node invocations. Passing the State to the `StateGraph` class lets all graph nodes communicate by reading and writing to this shared state. Defining the State requires anticipating required fields upfront so nodes can communicate effectively. Explicit data contracts beat implicit dictionary passing for reliability. Production systems need this structure to maintain conversation history so that context is preserved between nodes. Interfaces set before connecting edges ensure reliable multi-step orchestration.

Implementation: Assembling Nodes in Python

Python files instantiate the graph structure by integrating nodes that perform specific actions. This entry point connects nodes powered by large language models, such as GPT-4o, with nodes responsible for retrieving data. LangChain team built LangGraph to help developers create graph-based single or multi-agent AI applications. Importing the `StateGraph` class starts the workflow topology definition. Assigning the State schema to the graph builder ensures message history persists across iterations without manual concatenation. A Node functions as a Python function performing actions like integrating with a large language model, processing information, or calling an external API.

Pitfalls in Conditional Edge Routing Logic

Incorrect routing happens when node return values fail to merge properly with the shared state. Conditional edges execute functions to determine the next node based on current state values. A preceding node returning a partial dictionary or skipping the add_messages reducer means the router may not see updated data.

1. Define explicit return structures in every Python function to guarantee full state synchronization.
2. Verify that nodes write to the shared context correctly before subsequent nodes evaluate the path.
3. Inspect the intermediate state payload to confirm list appends rather than overwrites during execution.

Graphs re-traverse steps or fail to reach the intended termination point without these checks. Decision points rely entirely on accurate state reflection to function as intended crossroads. State mutation acts as the primary signal for flow control. Rigorous validation of state transitions helps prevent routing failures in production deployments.

References

• LangGraph Review 2026: The Graph-Based Agent Framework Powering Enterprise
• LangGraph Tutorial: What Is LangGraph and How to Use
• A comprehensive guide to LangGraph, covering core concepts, graph