【LangGraph】Graph Definitions（图定义）：StateGraph、CompiledStateGraph 和 add

本文链接：https://blog.csdn.net/u013172930/article/details/148109419

LangGraph 图定义

LangGraph 是一个强大的框架，用于构建需要状态管理的复杂 LLM（大型语言模型）工作流。以下内容参考 LangGraph 官方文档中的 Graph Definitions 部分，涵盖了 StateGraph、CompiledStateGraph 和 add_messages 函数的详细描述。内容以清晰的结构呈现，适合开发者学习和理解 LangGraph。

1. 类 `StateGraph`

继承自： Graph

描述：
StateGraph 是一个图，其节点通过读写共享状态进行通信。每个节点的签名是 State -> Partial，即接收状态并返回部分更新。状态的每个键可以选择性地使用 reducer 函数来聚合同一键的多个更新值，reducer 函数的签名是 (Value, Value) -> Value。

1.1 参数

名称	类型	描述	默认值
`state_schema`	`Optional[type[Any]]`	定义状态的 schema 类。	`None`
`config_schema`	`Optional[type[Any]]`	定义配置的 schema 类，用于在 API 中暴露可配置参数。	`None`

1.2 示例

以下示例展示如何使用 StateGraph 创建一个简单的图，计算逻辑斯蒂映射序列：

from langchain_core.runnables import RunnableConfig
from typing_extensions import Annotated, TypedDict
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

# 定义 reducer 函数，用于合并状态值
def reducer(a: list, b: int | None) -> list:
    if b is not None:
        return a + [b]  # 如果 b 不为空，则追加到列表 a 中
    return a

# 定义状态类
class State(TypedDict):
    x: Annotated[list, reducer]  # x 是一个列表，使用 reducer 函数注解

# 定义配置 schema
class ConfigSchema(TypedDict):
    r: float  # 配置参数 r，类型为浮点数

# 创建 StateGraph 实例
graph = StateGraph(State, config_schema=ConfigSchema)

# 定义节点函数
def node(state: State, config: RunnableConfig) -> dict:
    r = config["configurable"].get("r", 1.0)  # 获取配置中的 r，默认为 1.0
    x = state["x"][-1]  # 获取状态中 x 的最后一个值
    next_value = x * r * (1 - x)  # 计算逻辑斯蒂映射的下一个值
    return {"x": next_value}  # 返回更新后的状态

# 添加节点并设置入口和出口
graph.add_node("A", node)  # 添加名为 "A" 的节点
graph.set_entry_point("A")  # 设置入口点为 "A"
graph.set_finish_point("A")  # 设置结束点为 "A"

# 编译图
compiled = graph.compile()

# 打印配置规格
print(compiled.config_specs)
# 输出: [ConfigurableFieldSpec(id='r', annotation=<class 'float'>, name=None, description=None, default=None, is_shared=False, dependencies=None)]

# 调用图并传入初始状态和配置
step1 = compiled.invoke({"x": [0.5]}, {"configurable": {"r": 3.0}})
# 输出: {'x': [0.5, 0.75]}

1.3 方法

名称	描述
`add_node`	向状态图中添加一个新节点。
`add_edge`	从起始节点（或起始节点列表）到结束节点添加一个有向边。
`add_conditional_edges`	从起始节点到任意数量的目标节点添加一个条件边。
`add_sequence`	添加一个按提供顺序执行的节点序列。
`compile`	将状态图编译为 `CompiledStateGraph` 对象。

1.3.1 方法 `add_node`

add_node(
    node: Union[str, RunnableLike],
    action: Optional[RunnableLike] = None,
    *,
    defer: bool = False,
    metadata: Optional[dict[str, Any]] = None,
    input: Optional[type[Any]] = None,
    retry: Optional[Union[RetryPolicy, Sequence[RetryPolicy]]] = None,
    cache_policy: Optional[CachePolicy] = None,
    destinations: Optional[Union[dict[str, str], tuple[str, ...]]] = None
) -> Self

描述：
向状态图中添加一个新节点。

参数：

