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 a89cb54d6b..7051e5bae2 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`](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). + +::: + ### 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..f5d51a2553 100644 --- a/src/oss/langgraph/use-graph-api.mdx +++ b/src/oss/langgraph/use-graph-api.mdx @@ -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`](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. + +```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 in the same super-step, 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.