langgraph

[Edit section]

[Copy link]

• • •

The LangGraph repository provides a framework for building graph-based language agents, enabling developers to create complex workflows and interactions between components in a state-based computation model. It is designed to facilitate the development of agentic and multi-agent systems, with a focus on fine-grained control over information flow and the incorporation of human-in-the-loop interactions.

The most important components of the LangGraph library are:

• Graph-Based Computation Model: Located in …/graph, this model is the foundation of LangGraph, allowing developers to define and execute computation graphs. The Graph and CompiledGraph classes enable the construction of nodes and edges to build complex workflows. The Graph class provides methods to add nodes and edges, while the CompiledGraph class manages data flow and graph execution. Graph-Based Computation Model

• State Management and Checkpoint Handling: The classes StateGraph and CompiledStateGraph, found in …/graph, extend the basic graph functionality to include state management, enabling nodes to share and update information during execution. The checkpoint system, with functionality in …/checkpoint, …/checkpoint-sqlite, and …/checkpoint-postgres, provides resilience for long-running agents by allowing workflows to persist their state. State Management and Checkpoint Handling

• Pregel Framework: Inspired by Google's Pregel system, the Pregel framework is a core part of LangGraph's execution model, facilitating efficient distributed graph processing. The …/pregel directory contains the necessary classes for this framework, including Channel, Pregel, ChannelRead, and PregelNode. It supports both synchronous and asynchronous task execution. Pregel-based Computation

• Managed Values: The …/managed directory includes the ManagedValue abstraction and its implementations, which handle dynamic data within graph executions. The SharedValue class, a type of WritableManagedValue, allows for sharing and updating dictionary-based values across different components. Managed Values

Key design choices in LangGraph include:

• A graph-based computation model for modular agent design.
• A robust checkpoint system for state persistence and resilience.
• The Pregel-inspired framework for distributed graph processing.
• A channel system for state-based communication between nodes.
• Managed values for dynamic data handling within graph executions.

LangGraph also provides SDKs for Python (…/sdk-py) and JavaScript/TypeScript (…/sdk-js) to interact with the LangGraph Cloud API, enabling the deployment and management of LangGraph-based applications in the cloud. LangGraph SDK

Core LangGraph Functionality

[Edit section]

[Copy link]

References: libs/langgraph/langgraph, libs/langgraph/langgraph/graph, libs/langgraph/langgraph/pregel, libs/langgraph/langgraph/pregel/manager.py

• • •

The core functionality of the LangGraph library is centered around the graph-based computation model, state management, and checkpoint handling. These components provide the foundation for building agentic and multi-agent systems with a focus on controllability, human-in-the-loop interactions, and streaming-first design.

Graph-Based Computation Model

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/graph

• • •

The Graph class is the main entry point for defining a computation graph in the LangGraph library. It provides methods to add nodes (add_node()), edges (add_edge()), and conditional edges (add_conditional_edges()). Nodes are defined as NodeSpec objects, which contain a Runnable and optional metadata.

State Management and Checkpoint Handling

[Edit section]

[Copy link]

References: libs/checkpoint, libs/checkpoint-sqlite, libs/checkpoint-postgres

• • •

In LangGraph's …/checkpoint directory, Checkpoint and CheckpointMetadata types are defined for representing the state of the system at specific points in time and storing associated metadata. The BaseCheckpointSaver class outlines the interface for saving and loading checkpoints, with implementations like MemorySaver for in-memory storage and SqliteSaver for persistent SQLite-based storage.

Store System

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/store

• • •

The BaseStore abstract class defines the interface for data store operations in LangGraph. It includes methods for listing and putting data, with both synchronous and asynchronous versions:

Pregel Framework

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel

• • •

The Pregel class manages graph-based computations, offering methods like stream() and astream() for executing the graph and streaming output. These methods support different stream modes such as "values", "updates", and "debug", allowing flexible output handling. The stream and astream methods utilize the get_async_callback_manager_for_config function for asynchronous iterator inputs, enhancing the handling of callback managers.

Configuration and Utility Functions

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/utils/config.py, libs/langgraph/langgraph/utils/runnable.py

• • •

The patch_configurable() function updates a RunnableConfig object with new configuration values, while patch_checkpoint_map() specifically updates the checkpoint map based on provided metadata. These functions allow for flexible configuration management within the LangGraph system.

Error Handling and Exceptions

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/errors.py

• • •

LangGraph introduces robust error handling mechanisms to manage specific error cases that may arise during graph execution. The …/errors.py file defines a suite of custom exceptions tailored to the library's needs, ensuring that developers can effectively handle errors related to graph delegation, checkpoint versioning, and more.