名称	类型	描述	默认值
`node`	`Union[str, RunnableLike]`	这个节点将运行的函数或 `runnable`。如果提供的是字符串，它将被用作节点名称，`action` 将被用作函数或 `runnable`。	必填
`action`	`Optional[RunnableLike]`	与节点关联的动作。如果 `node` 是字符串，则用作节点函数或 `runnable`。	`None`
`defer`	`bool`	是否推迟节点的执行，直到运行即将结束。	`False`
`metadata`	`Optional[dict[str, Any]]`	与节点关联的元数据。	`None`
`input`	`Optional[type[Any]]`	节点的输入 schema，默认使用图的输入 schema。	`None`
`retry`	`Optional[Union[RetryPolicy, Sequence[RetryPolicy]]]`	节点的重试策略。如果提供的是序列，将应用第一个匹配的策略。	`None`
`cache_policy`	`Optional[CachePolicy]`	节点的缓存策略。	`None`
`destinations`	`Optional[Union[dict[str, str], tuple[str, ...]]]`	指示节点可以路由到的目标，用于无边图的渲染，不影响执行。	`None`

引发异常：

ValueError：如果键已经被用作状态键。

示例：

from langgraph.graph import START, StateGraph

# 定义节点函数
def my_node(state, config):
    return {"x": state["x"] + 1}  # 将状态中的 x 增加 1

# 创建并配置图
builder = StateGraph(dict)
builder.add_node(my_node)  # 节点名称将自动设为 "my_node"
builder.add_edge(START, "my_node")  # 从 START 到 my_node 添加边
graph = builder.compile()
graph.invoke({"x": 1})
# 输出: {'x': 2}

# 自定义节点名称
builder = StateGraph(dict)
builder.add_node("my_fair_node", my_node)  # 指定节点名称为 "my_fair_node"
builder.add_edge(START, "my_fair_node")
graph = builder.compile()
graph.invoke({"x": 1})
# 输出: {'x': 2}

返回值：

名称	类型	描述
`Self`	`Self`	状态图的实例，支持方法链式调用。

1.3.2 方法 `add_edge`

add_edge(
    start_key: Union[str, list[str]],
    end_key: str
) -> Self

描述：
从起始节点（或起始节点列表）到结束节点添加一个有向边。当提供单个起始节点时，图将等待该节点完成后再执行结束节点；当提供多个起始节点时，图将等待所有起始节点完成后再执行结束节点。

参数：

名称	类型	描述	默认值
`start_key`	`Union[str, list[str]]`	边的起始节点（或节点列表）的键。	必填
`end_key`	`str`	边的结束节点的键。	必填

引发异常：

类型	描述
`ValueError`	如果 `start_key` 是 “END”，或 `start_key` 或 `end_key` 不在图中。

返回值：

名称	类型	描述
`Self`	`Self`	状态图的实例，支持方法链式调用。

1.3.3 方法 `add_conditional_edges`

add_conditional_edges(
    source: str,
    path: Union[
        Callable[..., Union[Hashable, list[Hashable]]],
        Callable[..., Awaitable[Union[Hashable, list[Hashable]]]],
        Runnable[Any, Union[Hashable, list[Hashable]]]
    ],
    path_map: Optional[Union[dict[Hashable, str], list[str]]] = None,
    then: Optional[str] = None,
) -> Self

描述：
从起始节点到任意数量的目标节点添加一个条件边。

参数：

名称	类型	描述	默认值
`source`	`str`	起始节点，条件边将在退出此节点时运行。	必填
`path`	`Union[Callable[..., Union[Hashable, list[Hashable]]], ...]`	决定下一个节点或节点的 callable。如果返回 “END”，图将停止执行。	必填
`path_map`	`Optional[Union[dict[Hashable, str], list[str]]]`	路径到节点名称的映射。如果省略，`path` 返回的路径应为节点名称。	`None`
`then`	`Optional[str]`	在 `path` 选择的节点之后执行的节点名称。	`None`

返回值：

名称	类型	描述
`Self`	`Self`	图的实例，支持方法链式调用。

注意：
如果 path 函数的返回值没有类型提示（例如 -> Literal["foo", "__end__"]）或 path_map，图的可视化将假设边可以过渡到图中的任何节点。

1.3.4 方法 `add_sequence`

add_sequence(
    nodes: Sequence[Union[RunnableLike, tuple[str, RunnableLike]]],
) -> Self

描述：
添加一个按提供顺序执行的节点序列。

参数：

名称	类型	描述	默认值
`nodes`	`Sequence[Union[RunnableLike, tuple[str, RunnableLike]]]`	`RunnableLike` 对象或 `(name, RunnableLike)` 元组的序列。每个节点按顺序执行。	必填

