From c5b118a672393d69911d0b5fc866df90e3a1f745 Mon Sep 17 00:00:00 2001 From: William FH <13333726+hinthornw@users.noreply.github.com> Date: Tue, 8 Apr 2025 05:16:24 -0700 Subject: [PATCH] Add admonitions about managed checkpointers (#4197) If you're deploying with langgraph API, you don't need to manually define a checkpointer. For folks who already know they'll be developing with the api server, I'd like to save everyone time by making this more clear in the docs on checkpointing. --- docs/docs/concepts/persistence.md | 19 ++++++++++++++----- .../docs/how-tos/persistence-functional.ipynb | 4 ++++ docs/docs/how-tos/persistence.ipynb | 4 ++++ docs/docs/how-tos/persistence_postgres.ipynb | 6 +++++- .../langgraph/checkpoint/memory/__init__.py | 2 ++ 5 files changed, 29 insertions(+), 6 deletions(-) diff --git a/docs/docs/concepts/persistence.md b/docs/docs/concepts/persistence.md index 678b66a25..8b9981611 100644 --- a/docs/docs/concepts/persistence.md +++ b/docs/docs/concepts/persistence.md @@ -4,6 +4,10 @@ LangGraph has a built-in persistence layer, implemented through checkpointers. W ![Checkpoints](img/persistence/checkpoints.jpg) +!!! info "LangGraph API handles checkpointing automatically" + + When using the LangGraph API, you don't need to implement or configure checkpointers manually. The API handles all persistence infrastructure for you behind the scenes. + ## Threads A thread is a unique ID or [thread identifier](#threads) assigned to each checkpoint saved by a checkpointer. When invoking graph with a checkpointer, you **must** specify a `thread_id` as part of the `configurable` portion of the config: @@ -26,7 +30,7 @@ Let's see what checkpoints are saved when a simple graph is invoked as follows: ```python from langgraph.graph import StateGraph, START, END -from langgraph.checkpoint.memory import MemorySaver +from langgraph.checkpoint.memory import InMemorySaver from typing import Annotated from typing_extensions import TypedDict from operator import add @@ -49,7 +53,7 @@ workflow.add_edge(START, "node_a") workflow.add_edge("node_a", "node_b") workflow.add_edge("node_b", END) -checkpointer = MemorySaver() +checkpointer = InMemorySaver() graph = workflow.compile(checkpointer=checkpointer) config = {"configurable": {"thread_id": "1"}} @@ -223,6 +227,10 @@ But, what if we want to retain some information *across threads*? Consider the c With checkpointers alone, we cannot share information across threads. This motivates the need for the [`Store`](../reference/store.md#langgraph.store.base.BaseStore) interface. As an illustration, we can define an `InMemoryStore` to store information about a user across threads. We simply compile our graph with a checkpointer, as before, and with our new `in_memory_store` variable. +!!! info "LangGraph API handles stores automatically" + + When using the LangGraph API, you don't need to implement or configure stores manually. The API handles all storage infrastructure for you behind the scenes. + ### Basic Usage First, let's showcase this in isolation without using LangGraph. @@ -324,10 +332,10 @@ store.put( With this all in place, we use the `in_memory_store` in LangGraph. The `in_memory_store` works hand-in-hand with the checkpointer: the checkpointer saves state to threads, as discussed above, and the `in_memory_store` allows us to store arbitrary information for access *across* threads. We compile the graph with both the checkpointer and the `in_memory_store` as follows. ```python -from langgraph.checkpoint.memory import MemorySaver +from langgraph.checkpoint.memory import InMemorySaver # We need this because we want to enable threads (conversations) -checkpointer = MemorySaver() +checkpointer = InMemorySaver() # ... Define the graph ... @@ -440,6 +448,7 @@ Under the hood, checkpointing is powered by checkpointer objects that conform to * `langgraph-checkpoint-sqlite`: An implementation of LangGraph checkpointer that uses SQLite database ([SqliteSaver][langgraph.checkpoint.sqlite.SqliteSaver] / [AsyncSqliteSaver][langgraph.checkpoint.sqlite.aio.AsyncSqliteSaver]). Ideal for experimentation and local workflows. Needs to be installed separately. * `langgraph-checkpoint-postgres`: An advanced checkpointer that uses Postgres database ([PostgresSaver][langgraph.checkpoint.postgres.PostgresSaver] / [AsyncPostgresSaver][langgraph.checkpoint.postgres.aio.AsyncPostgresSaver]), used in LangGraph Cloud. Ideal for using in production. Needs to be installed separately. + ### Checkpointer interface Each checkpointer conforms to [BaseCheckpointSaver][langgraph.checkpoint.base.BaseCheckpointSaver] interface and implements the following methods: @@ -452,7 +461,7 @@ Each checkpointer conforms to [BaseCheckpointSaver][langgraph.checkpoint.base.Ba If the checkpointer is used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), asynchronous versions of the above methods will be used (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`). !!! note Note - For running your graph asynchronously, you can use `MemorySaver`, or async versions of Sqlite/Postgres checkpointers -- `AsyncSqliteSaver` / `AsyncPostgresSaver` checkpointers. + For running your graph asynchronously, you can use `InMemorySaver`, or async versions of Sqlite/Postgres checkpointers -- `AsyncSqliteSaver` / `AsyncPostgresSaver` checkpointers. ### Serializer diff --git a/docs/docs/how-tos/persistence-functional.ipynb b/docs/docs/how-tos/persistence-functional.ipynb index 7b9181992..91c1f786d 100644 --- a/docs/docs/how-tos/persistence-functional.ipynb +++ b/docs/docs/how-tos/persistence-functional.ipynb @@ -16,6 +16,10 @@ " - [Memory](../../concepts/memory/)\n", " - [Chat Models](https://python.langchain.com/docs/concepts/chat_models/)\n", "\n", + "!!! info \"Not needed for LangGraph API users\"\n", + "\n", + " If you're using the LangGraph API, you needn't manually implement a checkpointer. The API automatically handles checkpointing for you. This guide is relevant when implementing LangGraph in your own custom server.\n", + "\n", "Many AI applications need memory to share context across multiple interactions on the same [thread](../../concepts/persistence#threads) (e.g., multiple turns of a conversation). In LangGraph functional API, this kind of memory can be added to any [entrypoint()][langgraph.func.entrypoint] workflow using [thread-level persistence](https://langchain-ai.github.io/langgraph/concepts/persistence).\n", "\n", "When creating a LangGraph workflow, you can set it up to persist its results by using a [checkpointer](https://langchain-ai.github.io/langgraph/reference/checkpoints/#basecheckpointsaver):\n", diff --git a/docs/docs/how-tos/persistence.ipynb b/docs/docs/how-tos/persistence.ipynb index 4bbcfee9a..608add87c 100644 --- a/docs/docs/how-tos/persistence.ipynb +++ b/docs/docs/how-tos/persistence.ipynb @@ -31,6 +31,10 @@ "

\n", " \n", "\n", + "!!! info \"Not needed for LangGraph API users\"\n", + "\n", + " If you're using the LangGraph API, you needn't manually implement a checkpointer. The API automatically handles checkpointing for you. This guide is relevant when implementing LangGraph in your own custom server.\n", + "\n", "Many AI applications need memory to share context across multiple interactions. In LangGraph, this kind of memory can be added to any [StateGraph](https://langchain-ai.github.io/langgraph/reference/graphs/#langgraph.graph.StateGraph) using [thread-level persistence](https://langchain-ai.github.io/langgraph/concepts/persistence) .\n", "\n", "When creating any LangGraph graph, you can set it up to persist its state by adding a [checkpointer](https://langchain-ai.github.io/langgraph/reference/checkpoints/#basecheckpointsaver) when compiling the graph:\n", diff --git a/docs/docs/how-tos/persistence_postgres.ipynb b/docs/docs/how-tos/persistence_postgres.ipynb index 332c98cae..e32f1d2d1 100644 --- a/docs/docs/how-tos/persistence_postgres.ipynb +++ b/docs/docs/how-tos/persistence_postgres.ipynb @@ -26,6 +26,10 @@ "

\n", " \n", "\n", + "!!! info \"Not needed for LangGraph API users\"\n", + "\n", + " If you're using the LangGraph API, you needn't manually implement a checkpointer. The API automatically handles checkpointing for you. This guide is relevant when implementing LangGraph in your own custom server.\n", + "\n", "When creating LangGraph agents, you can also set them up so that they persist their state. This allows you to do things like interact with an agent multiple times and have it remember previous interactions.\n", "\n", "This how-to guide shows how to use `Postgres` as the backend for persisting checkpoint state using the [`langgraph-checkpoint-postgres`](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres) library.\n", @@ -44,7 +48,7 @@ "...\n", "```\n", "\n", - "!!! info \"Setup\"", + "!!! info \"Setup\"\n", "\n", " You need to run `.setup()` once on your checkpointer to initialize the database before you can use it." ] diff --git a/libs/checkpoint/langgraph/checkpoint/memory/__init__.py b/libs/checkpoint/langgraph/checkpoint/memory/__init__.py index 28e1696f1..863048240 100644 --- a/libs/checkpoint/langgraph/checkpoint/memory/__init__.py +++ b/libs/checkpoint/langgraph/checkpoint/memory/__init__.py @@ -38,6 +38,8 @@ class InMemorySaver( Only use `InMemorySaver` for debugging or testing purposes. For production use cases we recommend installing [langgraph-checkpoint-postgres](https://pypi.org/project/langgraph-checkpoint-postgres/) and using `PostgresSaver` / `AsyncPostgresSaver`. + If you are using the LangGraph Platform, no checkpointer needs to be specified. The correct managed checkpointer will be used automatically. + Args: serde (Optional[SerializerProtocol]): The serializer to use for serializing and deserializing checkpoints. Defaults to None.