Task Management and Execution Flow

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel, libs/langgraph/langgraph/pregel/types.py, libs/langgraph/langgraph/pregel/executor.py, libs/langgraph/langgraph/pregel/loop.py, libs/langgraph/langgraph/pregel/runner.py, libs/langgraph/langgraph/pregel/debug.py

• • •

In the Pregel framework of the LangGraph library, task management and execution flow are orchestrated through a series of classes and functions designed to handle the complexities of graph-based computations. The execution flow is primarily managed by the PregelLoop class, which is responsible for running a single iteration of a Pregel-style graph computation. The tick() method within this class is pivotal, as it processes input, applies writes, produces output, and sets up the next set of tasks.

Constants and Configuration Keys

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/constants.py

• • •

In the LangGraph library, a variety of constants and configuration keys play a pivotal role in managing the execution flow and task management of graph-based computations. The file …/constants.py introduces constants that serve as identifiers for various operations and configurations within the system. These constants include:

Managed Values

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed

• • •

The ManagedValue abstraction in the LangGraph system provides a way to manage values in a graph-based computation model. The ManagedValue class is an abstract base class that defines the interface for managing values, including methods for entering and exiting a managed value context, as well as an abstract __call__ method that must be implemented by subclasses.

Managed Value Lifecycle and Context Management

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed/base.py, libs/langgraph/langgraph/pregel/manager.py

• • •

Within the LangGraph framework, the lifecycle of managed values is orchestrated through context management, which ensures that managed values are correctly instantiated, utilized, and disposed of. The introduction of ChannelKeyPlaceholder and ChannelTypePlaceholder has streamlined this process.

SharedValue Class

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed/shared_value.py

• • •

The SharedValue class extends WritableManagedValue to facilitate the sharing and updating of values within a LangGraph application. It is specifically designed to handle dictionary-based values, which are commonly used for state management across various components. The class provides a structured way to manage shared states, ensuring that updates and access to the shared values are handled in a consistent manner.

Serialization and Deserialization

[Edit section]

[Copy link]

References: libs/checkpoint/langgraph/checkpoint/serde

• • •

The …/serde directory contains code related to the serialization and deserialization of objects in the LangGraph project. The main functionality is provided by the SerializerProtocol protocol, which defines a consistent interface for serializing and deserializing objects, allowing the use of different serialization libraries interchangeably.

SerializerProtocol

[Edit section]

[Copy link]

References: libs/checkpoint/langgraph/checkpoint/serde/base.py

• • •

The SerializerProtocol defines an interface for object serialization and deserialization in the LangGraph system. It is implemented as a Protocol type, allowing for flexible implementations by various serialization libraries.

JsonPlusSerializer

[Edit section]

[Copy link]

References: libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py

• • •

The JsonPlusSerializer class provides custom JSON serialization and deserialization for the LangGraph project. It extends the SerializerProtocol interface and handles various data types, including custom classes and project-specific protocols.

LangGraph Cloud API

[Edit section]

[Copy link]

References: docs/docs/cloud/concepts, docs/docs/cloud/deployment

• • •

The LangGraph Cloud API provides a comprehensive platform for deploying and managing agentic and multi-agent systems built using the LangGraph library. The API offers a set of core data models, streaming functionality, human-in-the-loop interactions, and flexible deployment options.

Core Data Models

[Edit section]

[Copy link]

References: docs/docs/cloud/concepts/api.md

• • •

The Assistants data model in the LangGraph Cloud API represents configured instances of a CompiledGraph that encapsulate the cognitive architecture and metadata. These assistants can be invoked as Runs, which are individual executions of the assistant with their own input, configuration, and metadata.

Streaming Functionality

[Edit section]

[Copy link]

References: docs/docs/cloud/concepts/api.md

• • •

The LangGraph Cloud API supports various streaming modes to enable responsive and interactive applications. These streaming modes include:

Human-in-the-Loop Interactions

[Edit section]

[Copy link]

References: docs/docs/cloud/concepts/api.md

• • •

The LangGraph Cloud API provides functionality that enables human intervention during the execution of a graph, including solutions for handling double texting.

Deployment Options

[Edit section]

[Copy link]

References: docs/docs/cloud/deployment/cloud.md, docs/docs/cloud/deployment/self_hosted.md

• • •

The LangGraph Cloud API provides two main deployment options: using the LangSmith UI and self-hosting with Docker and Helm.

Local Testing and Configuration