引发异常：

类型	描述
`ValueError`	如果序列为空。
`ValueError`	如果序列包含重复的节点名称。

返回值：

名称	类型	描述
`Self`	`Self`	状态图的实例，支持方法链式调用。

1.3.5 方法 `compile`

compile(
    checkpointer: Checkpointer = None,
    *,
    cache: Optional[BaseCache] = None,
    store: Optional[BaseStore] = None,
    interrupt_before: Optional[Union[All, list[str]]] = None,
    interrupt_after: Optional[Union[All, list[str]]] = None,
    debug: bool = False,
    name: Optional[str] = None
) -> CompiledStateGraph

描述：
将状态图编译为 CompiledStateGraph 对象。编译后的图实现了 Runnable 接口，可以被调用、流式处理、批处理和异步运行。

参数：

名称	类型	描述	默认值
`checkpointer`	`Checkpointer`	检查点保存对象或标志，用于暂停、恢复和重放图。如果为 `None`，可能继承父图的检查点；如果为 `False`，不使用检查点。	`None`
`cache`	`Optional[BaseCache]`	缓存对象。	`None`
`store`	`Optional[BaseStore]`	存储对象。	`None`
`interrupt_before`	`Optional[Union[All, list[str]]]`	在之前中断的节点名称列表。	`None`
`interrupt_after`	`Optional[Union[All, list[str]]]`	在之后中断的节点名称列表。	`None`
`debug`	`bool`	是否启用调试模式。	`False`
`name`	`Optional[str]`	编译图的名称。	`None`

返回值：

名称	类型	描述
`CompiledStateGraph`	`CompiledStateGraph`	编译后的状态图。

2. 类 `CompiledStateGraph`

继承自： CompiledGraph

描述：
CompiledStateGraph 是编译后的状态图，实现了 Runnable 接口，支持同步和异步执行、流式处理、状态管理和检查点功能。

2.1 方法

名称	描述
`stream`	为单个输入流式传输图的步骤。
`astream`	异步为单个输入流式传输图的步骤。
`invoke`	使用单个输入和配置运行图。
`ainvoke`	异步在单个输入上调用图。
`get_state`	获取图的当前状态。
`aget_state`	异步获取图的当前状态。
`get_state_history`	获取图的状态历史。
`aget_state_history`	异步获取图的状态历史。
`update_state`	使用给定值更新图的状态，如同来自指定节点。
`aupdate_state`	异步使用给定值更新图的状态，如同来自指定节点。
`bulk_update_state`	批量应用更新到图状态，需要设置检查点。
`abulk_update_state`	异步批量应用更新到图状态，需要设置检查点。
`get_graph`	返回计算图的可视化表示。
`aget_graph`	异步返回计算图的可视化表示。
`get_subgraphs`	获取图的子图。
`aget_subgraphs`	异步获取图的子图。
`with_config`	创建 `Pregel` 对象的副本并更新配置。

2.1.1 方法 `stream`

stream(
    input: dict[str, Any] | Any,
    config: Optional[RunnableConfig] = None,
    *,
    stream_mode: Optional[Union[StreamMode, List[StreamMode]]] = None,
    output_keys: Optional[Union[str, Sequence[str]]] = None,
    interrupt_before: Optional[Union[All, Sequence[str]]] = None,
    interrupt_after: Optional[Union[All, Sequence[str]]] = None,
    checkpoint_during: Optional[bool] = None,
    debug: Optional[bool] = None,
    subgraphs: bool = False
) -> Iterator[Union[dict[str, Any], Any]]

描述：
为单个输入流式传输图的步骤。每个步骤的输出可以以不同模式（stream_mode）发出，例如状态值、节点更新或调试信息。

参数：

