From edb4bdcf2b772fd493524e231622f5e8f61216bc Mon Sep 17 00:00:00 2001 From: Caspar Broekhuizen Date: Thu, 30 Oct 2025 08:43:53 -0700 Subject: [PATCH 1/3] docs(langgraph): add docs on Overwrite --- src/oss/langgraph/graph-api.mdx | 7 ++++ src/oss/langgraph/use-graph-api.mdx | 54 ++++++++++++++++++++++++++++- 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/src/oss/langgraph/graph-api.mdx b/src/oss/langgraph/graph-api.mdx index a89cb54d6b..b1fb7e2df3 100644 --- a/src/oss/langgraph/graph-api.mdx +++ b/src/oss/langgraph/graph-api.mdx @@ -287,6 +287,13 @@ const State = z.object({ In this example, we've used [Zod 4 registries](https://zod.dev/metadata) to specify a reducer function for the second key (`bar`). Note that the first key remains unchanged. Let's assume the input to the graph is `{ foo: 1, bar: ["hi"] }`. Let's then assume the first `Node` returns `{ foo: 2 }`. This is treated as an update to the state. Notice that the `Node` does not need to return the whole `State` schema - just an update. After applying this update, the `State` would then be `{ foo: 2, bar: ["hi"] }`. If the second node returns `{ bar: ["bye"] }` then the `State` would then be `{ foo: 2, bar: ["hi", "bye"] }`. Notice here that the `bar` key is updated by adding the two arrays together. ::: +:::python +#### Overwrite + +In some cases, you may want to bypass a reducer and directly overwrite a state value. LangGraph provides the `Overwrite` type for this purpose. Learn how to use `Overwrite` [here](/oss/langgraph/use-graph-api#bypass-reducers-with-overwrite). + +::: + ### Working with Messages in Graph State #### Why use messages? diff --git a/src/oss/langgraph/use-graph-api.mdx b/src/oss/langgraph/use-graph-api.mdx index bd9a41252e..7dff1dd441 100644 --- a/src/oss/langgraph/use-graph-api.mdx +++ b/src/oss/langgraph/use-graph-api.mdx @@ -246,7 +246,7 @@ ai: Hello! Each key in the state can have its own independent [reducer](/oss/langgraph/graph-api#reducers) function, which controls how updates from nodes are applied. If no reducer function is explicitly specified then it is assumed that all updates to the key should override it. :::python -For `TypedDict` state schemas, we can define reducers by annotating the corresponding field of the state with a reducer function. +For `TypedDict` state schemas, we can define reducers by annotating tuvhe corresponding field of the state with a reducer function. In the earlier example, our node updated the `"messages"` key in the state by appending a message to it. Below, we add a reducer to this key, such that updates are automatically appended: @@ -446,6 +446,58 @@ const State = z.object({ ``` ::: +:::python +### Bypass reducers with `Overwrite` + +In some cases, you may want to bypass a reducer and directly overwrite a state value. LangGraph provides the `Overwrite` type for this purpose. When a node returns a value wrapped with `Overwrite`, the reducer is bypassed and the channel is set directly to that value. + +This is useful when you want to reset or replace accumulated state rather than merge it with existing values. + +```python +from langgraph.graph import StateGraph, START, END +from langgraph.types import Overwrite +from typing_extensions import Annotated, TypedDict +import operator + +class State(TypedDict): + messages: Annotated[list, operator.add] + +def add_message(state: State): + return {"messages": ["first message"]} + +def replace_messages(state: State): + # Bypass the reducer and replace the entire messages list + return {"messages": Overwrite(["replacement message"])} + +builder = StateGraph(State) +builder.add_node("add_message", add_message) +builder.add_node("replace_messages", replace_messages) +builder.add_edge(START, "add_message") +builder.add_edge("add_message", "replace_messages") +builder.add_edge("replace_messages", END) + +graph = builder.compile() + +result = graph.invoke({"messages": ["initial"]}) +print(result["messages"]) +``` + +``` +['replacement message'] +``` + +You can also use JSON format with the special key `"__overwrite__"`: + +```python +def replace_messages(state: State): + return {"messages": {"__overwrite__": ["replacement message"]}} +``` + + +When nodes execute in parallel, only one node can use `Overwrite` on the same state key in a given super-step. If multiple nodes attempt to overwrite the same key simultaneously, an `InvalidUpdateError` will be raised. + +::: + ### Define input and output schemas By default, `StateGraph` operates with a single schema, and all nodes are expected to communicate using that schema. However, it's also possible to define distinct input and output schemas for a graph. From 66e0f78887add1dec919f5315e045adb6fcd172f Mon Sep 17 00:00:00 2001 From: Caspar Broekhuizen Date: Thu, 30 Oct 2025 08:55:49 -0700 Subject: [PATCH 2/3] docs(langgraph): add reference doc links --- reference/python/docs/langgraph/types.md | 1 + src/oss/langgraph/graph-api.mdx | 2 +- src/oss/langgraph/use-graph-api.mdx | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/reference/python/docs/langgraph/types.md b/reference/python/docs/langgraph/types.md index 6da8ccac6a..cc8e3dd38d 100644 --- a/reference/python/docs/langgraph/types.md +++ b/reference/python/docs/langgraph/types.md @@ -11,4 +11,5 @@ - StateSnapshot - Send - Command + - Overwrite - interrupt diff --git a/src/oss/langgraph/graph-api.mdx b/src/oss/langgraph/graph-api.mdx index b1fb7e2df3..7051e5bae2 100644 --- a/src/oss/langgraph/graph-api.mdx +++ b/src/oss/langgraph/graph-api.mdx @@ -290,7 +290,7 @@ In this example, we've used [Zod 4 registries](https://zod.dev/metadata) to spec :::python #### Overwrite -In some cases, you may want to bypass a reducer and directly overwrite a state value. LangGraph provides the `Overwrite` type for this purpose. Learn how to use `Overwrite` [here](/oss/langgraph/use-graph-api#bypass-reducers-with-overwrite). +In some cases, you may want to bypass a reducer and directly overwrite a state value. LangGraph provides the [`Overwrite`](https://reference.langchain.com/python/langgraph/types/) type for this purpose. [Learn how to use `Overwrite` here](/oss/langgraph/use-graph-api#bypass-reducers-with-overwrite). ::: diff --git a/src/oss/langgraph/use-graph-api.mdx b/src/oss/langgraph/use-graph-api.mdx index 7dff1dd441..010edeafec 100644 --- a/src/oss/langgraph/use-graph-api.mdx +++ b/src/oss/langgraph/use-graph-api.mdx @@ -449,7 +449,7 @@ const State = z.object({ :::python ### Bypass reducers with `Overwrite` -In some cases, you may want to bypass a reducer and directly overwrite a state value. LangGraph provides the `Overwrite` type for this purpose. When a node returns a value wrapped with `Overwrite`, the reducer is bypassed and the channel is set directly to that value. +In some cases, you may want to bypass a reducer and directly overwrite a state value. LangGraph provides the [`Overwrite`](https://reference.langchain.com/python/langgraph/types/) type for this purpose. When a node returns a value wrapped with `Overwrite`, the reducer is bypassed and the channel is set directly to that value. This is useful when you want to reset or replace accumulated state rather than merge it with existing values. From 9e24b9004e9929a1c6cb27365b4fe77cda8a84ae Mon Sep 17 00:00:00 2001 From: Caspar Broekhuizen Date: Thu, 30 Oct 2025 09:13:49 -0700 Subject: [PATCH 3/3] docs(langgraph): fix spelling error --- src/oss/langgraph/use-graph-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oss/langgraph/use-graph-api.mdx b/src/oss/langgraph/use-graph-api.mdx index 010edeafec..f5d51a2553 100644 --- a/src/oss/langgraph/use-graph-api.mdx +++ b/src/oss/langgraph/use-graph-api.mdx @@ -246,7 +246,7 @@ ai: Hello! Each key in the state can have its own independent [reducer](/oss/langgraph/graph-api#reducers) function, which controls how updates from nodes are applied. If no reducer function is explicitly specified then it is assumed that all updates to the key should override it. :::python -For `TypedDict` state schemas, we can define reducers by annotating tuvhe corresponding field of the state with a reducer function. +For `TypedDict` state schemas, we can define reducers by annotating the corresponding field of the state with a reducer function. In the earlier example, our node updated the `"messages"` key in the state by appending a message to it. Below, we add a reducer to this key, such that updates are automatically appended: @@ -494,7 +494,7 @@ def replace_messages(state: State): ``` -When nodes execute in parallel, only one node can use `Overwrite` on the same state key in a given super-step. If multiple nodes attempt to overwrite the same key simultaneously, an `InvalidUpdateError` will be raised. +When nodes execute in parallel, only one node can use `Overwrite` on the same state key in a given super-step. If multiple nodes attempt to overwrite the same key in the same super-step, an `InvalidUpdateError` will be raised. :::