[Edit section]

[Copy link]

References: docs/docs/cloud/deployment/test_locally.md, docs/docs/cloud/deployment/setup_pyproject.md

• • •

Local testing of LangGraph applications involves setting up the environment, starting the API server, and interacting with it using the LangGraph SDK. The process begins with installing the langgraph-cli package and obtaining a LangChain API key from the LangSmith UI.

Graph Definition and Rebuilding

[Edit section]

[Copy link]

References: docs/docs/cloud/deployment/setup.md, docs/docs/cloud/deployment/graph_rebuild.md

• • •

LangGraph applications can define graphs for deployment and dynamically rebuild them with different configurations at runtime. The make_graph() function in …/graph_rebuild.md demonstrates this capability:

Configuring Assistants

[Edit section]

[Copy link]

References: docs/docs/cloud/concepts/api.md

• • •

Within the LangGraph Cloud API, users have the flexibility to configure Assistants to suit specific use cases without the need to modify the underlying graph code. An Assistant is essentially a configured instance of a CompiledGraph that encapsulates the cognitive structure of the graph, complete with its own configuration and metadata tailored to the task at hand.

Webhooks

[Edit section]

[Copy link]

References: docs/docs/cloud/concepts/api.md

• • •

LangGraph Cloud API introduces a webhook system that notifies users upon the completion of runs. This feature is particularly useful for scenarios where runs are executed as background tasks or scheduled as cron jobs. When a run reaches completion, the webhook sends a notification, allowing for asynchronous workflows where immediate response to the run's outcome is not necessary.

Dependency and Package Management

[Edit section]

[Copy link]

References: docs/docs/cloud/deployment/setup.md, docs/docs/cloud/deployment/setup_pyproject.md

• • •

Managing dependencies and packages for LangGraph applications involves specifying required libraries and their versions to ensure consistent environments across development and deployment. The primary files used for this purpose are the requirements.txt and pyproject.toml.

Concurrent Operations Handling

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/enqueue_concurrent.md, docs/docs/cloud/how-tos/interrupt_concurrent.md, docs/docs/cloud/how-tos/reject_concurrent.md, docs/docs/cloud/how-tos/rollback_concurrent.md

• • •

Handling concurrent operations in the LangGraph Cloud API is managed through various strategies, each tailored to specific scenarios where multiple runs of a graph may occur simultaneously. These strategies include enqueue, interrupt, reject, and rollback, which are implemented in the runs.create() method of the LangGraph SDK.

Thread Management

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/check_thread_status.md, docs/docs/cloud/how-tos/copy_threads.md

• • •

The client.threads module provides functionality for managing threads in LangGraph Cloud. Key operations include:

LangGraph Studio Integration

[Edit section]

[Copy link]

References: docs/docs/cloud/faq/studio.md

LangGraph Studio serves as a development and testing environment for LangGraph projects, providing a visual interface for graph execution and debugging. Key features include:

API Reference and How-To Guides

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/cron_jobs.md, docs/docs/cloud/how-tos/stateless_runs.md, docs/docs/cloud/how-tos/webhooks.md

• • •

Through the LangGraph Cloud API, developers can orchestrate cron jobs with the create_for_thread() method, enabling scheduled execution of LangGraph-based applications. This method necessitates parameters like thread ID, assistant ID, a cron schedule expression, and an input object to define the execution timing and data. For scenarios where persistent state is not required, the API offers a method to create stateless cron jobs, which is detailed in the guide at …/cron_jobs.md.

Thread Operations

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos

• • •

The Client class provides methods for managing threads in LangGraph Cloud:

Shared State Management

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/shared_state.md

• • •

Shared state channels in LangGraph Cloud applications allow maintaining user-specific information across multiple runs and threads. The AgentState class defines a state schema using a shared value annotation to scope information to specific users. This approach enables isolation of shared state between different users.

LangGraph SDK

[Edit section]

[Copy link]

References: libs/sdk-py, libs/sdk-js

• • •

The LangGraph SDK provides Python and JavaScript/TypeScript libraries for interacting with the LangGraph Cloud API. These SDKs allow developers to manage assistants, threads, runs, and cron jobs programmatically.

Python SDK - RunsClient Methods

[Edit section]

[Copy link]

References: libs/sdk-py/langgraph_sdk/client.py

• • •

Within the Python SDK, the RunsClient class serves as a specialized interface for managing run operations against the LangGraph API. It is part of the broader LangGraphClient which is instantiated through the get_client() function and is designed to interact with the LangGraph API's run-related endpoints.