名称	类型	描述	默认值
`input`	`dict[str, Any]	Any`	图的输入。
`config`	`Optional[RunnableConfig]`	用于运行的配置。	`None`
`stream_mode`	`Optional[Union[StreamMode, List[StreamMode]]]`	流式输出模式，详见下文。	`None`
`output_keys`	`Optional[Union[str, Sequence[str]]]`	要流式的键，默认包括所有非上下文通道。	`None`
`interrupt_before`	`Optional[Union[All, Sequence[str]]]`	在之前中断的节点，默认包括图中所有节点。	`None`
`interrupt_after`	`Optional[Union[All, Sequence[str]]]`	在之后中断的节点，默认包括图中所有节点。	`None`
`checkpoint_during`	`Optional[bool]`	是否在中间步骤保存检查点，默认 `True`。	`None`
`debug`	`Optional[bool]`	在执行期间是否打印调试信息，默认 `False`。	`None`
`subgraphs`	`bool`	是否流式传输子图内部的事件，默认 `False`。如果为 `True`，事件将以 `(namespace, data)` 或 `(namespace, mode, data)` 元组形式发出，其中 `namespace` 是子图节点的路径，例如 `("parent_node:<task_id>", "child_node:<task_id>")`。	`False`

stream_mode 可选项：

"values": 在每个步骤后发出状态中的所有值，包括中断。在函数式 API 中，值在工作流结束时发出一次。
"updates": 在每个步骤后仅发出节点或任务名称及其返回的更新。如果同一步骤中有多个更新（例如运行多个节点），则分别发出这些更新。
"custom": 使用 StreamWriter 从节点或任务内部发出自定义数据。
"messages": 逐个 token 发出 LLM 消息，附带任何 LLM 调用的元数据，格式为 (LLM token, metadata) 的二元组。
"debug": 为每个步骤发出包含尽可能多信息的调试事件。
可传递列表以同时流式传输多种模式，输出为 (mode, data) 元组。

示例：

from langgraph.graph import StateGraph
from typing_extensions import TypedDict

class State(TypedDict):
    value: int

graph = StateGraph(State)

def node(state: State) -> dict:
    return {"value": state["value"] + 1}

graph.add_node("A", node)
graph.add_edge("A", "A")
graph.set_entry_point("A")
compiled = graph.compile()

# 流式传输值模式
for output in compiled.stream({"value": 0}, stream_mode="values"):
    print(output)
# 输出: {'value': 1}, {'value': 2}, ...

# 流式传输更新模式
for output in compiled.stream({"value": 0}, stream_mode="updates"):
    print(output)
# 输出: {"A": {"value": 1}}, {"A": {"value": 2}}, ...

返回值：

类型	描述
`Iterator[Union[dict[str, Any], Any]]`	图中每个步骤的输出，形状取决于 `stream_mode`。

2.1.2 方法 `astream`

async astream(
    input: dict[str, Any] | Any,
    config: Optional[RunnableConfig] = None,
    *,
    stream_mode: Optional[Union[StreamMode, List[StreamMode]]] = None,
    output_keys: Optional[Union[str, Sequence[str]]] = None,
    interrupt_before: Optional[Union[All, Sequence[str]]] = None,
    interrupt_after: Optional[Union[All, Sequence[str]]] = None,
    checkpoint_during: Optional[bool] = None,
    debug: Optional[bool] = None,
    subgraphs: bool = False
) -> AsyncIterator[Union[dict[str, Any], Any]]

描述：
异步为单个输入流式传输图的步骤。参数与 stream 方法相同。

示例：

import asyncio
from langgraph.graph import StateGraph
from typing_extensions import TypedDict

class State(TypedDict):
    value: int

graph = StateGraph(State)

def node(state: State) -> dict:
    return {"value": state["value"] + 1}

graph.add_node("A", node)
graph.add_edge("A", "A")
graph.set_entry_point("A")
compiled = graph.compile()

async def main():
    async for output in compiled.astream({"value": 0}, stream_mode="values"):
        print(output)

asyncio.run(main())
# 输出: {'value': 1}, {'value': 2}, ...

返回值：

类型	描述
`AsyncIterator[Union[dict[str, Any], Any]]`	图中每个步骤的输出，形状取决于 `stream_mode`。

2.1.3 方法 `invoke`

invoke(
    input: dict[str, Any] | Any,
    config: Optional[RunnableConfig] = None,
    *,
    stream_mode: StreamMode = "values",
    output_keys: Optional[Union[str, Sequence[str]]] = None,
    interrupt_before: Optional[Union[All, Sequence[str]]] = None,
    interrupt_after: Optional[Union[All, Sequence[str]]] = None,
    checkpoint_during: Optional[bool] = None,
    debug: Optional[bool] = None,
    **kwargs: Any
) -> Union[dict[str, Any], Any]

描述：
使用单个输入和配置运行图。