Python SDK - CronClient Method Parameters

[Edit section]

[Copy link]

References: libs/sdk-py/langgraph_sdk/client.py

• • •

Within the Python SDK of LangGraph, the CronClient class plays a crucial role in managing cron jobs, which are scheduled tasks that can be set to run at specific intervals. A significant method within this class is create_for_thread, which facilitates the creation of cron jobs for specific threads within the LangGraph system. This method has undergone an update, introducing the multitask_strategy parameter. This new parameter is pivotal as it dictates the behavior of the cron job when dealing with multiple tasks. It has effectively replaced the previously used config parameter, streamlining the process of cron job creation and providing a more direct way to specify multitasking strategies.

JavaScript/TypeScript SDK

[Edit section]

[Copy link]

References: libs/sdk-js

• • •

The JavaScript/TypeScript SDK for interacting with the LangGraph Cloud API provides a set of utilities and data structures for working with the LangGraph system. The core functionality of the SDK is implemented in the …/src directory, with the build process and configuration managed by the scripts in the …/scripts directory.

Examples and Patterns

[Edit section]

[Copy link]

References: docs/docs/tutorials/llm-compiler, libs/cli/examples/graphs_reqs_a, libs/cli/examples/graphs_reqs_b

• • •

The …/llm-compiler directory contains an example implementation of an LLM (Language Model) compiler that enables a language model to solve mathematical problems and parse the output of the compiler.

Conversational Agent Examples

[Edit section]

[Copy link]

References: libs/cli/examples/graphs_reqs_a, libs/cli/examples/graphs_reqs_b

• • •

The …/graphs_reqs_a and …/graphs_reqs_b directories contain example implementations of conversational agents that use language models and search tools to engage in state-based workflows.

Graphs Reqs A

[Edit section]

[Copy link]

References: libs/cli/examples/graphs_reqs_a/graphs_submod

• • •

The key components in the …/graphs_submod directory are:

Graphs Reqs B

[Edit section]

[Copy link]

References: libs/cli/examples/graphs_reqs_b/graphs_submod, libs/cli/examples/graphs_reqs_b/utils

• • •

The …/graphs_reqs_b directory contains an example implementation of a conversational agent that uses language models and a search tool to engage in a state-based workflow. The key components of this implementation are:

LLM Compiler Tools

[Edit section]

[Copy link]

References: docs/docs/tutorials/llm-compiler/math_tools.py, docs/docs/tutorials/llm-compiler/output_parser.py

• • •

The StructuredTool is designed to solve mathematical problems using the OpenAI language model. It accepts mathematical expressions or word problems as input and leverages the numexpr library to evaluate and return numerical results. The tool ensures consistent and predictable problem-solving by utilizing structured output and prompt templates. These templates guide the language model, providing a system prompt defined in _SYSTEM_PROMPT and additional context when necessary through _ADDITIONAL_CONTEXT_PROMPT.

Web Navigation Example

[Edit section]

[Copy link]

References: docs/docs/tutorials/web-navigation/mark_page.js

• • •

In the context of LangGraph applications, web navigation tools are exemplified by the JavaScript implementation in …/mark_page.js. The script enhances user interaction with web pages by visually marking clickable elements, aiding in the identification and navigation of these elements during automated or manual testing.

Human-in-the-Loop Operations

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/human_in_the_loop_edit_state.md, docs/docs/cloud/how-tos/human_in_the_loop_user_input.md, docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md, docs/docs/cloud/how-tos/human_in_the_loop_breakpoint.md, docs/docs/cloud/how-tos/human_in_the_loop_review_tool_calls.md

• • •

LangGraph facilitates human-in-the-loop operations, allowing for dynamic interaction and intervention in graph execution. Key operations include:

Time Travel Operations

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md

• • •

LangGraph provides a mechanism for "time travel" operations, allowing users to replay and branch from previous states within a graph. This capability is essential for scenarios where developers need to test different outcomes based on historical states or when a human-in-the-loop needs to intervene and alter the course of execution.

SQLite Checkpoint Saver

[Edit section]

[Copy link]

References: libs/checkpoint-sqlite/langgraph/checkpoint/sqlite

• • •

The SQLite Checkpoint Saver provides a persistent storage solution for graph state checkpoints using a SQLite database. It offers both synchronous and asynchronous implementations through the SqliteSaver and AsyncSqliteSaver classes, respectively.

Synchronous Operations with SqliteSaver

[Edit section]

[Copy link]

References: libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py

• • •

The SqliteSaver class provides synchronous operations for storing and retrieving checkpoints using a SQLite database. Key methods include:

Configuration and Initialization of SqliteSaver

[Edit section]

[Copy link]

References: libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py

• • •

The SqliteSaver class is initialized with a sqlite3.Connection object and an optional SerializerProtocol instance. The from_conn_string class method provides a convenient way to create a SqliteSaver instance from a connection string:

Asynchronous Operations with AsyncSqliteSaver

[Edit section]

[Copy link]

References: libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py

• • •

The AsyncSqliteSaver class in …/aio.py facilitates asynchronous checkpoint management in a SQLite database. It handles operations without blocking the main execution thread, allowing concurrent tasks to proceed efficiently.

Configuration and Initialization of AsyncSqliteSaver

[Edit section]

[Copy link]

References: libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py

• • •

The AsyncSqliteSaver class is initialized with an aiosqlite.Connection object, which allows it to perform database operations asynchronously. During initialization, the loop attribute is set to the currently running event loop, which is crucial for the class to execute its asynchronous methods such as aget_tuple(), alist(), aput(), and aput_writes(). These methods correspond to their synchronous counterparts but are designed to work within an asynchronous programming environment.

LangGraph Studio

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos

• • •

LangGraph Studio is a visual tool for testing and debugging LangGraph configurations. It provides a graphical interface to observe node execution and outputs in real-time, enhancing the development process for LangGraph applications.

LangGraph Studio Desktop Overview

[Edit section]

[Copy link]

References: docs/docs/cloud/quick_start.md

• • •

LangGraph Studio Desktop serves as a visualization and interaction tool for developers working with complex agentic applications. It facilitates the development process by providing a graphical interface where users can:

LangGraph Studio Integration with LangGraph Cloud

[Edit section]

[Copy link]

References: docs/docs/cloud/quick_start.md, docs/docs/cloud/how-tos

• • •

LangGraph Studio serves as an interactive interface for users to set up, test, and manage cloud deployments of their LangGraph applications. Through the studio, users can access a variety of functionalities that streamline the development and deployment process:

LangGraph Studio FAQs and Troubleshooting

[Edit section]

[Copy link]

References: docs/docs/cloud/faq/studio.md

LangGraph Studio serves as a development and testing environment for LangGraph projects, providing tools for visualizing and debugging graph configurations. Users may encounter issues related to Docker, project configuration, or the Studio's features such as the "Interrupts" dropdown. The following points address common questions and offer troubleshooting advice:

Deprecation and API Management

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/_api

• • •

The LangGraph library provides mechanisms for handling deprecation and managing API changes through the LangGraphDeprecationWarning class and two decorators: deprecated() and deprecated_parameter().

Testing Framework and Practices

[Edit section]

[Copy link]

References: libs/langgraph/tests, libs/checkpoint-sqlite/tests, libs/checkpoint-postgres/tests

• • •

In the LangGraph library, the …/tests directory serves as the central hub for unit testing, encompassing a variety of test cases that validate the functionality of the library's components. The tests are designed to validate features such as state management and the Pregel graph processing framework.

Unit Testing Structure and Conventions

[Edit section]

[Copy link]

References: libs/langgraph/tests

• • •

Within the …/tests directory, test cases are organized to validate the functionalities of the LangGraph library. Tests are categorized to reflect the specific components they assess, such as channel implementations, state management, and Pregel graph processing. Naming conventions for test files are systematic, with each file name indicating the component or feature under test, such as test_channels.py for channel-related tests and test_pregel.py for tests concerning the Pregel computation model.

Testing Pregel and Graph Functionality

[Edit section]

[Copy link]

References: libs/langgraph/tests/test_pregel.py

• • •

In the LangGraph library, the Pregel class is central to the execution of graph-based workflows, with a focus on testing its robustness across various scenarios. The …/test_pregel.py file encapsulates a suite of tests that ensure the Pregel class and its associated Graph and StateGraph classes behave as expected under different conditions.

Testing Asynchronous Operations and Error Handling

[Edit section]

[Copy link]

References: libs/langgraph/tests/test_pregel_async.py

• • •

In the LangGraph library, the file …/test_pregel_async.py is dedicated to ensuring the robustness of asynchronous operations within the Pregel class. The tests are designed to validate the behavior of the system under various conditions that could occur during asynchronous graph computation. Key areas covered by these tests include:

Testing Checkpoint Saver Implementations

[Edit section]

[Copy link]

References: libs/checkpoint-sqlite/tests, libs/checkpoint-postgres/tests

• • •