参数：

名称	类型	描述	默认值
`input`	`dict[str, Any]	Any`	图的输入数据。
`config`	`Optional[RunnableConfig]`	图运行的配置。	`None`
`stream_mode`	`StreamMode`	图运行的流模式，默认 `"values"`。	`"values"`
`output_keys`	`Optional[Union[str, Sequence[str]]]`	从图运行中检索的输出键。	`None`
`interrupt_before`	`Optional[Union[All, Sequence[str]]]`	在之前中断图运行的节点。	`None`
`interrupt_after`	`Optional[Union[All, Sequence[str]]]`	在之后中断图运行的节点。	`None`
`debug`	`Optional[bool]`	启用图运行的调试模式。	`None`
`**kwargs`	`Any`	传递给图运行的额外关键字参数。	`{}`

返回值：

类型	描述
`Union[dict[str, Any], Any]`	如果 `stream_mode` 为 `"values"`，返回最新输出。如果 `stream_mode` 不是 `"values"`，返回输出块列表。

2.1.4 方法 `ainvoke`

async ainvoke(
    input: dict[str, Any] | Any,
    config: Optional[RunnableConfig] = None,
    *,
    stream_mode: StreamMode = "values",
    output_keys: Optional[Union[str, Sequence[str]]]] = None,
    interrupt_before: Optional[Union[All, Sequence[str]]] = None,
    interrupt_after: Optional[Union[All, Sequence[str]]] = None,
    checkpoint_during: Optional[bool] = None,
    debug: Optional[bool] = None,
    **kwargs: Any
) -> Union[dict[str, Any], Any]

描述：
异步在单个输入上调用图。参数与 invoke 方法相同。

返回值：

类型	描述
`Union[dict[str, Any], Any]`	如果 `stream_mode` 为 `"values"`，返回最新值。如果 `stream_mode` 为 `"chunks"`，返回块列表。

2.1.5 方法 `get_state`

get_state(
    config: RunnableConfig,
    *,
    subgraphs: bool = False
) -> StateSnapshot

描述：
获取图的当前状态。

2.1.6 方法 `aget_state`

async aget_state(
    config: RunnableConfig,
    *,
    subgraphs: bool = False
) -> StateSnapshot

描述：
异步获取图的当前状态。

2.1.7 方法 `get_state_history`

get_state_history(
    config: RunnableConfig,
    *,
    filter: Optional[dict[str, Any]] = None,
    before: Optional[RunnableConfig] = None,
    limit: Optional[int] = None
) -> Iterator[StateSnapshot]

描述：
获取图的状态历史。

2.1.8 方法 `aget_state_history`

async aget_state_history(
    config: RunnableConfig,
    *,
    filter: Optional[dict[str, Any]] = None,
    before: Optional[RunnableConfig] = None,
    limit: Optional[int] = None
) -> AsyncIterator[StateSnapshot]

描述：
异步获取图的状态历史。

2.1.9 方法 `update_state`

update_state(
    config: RunnableConfig,
    values: Union[dict[str, Any], Any, None],
    as_node: Optional[str] = None,
) -> RunnableConfig

描述：
使用给定值更新图的状态，如同来自 as_node 节点。如果未提供 as_node，将设置为最后一个更新状态的节点（若不模糊）。

2.1.10 方法 `aupdate_state`

async aupdate_state(
    config: RunnableConfig,
    values: Union[dict[str, Any], Any],
    as_node: Optional[str] = None,
) -> RunnableConfig

描述：
异步使用给定值更新图的状态，如同来自 as_node 节点。如果未提供 as_node，将设置为最后一个更新状态的节点（若不模糊）。

2.1.11 方法 `bulk_update_state`

bulk_update_state(
    config: RunnableConfig,
    supersteps: Sequence[Sequence[StateUpdate]],
) -> RunnableConfig

描述：
批量应用更新到图状态，需要设置 checkpointer。

参数：

名称	类型	描述	默认值
`config`	`RunnableConfig`	要应用更新的配置。	必填
`supersteps`	`Sequence[Sequence[StateUpdate]]`	超级步骤的列表，每个超级步骤包括按顺序应用于图状态的更新列表。每个更新是 `(values, as_node)` 形式的元组。	必填

引发异常：

类型	描述
`ValueError`	如果未设置 `checkpointer` 或未提供更新。
`InvalidUpdateError`	如果提供了无效的更新。