In the LangGraph library, the testing of checkpoint saver implementations is essential for verifying the integrity of the checkpointing system. The SqliteSaver and PostgresSaver classes, located in …/checkpoint-sqlite and …/checkpoint-postgres respectively, are subjected to rigorous tests to ensure their reliability in saving and retrieving checkpoints.

Testing State Management and Schema Features

[Edit section]

[Copy link]

References: libs/langgraph/tests/test_state.py

• • •

In the LangGraph library, the StateGraph class is central to managing the flow and schema of application states. Testing for this class, as demonstrated in …/test_state.py, involves validating state schemas that may include type hints, optional fields, and default values. The tests ensure that developers receive appropriate warnings when defining invalid state schemas, while valid schemas pass without issue.

Pregel-based Computation

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel

• • •

The Pregel class serves as the main entry point for running graph computations in LangGraph. It implements a Pregel-based computation model, which is designed for distributed processing of large-scale graphs. The core concepts of Pregel include:

Pregel Algorithm Implementation

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/algo.py, libs/langgraph/langgraph/pregel/__init__.py, libs/langgraph/langgraph/pregel/types.py

• • •

The Pregel algorithm implementation in LangGraph is centered around the prepare_next_tasks() function in …/algo.py. This function serves as the main entry point for executing the Pregel algorithm, determining which tasks should run in the next step based on channel changes. The core workflow includes:

Asynchronous Execution

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/loop.py, libs/langgraph/langgraph/pregel/__init__.py

• • •

The AsyncPregelLoop class in …/loop.py facilitates asynchronous execution of Pregel-style graph computations, enhancing performance and scalability. It operates similarly to its synchronous counterpart, SyncPregelLoop, but is tailored for asynchronous operations. The class manages the execution of tasks within the graph, handling input, output, and checkpoint data, as well as interrupts and subgraph delegation.

Task Configuration and Metadata

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/algo.py, libs/langgraph/langgraph/pregel/read.py

• • •

In the Pregel framework of the LangGraph library, task configuration and metadata play a crucial role in managing the execution flow of graph-based computations. The PregelNode class, found in …/read.py, serves as a central component for configuring tasks within the Pregel model. It encapsulates the logic for reading from and writing to channels, which are the conduits for data flow between different nodes in the computation graph. The PregelNode class allows for the association of metadata and tags with each node, which can be used to store additional information about the task or to influence the execution behavior.

Channel Management and Communication

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/read.py, libs/langgraph/langgraph/pregel/manager.py

• • •

The ChannelRead class in …/read.py manages reading data from channels. It supports:

Graph Configuration and Validation

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/__init__.py

The Pregel class serves as the primary interface for configuring and executing graph computations. It offers several configurable attributes:

Checkpoint Handling and State Management

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/__init__.py, libs/langgraph/langgraph/pregel/types.py

• • •

Within the Pregel framework of the LangGraph library, the Pregel class serves as the central component for checkpoint handling and state management. It leverages a BaseCheckpointSaver to persist the state of the graph, allowing progress to be saved and resumed as needed. This is useful for long-running or complex graph computations where resilience against interruptions is desired.

Stream Protocol Interface

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel/loop.py

• • •

The introduction of the StreamProtocol interface in the Pregel framework marks a significant enhancement to the streaming capabilities within LangGraph. This interface standardizes the way streams are handled, allowing for a more structured approach to sending and receiving data during the execution of Pregel-style graph processing algorithms. The StreamProtocol is particularly crucial in scenarios where output values need to be sent to a configured stream, such as in the case of distributed graph processing where nodes may need to communicate results or updates.

PostgreSQL Checkpoint Saver

[Edit section]

[Copy link]

References: libs/checkpoint-postgres/langgraph/checkpoint/postgres

• • •

The PostgresSaver class, inheriting from BasePostgresSaver, manages checkpoints in a PostgreSQL database. Key functionalities include:

Synchronous and Asynchronous Implementations

[Edit section]

[Copy link]

References: libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py, libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py

• • •

The PostgresSaver and AsyncPostgresSaver classes provide synchronous and asynchronous implementations for storing and retrieving graph state checkpoints using a PostgreSQL database.

Database Setup and Migration

[Edit section]

[Copy link]

References: libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py, libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py

• • •

The PostgresSaver and AsyncPostgresSaver classes handle database setup and migration for the PostgreSQL checkpoint saver. Key aspects of this process include:

Checkpoint Operations

[Edit section]

[Copy link]

References: libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py, libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py

• • •

The PostgresSaver and AsyncPostgresSaver classes provide methods for managing checkpoints in a PostgreSQL database:

Connection and Cursor Management

[Edit section]

[Copy link]

References: libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py, libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py

• • •

In the LangGraph system, the PostgreSQL checkpoint saver utilizes the _get_connection and _cursor context managers to handle database connections and cursors, which are essential for performing database operations such as storing and retrieving checkpoints. These context managers are defined in …/__init__.py and are crucial for ensuring that database interactions are thread-safe and efficient.

Channel Versions

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel, libs/checkpoint/langgraph/checkpoint/base

• • •

Channel versions in LangGraph are managed through a system of version tracking and updating. The Pregel class handles the core functionality for managing channel versions during graph execution.

Channel Version Management

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel

• • •

Channel version management in LangGraph is implemented primarily through the get_new_channel_versions() function in …/utils.py. This function compares two sets of ChannelVersions to determine which channels have been updated:

Version Consistency and State Management

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/pregel

• • •

Channel versions are used to maintain consistent state across the Pregel graph. The get_new_channel_versions function in …/utils.py compares previous and current versions, returning only updated channels. This ensures efficient state tracking by identifying changes between iterations.

Version Utility Functions

[Edit section]

[Copy link]

References: libs/checkpoint/langgraph/checkpoint/base

• • •

The get_next_version() method in BaseCheckpointSaver generates the next version ID for a channel. It takes the current versions and new versions as input, comparing them to determine if an update is needed. The method returns either the existing version if no update is required, or a new UUID-6 if an update is necessary.

LangGraph Studio FAQs

[Edit section]

[Copy link]

References: docs/docs/cloud/faq

When working with the LangGraph Studio, developers may encounter a range of questions and issues. The FAQs in the …/studio.md file address these concerns, providing clarity on the LangGraph Studio's features and troubleshooting advice. Key points from the FAQs include:

How does interrupt work?

[Edit section]

[Copy link]

References: docs/docs/cloud/faq/studio.md

• • •

The interrupt functionality in LangGraph Studio allows developers to pause graph execution at specific points for inspection and debugging. When an interrupt is set on a node:

How does automatic rebuilding work?

[Edit section]

[Copy link]

References: docs/docs/cloud/faq/studio.md

• • •

Automatic rebuilding in LangGraph Studio handles changes to source code, configuration, and dependencies. The process involves:

Why are extra edges showing up in my graph?

[Edit section]

[Copy link]

References: docs/docs/cloud/faq/studio.md

• • •

Extra edges appearing in graphs within LangGraph Studio can be caused by improper configuration of the path map or incorrect typing of the router function. To resolve this issue:

Thread Operations in LangGraph Cloud

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos

• • •

Within the LangGraph Cloud platform, thread operations are integral to managing the flow and history of interactions. The LangGraph SDK facilitates a variety of thread manipulations, enabling users to effectively control the lifecycle and state of threads in their applications.

Checking Thread Status

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/check_thread_status.md

• • •

To monitor the execution state of threads within the LangGraph Cloud platform, the client.threads module provides essential methods. Developers can utilize this module to query the status of threads, which can be in various states such as idle, interrupted, or busy. The status of a thread indicates its current activity within the system, and understanding how to check this status is crucial for managing the execution flow of LangGraph applications.

Copying Threads

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/copy_threads.md

• • •

To replicate an existing thread within the LangGraph cloud platform, the client.threads.copy() method is utilized. This operation is essential when an independent run of a thread is needed, ensuring that the original thread remains unaffected. The process involves the following steps:

Concurrent Operations Handling

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/enqueue_concurrent.md, docs/docs/cloud/how-tos/interrupt_concurrent.md, docs/docs/cloud/how-tos/reject_concurrent.md, docs/docs/cloud/how-tos/rollback_concurrent.md

• • •

LangGraph Cloud provides a robust mechanism for handling concurrent operations within a graph through the client.runs.create() method, which accepts a multitask_strategy parameter. This parameter can be set to different strategies such as interrupt, rollback, reject, and enqueue, each designed to manage concurrent runs in a specific manner.

Human-in-the-Loop Thread Management

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/human_in_the_loop_breakpoint.md, docs/docs/cloud/how-tos/human_in_the_loop_edit_state.md, docs/docs/cloud/how-tos/human_in_the_loop_review_tool_calls.md, docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md, docs/docs/cloud/how-tos/human_in_the_loop_user_input.md

• • •