返回值：

名称	类型	描述
`RunnableConfig`	`RunnableConfig`	更新后的配置。

2.1.12 方法 `abulk_update_state`

async abulk_update_state(
    config: RunnableConfig,
    supersteps: Sequence[Sequence[StateUpdate]],
) -> RunnableConfig

描述：
异步批量应用更新到图状态，需要设置 checkpointer。参数、异常和返回值与 bulk_update_state 相同。

2.1.13 方法 `get_graph`

get_graph(
    config: Optional[RunnableConfig] = None,
    *,
    xray: Union[int, bool] = False
) -> Graph

描述：
返回计算图的可视化表示。

2.1.14 方法 `aget_graph`

async aget_graph(
    config: Optional[RunnableConfig] = None,
    *,
    xray: Union[int, bool] = False
) -> Graph

描述：
异步返回计算图的可视化表示。

2.1.15 方法 `get_subgraphs`

get_subgraphs(
    *,
    namespace: Optional[str] = None,
    recurse: bool = False
) -> Iterator[tuple[str, PregelProtocol]]

描述：
获取图的子图。

参数：

名称	类型	描述	默认值
`namespace`	`Optional[str]`	用于过滤子图的命名空间。	`None`
`recurse`	`bool`	是否递归到子图中，默认仅返回直接子图。	`False`

返回值：

类型	描述
`Iterator[tuple[str, PregelProtocol]]`	`(namespace, subgraph)` 对的迭代器。

2.1.16 方法 `aget_subgraphs`

async aget_subgraphs(
    *,
    namespace: Optional[str] = None,
    recurse: bool = False
) -> AsyncIterator[tuple[str, PregelProtocol]]

描述：
异步获取图的子图。参数和返回值与 get_subgraphs 相同。

2.1.17 方法 `with_config`

with_config(
    config: Optional[RunnableConfig] = None,
    **kwargs: Any
) -> Self

描述：
创建 Pregel 对象的副本并更新配置。

3. 类 `Graph`

描述：
Graph 是 StateGraph 的基类，提供基本的图操作方法。

3.1 方法

名称	描述
`add_node`	向图中添加一个新节点。
`add_edge`	从起始节点到结束节点添加一个有向边。
`add_conditional_edges`	从起始节点到任意数量的目标节点添加一个条件边。
`compile`	将图编译为 `CompiledGraph` 对象。

3.1.1 方法 `add_node`

add_node(
    node: Union[str, RunnableLike],
    action: Optional[RunnableLike] = None,
    *,
    metadata: Optional[dict[str, Any]] = None
) -> Self

描述：
向图中添加一个新节点。

参数：

名称	类型	描述	默认值
`node`	`Union[str, RunnableLike]`	这个节点将运行的函数或 `runnable`。如果提供的是字符串，它将被用作节点名称，`action` 将被用作函数或 `runnable`。	必填
`action`	`Optional[RunnableLike]`	与节点关联的动作。如果 `node` 是字符串，则用作节点函数或 `runnable`。	`None`
`metadata`	`Optional[dict[str, Any]]`	与节点关联的元数据。	`None`

3.1.2 方法 `add_edge`

add_edge(start_key: str, end_key: str) -> Self

描述：
从起始节点到结束节点添加一个有向边。

参数：

名称	类型	描述	默认值
`start_key`	`str`	边的起始节点的键。	必填
`end_key`	`str`	边的结束节点的键。	必填

3.1.3 方法 `add_conditional_edges`

add_conditional_edges(
    source: str,
    path: Union[
        Callable[..., Union[Hashable, list[Hashable]]],
        Callable[..., Awaitable[Union[Hashable, list[Hashable]]]],
        Runnable[Any, Union[Hashable, list[Hashable]]]
    ],
    path_map: Optional[Union[dict[Hashable, str], list[str]]] = None,
    then: Optional[str] = None,
) -> Self

描述：
从起始节点到任意数量的目标节点添加一个条件边。参数和返回值与 StateGraph 的 add_conditional_edges 方法相同。

3.1.4 方法 `compile`

compile(
    checkpointer: Optional[Checkpointer] = None,
    interrupt_before: Optional[Union[All, list[str]]] = None,
    interrupt_after: Optional[Union[All, list[str]]] = None,
    debug: bool = False,
    name: Optional[str] = None,
    *,
    cache: Optional[BaseCache] = None,
    store: Optional[BaseStore] = None
) -> CompiledGraph

描述：
将图编译为 CompiledGraph 对象。参数和返回值与 StateGraph 的 compile 方法类似。

4. 类 `CompiledGraph`

继承自： Pregel

描述：
CompiledGraph 是编译后的图，提供了与 CompiledStateGraph 类似的方法，支持流式处理、调用和状态管理。

4.1 方法

方法与 CompiledStateGraph 相同，详见第 2.1 节。

5. 函数 `add_messages`

add_messages(
    left: Messages,
    right: Messages,
    *,
    format: Optional[Literal["langchain-openai"]] = None
) -> Messages

描述：
合并两个消息列表，按 ID 更新现有消息。默认情况下，确保状态是“仅追加”的，除非新消息的 ID 与现有消息相同。

参数：

名称	类型	描述	默认值
`left`	`Messages`	基础消息列表。	必填
`right`	`Messages`	要合并到基础列表中的消息列表（或单个消息）。	必填
`format`	`Optional[Literal["langchain-openai"]]`	返回消息的格式，`None` 表示按原样返回，`"langchain-openai"` 表示格式化为 OpenAI 消息格式（内容可以是字符串、文本块或图像 URL 块，工具响应作为单独的 `ToolMessages` 返回）。	`None`

要求：
必须安装 langchain-core>=0.3.11 才能使用此功能。

返回值：

类型	描述
`Messages`	带有 `right` 中消息合并到 `left` 中的新消息列表。
`Messages`	如果 `right` 中的消息与 `left` 中的消息具有相同 ID，则替换 `left` 中的消息。

示例：

5.1 基本用法

from langchain_core.messages import AIMessage, HumanMessage

msgs1 = [HumanMessage(content="Hello", id="1")]
msgs2 = [AIMessage(content="Hi there!", id="2")]
add_messages(msgs1, msgs2)
# 输出: [HumanMessage(content='Hello', id='1'), AIMessage(content='Hi there!', id='2')]

5.2 覆盖现有消息

msgs1 = [HumanMessage(content="Hello", id="1")]
msgs2 = [HumanMessage(content="Hello again", id="1")]
add_messages(msgs1, msgs2)
# 输出: [HumanMessage(content='Hello again', id='1')]

5.3 在 `StateGraph` 中使用

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph

class State(TypedDict):
    messages: Annotated[list, add_messages]  # 使用 add_messages 注解 messages 字段

builder = StateGraph(State)
builder.add_node("chatbot", lambda state: {"messages": [("assistant", "Hello")]})
builder.set_entry_point("chatbot")
builder.set_finish_point("chatbot")
graph = builder.compile()
graph.invoke({})
# 输出: {'messages': [AIMessage(content='Hello', id=...)]}

5.4 使用 OpenAI 消息格式

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages(format='langchain-openai')]  # 指定 OpenAI 格式

def chatbot_node(state: State) -> list:
    return {"messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Here's an image:",
                    "cache_control": {"type": "ephemeral"},
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "1234",
                    },
                },
            ]
        },
    ]}

builder = StateGraph(State)
builder.add_node("chatbot", chatbot_node)
builder.set_entry_point("chatbot")
builder.set_finish_point("chatbot")
graph = builder.compile()
graph.invoke({"messages": []})
# 输出:
# {
#     'messages': [
#         HumanMessage(
#             content=[
#                 {"type": "text", "text": "Here's an image:"},
#                 {
#                     "type": "image_url",
#                     "image_url": {"url": "data:image/jpeg;base64,1234"},
#                 },
#             ],
#         ),
#     ]
# }

6. 总结

StateGraph：用于定义节点、边和共享状态的图，编译后生成 CompiledStateGraph 以供执行。
CompiledStateGraph：支持灵活的执行方式（同步/异步、流式/批量）和状态管理，stream 方法提供了多种输出模式，适合实时处理和调试。
add_messages：简化对话类工作流中的消息管理，支持 OpenAI 消息格式，适用于智能代理和多轮对话场景。

LangGraph 提供了一个强大且灵活的框架，适合构建复杂的 LLM 工作流。开发者可以从简单的图开始，逐步探索条件边、异步执行和检查点等高级功能。

参考资料