Incorporating human oversight into thread operations within LangGraph involves a series of methods that allow for the interruption of execution, state editing, and review of tool calls. These methods facilitate human-in-the-loop (HIL) interactions, where a human operator can intervene in the automated processes of a LangGraph agent.

State Replay and Branching

[Edit section]

[Copy link]

References: docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md

• • •

Within the LangGraph Cloud platform, threads can be manipulated to replay or branch from specific states, a process that is facilitated by the client.runs.stream() method. This method is essential for rerunning a graph from a designated state, which is identified by a checkpoint_id. To prepare for either replaying or branching, the thread state is first updated with an empty message. This step is crucial as it sets the stage for the graph to be rerun from the chosen state.

Command-Line Interface (CLI)

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli

The LangGraph library's Command-Line Interface (CLI) is a pivotal tool for developers to manage and interact with LangGraph applications. The CLI leverages the Click library to provide a user-friendly interface with commands that control various aspects of application management, from starting the server to running tests and preparing for deployment.

CLI Commands and Usage

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli/cli.py

• • •

The LangGraph Command-Line Interface (CLI) is equipped with a suite of commands to streamline the management of LangGraph applications. The up command launches the LangGraph API server, offering options for customization such as alternative Docker Compose files via --docker-compose, configuration through --config, and port selection with --port. For validation purposes, the test command initiates a test server to verify the API server's functionality prior to deployment on LangGraph Cloud.

Configuration Management

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli/config.py

• • •

In …/config.py, the LangGraph CLI uses a Config TypedDict to encapsulate the necessary parameters for setting up the API server environment. The configuration includes fields such as python_version, pip_config_file, dockerfile_lines, and node_version, which are used for creating a compatible and functional server environment.

Docker Integration and Utilities

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli/docker.py

• • •

The LangGraph CLI leverages Docker to streamline the deployment process of LangGraph applications. It includes a set of utilities encapsulated in the …/docker.py module, which facilitates Docker Compose configurations and the integration of a debugger service.

Asynchronous Subprocess Execution

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli/exec.py

• • •

In the LangGraph CLI, the …/exec.py file plays a pivotal role in facilitating the execution of subprocesses asynchronously. The Runner context manager is central to this functionality, providing a streamlined way to execute asynchronous code. It leverages the asyncio.Runner class when available, or falls back to a custom implementation _Runner for environments where asyncio.Runner might not be present.

Progress Reporting Mechanism

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli/progress.py

• • •

The Progress class in …/progress.py enhances the user experience during command-line operations that may take an extended period to complete. It provides visual feedback in the form of a spinning cursor animation, indicating that a process is ongoing. The class is designed to be used as a context manager, which simplifies the management of starting and stopping the animation during such operations.

Version and Analytics Management

[Edit section]

[Copy link]

References: libs/cli/langgraph_cli/version.py, libs/cli/langgraph_cli/analytics.py

• • •

Retrieving the current version of the LangGraph CLI tool is managed by the version.py file located at …/version.py. The version information is crucial for users to identify the build they are working with, especially when reporting issues or seeking help. The retrieval process uses the metadata.version() function to obtain the version string of the langgraph package, which is then stored in the __version__ variable. In cases where the package metadata is not available, a fallback mechanism sets the __version__ variable to an empty string, ensuring that the CLI tool can handle such scenarios gracefully.

Shared Values

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed

• • •

The SharedValue class, located in …/shared_value.py, provides a mechanism for sharing and updating values across different components of a LangGraph application. As a subclass of WritableManagedValue, it offers a flexible interface for managing shared state.

SharedValue Class

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed/shared_value.py

• • •

The SharedValue class, a subclass of WritableManagedValue, provides functionality for sharing and updating dictionary-based values across different components of a LangGraph application. Key features include:

Configuration and Initialization

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed/shared_value.py

• • •

The SharedValue class provides a mechanism for configuring and initializing shared values across different components of a LangGraph application. Configuration is primarily done using the static on() method, which returns a ConfiguredManagedValue instance. This method allows users to specify the scope, key, and type of the shared value.

Value Management and Updates

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed/shared_value.py

• • •

The SharedValue class manages dictionary-based values, allowing for sharing and updating across different components of a LangGraph application. Values are stored internally and can be retrieved using the __call__() method, which returns a copy of the current value.

Integration with BaseStore

[Edit section]

[Copy link]

References: libs/langgraph/langgraph/managed/shared_value.py, libs/langgraph/langgraph/store

• • •

The SharedValue class integrates with BaseStore to provide persistent storage of shared values across different components of a LangGraph application. This integration is achieved through the following mechanisms: