8、LangGraph

最新推荐文章于 2025-07-11 11:32:05 发布

原创

最新推荐文章于 2025-07-11 11:32:05 发布 · 674 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#langchain #人工智能 #AI编程 #langgraph

LangGraph 核心组件: Graphs, State, Nodes, Edges

LangGraph

🦜🕸️LangGraph ⚡ 以图的方式构建语言代理 ⚡

官方文档地址：https://langchain-ai.github.io/langgraph/

LangGraph 是一个用于构建具有 LLMs 的有状态、多角色应用程序的库，用于创建代理和多代理工作流。与其他 LLM 框架相比，它提供了以下核心优势：循环、可控性和持久性。

LangGraph 允许您定义涉及循环的流程，这对于大多数代理架构至关重要。作为一种非常底层的框架，它提供了对应用程序的流程和状态的精细控制，这对创建可靠的代理至关重要。此外，LangGraph 包含内置的持久性，可以实现高级的“人机交互”和内存功能。

LangGraph 的灵感来自 Pregel 和 Apache Beam。公共接口借鉴了 NetworkX。

Apache Beam 是一个开源的统一编程模型，用于构建复杂的数据处理管道。它支持批处理和流处理，能够跨多个大数据执行引擎无缝运行。本文将详细介绍 Apache Beam 的原理、基础使用、高级使用

NetworkX在02年5月产生，是用python语言编写的软件包，便于用户对复杂网络进行创建、操作和学习。利用networkx可以以标准化和非标准化的数据格式存储网络、生成多种随机网络和经典网络、分析网络结构、建立网络模型、设计新的网络算法、进行网络绘制等。

LangGraph 由 LangChain Inc（LangChain 的创建者）构建，但可以在没有 LangChain 的情况下使用。

主要功能

循环和分支：在您的应用程序中实现循环和条件语句。
持久性：在图中的每个步骤之后自动保存状态。在任何时候暂停和恢复图执行以支持错误恢复、“人机交互”工作流、时间旅行等等。
“人机交互”：中断图执行以批准或编辑代理计划的下一个动作。
流支持：在每个节点产生输出时流式传输输出（包括令牌流式传输）。
与 LangChain 集成：LangGraph 与 LangChain 和 LangSmith 无缝集成（但不需要它们）。

安装

pip install -U langgraph

示例

LangGraph 的一个核心概念是状态。每次图执行都会创建一个状态，该状态在图中的节点执行时传递，每个节点在执行后使用其返回值更新此内部状态。图更新其内部状态的方式由所选图类型或自定义函数定义。

让我们看一个可以使用搜索工具的简单代理示例。

pip install langchain-openai

setx OPENAI_BASE_URL "https://api.openai.com/v1"
setx OPENAI_API_KEY "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

可以选择设置 LangSmith 以实现最佳的可观察性。

setx LANGSMITH_TRACING "true"
setx LANGSMITH_API_KEY "xxxxxxxxxxxxxxxx"

#示例：langgraph_hello.py
from typing import Literal
from langchain_core.messages import HumanMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
# pip install langgraph
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, StateGraph, MessagesState
from langgraph.prebuilt import ToolNode

# 定义工具函数，用于代理调用外部工具
@tool
def search(query: str):
    """模拟一个搜索工具"""
    if "上海" in query.lower() or "Shanghai" in query.lower():
        return "现在30度，有雾."
    return "现在是35度，阳光明媚。"


# 将工具函数放入工具列表
tools = [search]

# 创建工具节点
tool_node = ToolNode(tools)

# 1.初始化模型和工具，定义并绑定工具到模型
model = ChatOpenAI(model="gpt-4o", temperature=0).bind_tools(tools)

# 定义函数，决定是否继续执行
def should_continue(state: MessagesState) -> Literal["tools", END]:
    messages = state['messages']
    last_message = messages[-1]
    # 如果LLM调用了工具，则转到“tools”节点
    if last_message.tool_calls:
        return "tools"
    # 否则，停止（回复用户）
    return END


# 定义调用模型的函数
def call_model(state: MessagesState):
    messages = state['messages']
    response = model.invoke(messages)
    # 返回列表，因为这将被添加到现有列表中
    return {
   
   "messages": [response]}

# 2.用状态初始化图，定义一个新的状态图
workflow = StateGraph(MessagesState)
# 3.定义图节点，定义我们将循环的两个节点
workflow.add_node("agent", call_model)
workflow.add_node("tools", tool_node)

# 4.定义入口点和图边
# 设置入口点为“agent”
# 这意味着这是第一个被调用的节点
workflow.set_entry_point("agent")

# 添加条件边
workflow.add_conditional_edges(
    # 首先，定义起始节点。我们使用`agent`。
    # 这意味着这些边是在调用`agent`节点后采取的。
    "agent",
    # 接下来，传递决定下一个调用节点的函数。
    should_continue,
)

# 添加从`tools`到`agent`的普通边。
# 这意味着在调用`tools`后，接下来调用`agent`节点。
workflow.add_edge("tools", 'agent')

# 初始化内存以在图运行之间持久化状态
checkpointer = MemorySaver()

# 5.编译图
# 这将其编译成一个LangChain可运行对象，
# 这意味着你可以像使用其他可运行对象一样使用它。
# 注意，我们（可选地）在编译图时传递内存
app = workflow.compile(checkpointer=checkpointer)

# 6.执行图，使用可运行对象
final_state = app.invoke(
    {
   
   "messages": [HumanMessage(content="上海的天气怎么样?")]},
    config={
   
   "configurable": {
   
   "thread_id": 42}}
)
# 从 final_state 中获取最后一条消息的内容
result = final_state["messages"][-1].content
print(result)
final_state = app.invoke(
    {
   
   "messages": [HumanMessage(content="我问的那个城市?")]},
    config={
   
   "configurable": {
   
   "thread_id": 42}}
)
result = final_state["messages"][-1].content
print(result)

上海现在的天气是30度，有雾。

现在，当我们传递相同的 "thread_id" 时，对话上下文将通过保存的状态（即存储的消息列表）保留下来。

final_state = app.invoke(
    {
   
   "messages": [HumanMessage(content="我问的那个城市?")]},
    config={
   
   "configurable": {
   
   "thread_id": 42}}
)
result = final_state["messages"][-1].content
print(result)

你问的是上海的天气。上海现在的天气是30度，有雾。

逐步分解

初始化模型和工具

- 我们使用 `ChatOpenAI` 作为我们的 LLM。**注意：**我们需要确保模型知道可以使用哪些工具。我们可以通过将 LangChain 工具转换为 OpenAI 工具调用格式来完成此操作，方法是使用 `.bind_tools()` 方法。
- 我们定义要使用的工具——在本例中是搜索工具。创建自己的工具非常容易——请参阅此处的文档了解如何操作 [此处](http://python.langchain.ac.cn/docs/modules/agents/tools/custom_tools)。

用状态初始化图

- 我们通过传递状态模式（在本例中为 `MessagesState`）来初始化图（`StateGraph`）。
- `MessagesState` 是一个预构建的状态模式，它具有一个属性，一个 LangChain `Message` 对象列表，以及将每个节点的更新合并到状态中的逻辑。

定义图节点

我们需要两个主要节点

- `agent` 节点：负责决定采取什么（如果有）行动。
- 调用工具的 `tools` 节点：如果代理决定采取行动，此节点将执行该行动。

定义入口点和图边

首先，我们需要设置图执行的入口点——agent 节点。

然后，我们定义一个普通边和一个条件边。条件边意味着目的地取决于图状态（MessageState）的内容。在本例中，目的地在代理（LLM）决定之前是未知的。

- 条件边：调用代理后，我们应该要么
    * a. 如果代理说要采取行动，则运行工具
    * b. 如果代理没有要求运行工具，则完成（回复用户）。
- 普通边：调用工具后，图应该始终返回到代理以决定下一步操作。

编译图

- 当我们编译图时，我们将其转换为 LangChain Runnable，这会自动启用使用您的输入调用 `.invoke()`、`.stream()` 和 `.batch()`。
- 我们还可以选择传递检查点对象以在图运行之间持久化状态，并启用内存、“人机交互”工作流、时间旅行等等。在本例中，我们使用 `MemorySaver`——一个简单的内存中检查点。

执行图

1. LangGraph 将输入消息添加到内部状态，然后将状态传递给入口点节点 `"agent"`。
2. `"agent"` 节点执行，调用聊天模型。
3. 聊天模型返回 `AIMessage`。LangGraph 将其添加到状态中。
4. 图循环以下步骤，直到 `AIMessage` 上不再有 `tool_calls`。
    * 如果 `AIMessage` 具有 `tool_calls`，则 `"tools"` 节点执行。
    * `"agent"` 节点再次执行并返回 `AIMessage`。
5. 执行进度到特殊的 `END` 值，并输出最终状态。因此，我们得到所有聊天消息的列表作为输出。

Graph(图)

LangGraph 的核心是将代理工作流建模为图。你可以使用三个关键组件来定义代理的行为

状态：一个共享的数据结构，表示应用程序的当前快照。它可以是任何 Python 类型，但通常是 TypedDict 或 Pydantic BaseModel。
节点：编码代理逻辑的 Python 函数。它们接收当前 状态 作为输入，执行一些计算或副作用，并返回一个更新的 状态。
边：Python 函数，根据当前 状态 确定要执行的下一个 节点。它们可以是条件分支或固定转换。

通过组合 节点 和 边，你可以创建复杂的循环工作流，随着时间的推移发展 状态。但是，真正的力量来自于 LangGraph 如何管理 状态。需要强调的是：节点 和 边 不过是 Python 函数——它们可以包含 LLM 或简单的 Python 代码。

简而言之：节点完成工作。边指示下一步要做什么。

LangGraph 的底层图算法使用消息传递来定义一个通用程序。当一个节点完成其操作时，它会沿着一条或多条边向其他节点发送消息。这些接收节点然后执行其函数，将结果消息传递给下一组节点，并且该过程继续进行。受到 Google 的 Pregel 系统的启发，该程序以离散的“超级步骤”进行。

超级步骤可以被认为是图节点上的单个迭代。并行运行的节点属于同一个超级步骤，而顺序运行的节点则属于不同的超级步骤。在图执行开始时，所有节点都处于 inactive 状态。当节点在任何传入边（或“通道”）上收到新消息（状态）时，它将变为 active 状态。然后，活动节点运行其函数并响应更新。在每个超级步骤结束时，没有传入消息的节点通过将其标记为 inactive 来投票 halt。当所有节点都处于 inactive 状态且没有消息在传输中时，图执行终止。

StateGraph

StateGraph 类是使用的主要图类。它由用户定义的 状态 对象参数化。

from langgraph.graph import StateGraph
from typing_extensions import TypedDict
class MyState(TypedDict)
    ...
graph = StateGraph(MyState)

基类：图

一个图，其节点通过读取和写入共享状态进行通信。每个节点的签名是 State -> Partial.

每个状态键可以选择性地使用一个 reducer 函数进行注释，该函数将用于聚合从多个节点接收到的该键的值。reducer 函数的签名是 (Value, Value) -> Value。

参数

**state_schema** ([类型](http://docs.pythonlang.cn/3/library/typing.html#typing.Type)[[任何](http://docs.pythonlang.cn/3/library/typing.html#typing.Any)], 默认值：None ) –

定义状态的模式类。

**config_schema** ([可选](http://docs.pythonlang.cn/3/library/typing.html#typing.Optional)[[类型](http://docs.pythonlang.cn/3/library/typing.html#typing.Type)[[任何](http://docs.pythonlang.cn/3/library/typing.html#typing.Any)]], 默认值：None ) –

定义配置的模式类。使用此方法在您的 API 中公开可配置参数。

示例

#示例：state_graph.py
# 从langgraph.graph模块导入START和StateGraph
from langgraph.graph import START, StateGraph

# 定义一个节点函数my_node，接收状态和配置，返回新的状态
def my_node(state, config):
    return {
   
   "x": state["x"] + 1,"y": state["y"] + 2}

# 创建一个状态图构建器builder，使用字典类型作为状态类型
builder = StateGraph(dict)
# 向构建器中添加节点my_node，节点名称将自动设置为'my_node'
builder.add_node(my_node)  # node name will be 'my_node'
# 添加一条边，从START到'my_node'节点
builder.add_edge(START, "my_node")
# 编译状态图，生成可执行的图
graph = builder.compile()
# 调用编译后的图，传入初始状态{"x": 1}
print(graph.invoke({
   
   "x": 1,"y":2}))

结果

{
   
   'x': 2, 'y': 4}

Compiling your graph(编译你的图)

要构建你的图，你首先定义状态，然后添加节点和边，最后进行编译。编译图究竟是什么，为什么需要它？

编译是一个非常简单的步骤。它对图的结构进行一些基本检查（没有孤立的节点等等）。它也是你可以指定运行时参数的地方，例如检查点和断点。你只需调用 .compile 方法即可编译你的图。

#你必须在使用图之前编译它。
graph = graph_builder.compile(...)

编译结果

nodes={
   
   '__start__': PregelNode(config={
   
   'tags': ['langsmith:hidden'], 'metadata': {
   
   }, 'configurable': {
   
   }}, channels=['__start__'], triggers=['__start__'], writers=[ChannelWrite<__root__>(recurse=True, writes=[ChannelWriteEntry(channel='__root__', value=<object object at 0x00000180616FE0C0>, skip_none=True, mapper=None)], require_at_least_one_of=['__root__']), ChannelWrite<start:my_node>(recurse=True, writes=[ChannelWriteEntry(channel='start:my_node', value='__start__', skip_none=False, mapper=None)], require_at_least_one_of=None)]), 'my_node': PregelNode(config={
   
   'tags': [], 'metadata': {
   
   }, 'configurable': {
   
   }}, channels=['__root__'], triggers=['start:my_node'], writers=[ChannelWrite<my_node,__root__>(recurse=True, writes=[ChannelWriteEntry(channel='my_node', value='my_node', skip_none=False, mapper=None), ChannelWriteEntry(channel='__root__', value=<object object at 0x00000180616FE0C0>, skip_none=True, mapper=None)], require_at_least_one_of=['__root__'])])} channels={
   
   '__root__': <langgraph.channels.last_value.LastValue object at 0x0000018061C48470>, '__start__': <langgraph.channels.ephemeral_value.EphemeralValue object at 0x0000018061C484A0>, 'my_node': <langgraph.channels.ephemeral_value.EphemeralValue object at 0x0000018065131BB0>, 'start:my_node': <langgraph.channels.ephemeral_value.EphemeralValue object at 0x0000018064DC0050>} auto_validate=False stream_mode='updates' output_channels='__root__' stream_channels='__root__' input_channels='__start__' builder=<langgraph.graph.state.StateGraph object at 0x0000018064DE0740>

State(状态)

定义图时，你做的第一件事是定义图的 状态。状态 包含图的模式以及归约器函数，它们指定如何将更新应用于状态。状态 的模式将是图中所有 节点 和 边 的输入模式，可以是 TypedDict 或者 Pydantic 模型。所有 节点 将发出对 状态 的更新，这些更新然后使用指定的 归约器 函数进行应用。

Schema(模式)

指定图模式的主要文档化方法是使用 TypedDict。但是，我们也支持使用 Pydantic BaseModel 作为你的图状态，以添加默认值和其他数据验证。

默认情况下，图将具有相同的输入和输出模式。如果你想更改这一点，你也可以直接指定显式输入和输出模式。当你有许多键，其中一些是显式用于输入，而另一些是用于输出时，这很有用。查看此笔记本，了解如何使用。

默认情况下，图中的所有节点都将共享相同的状态。这意味着它们将读取和写入相同的状态通道。可以在图中创建节点写入私有状态通道，用于内部节点通信——查看此笔记本，了解如何执行此操作。

Reducers(归约器)

归约器是理解节点更新如何应用于 状态 的关键。状态 中的每个键都有其自己的独立归约器函数。如果未显式指定归约器函数，则假设对该键的所有更新都应该覆盖它。存在几种不同类型的归约器，从默认类型的归约器开始

Default Reducer(默认归约器)

这两个示例展示了如何使用默认归约器

#示例：default_reducer.py
from typing import TypedDict, List, Dict, Any

class State(TypedDict):
    foo: int
    bar: List[str]

def update_state(current_state: State, updates: Dict[str, Any]) -> State:
    # 创建一个新的状态字典
    new_state = current_state.copy()
    # 更新状态字典中的值
    new_state.update(updates)
    return new_state

# 初始状态
state: State = {
   
   "foo": 1, "bar": ["hi"]}

# 第一个节点返回的更新
node1_update = {
   
   "foo": 2}
state = update_state(state, node1_update)
print(state)  # 输出: {'foo': 2, 'bar': ['hi']}

# 第二个节点返回的更新
node2_update = {
   
   "bar": ["bye"]}
state = update_state(state, node2_update)
print(state)  # 输出: {'foo': 2, 'bar': ['bye']}

在此示例中，没有为任何键指定归约器函数。假设图的输入是 {"foo": 1, "bar": ["hi"]}。然后，假设第一个 节点 返回 {"foo": 2}。这被视为对状态的更新。请注意，节点 不需要返回整个 状态 模式——只需更新即可。应用此更新后，状态 则变为 {"foo": 2, "bar": ["hi"]}。如果第二个节点返回 {"bar": ["bye"]}，则 状态 则变为 {"foo": 2, "bar": ["bye"]}

Nodes(节点)

在 LangGraph 中，节点通常是 Python 函数（同步或async），其中第一个位置参数是状态，（可选地），第二个位置参数是“配置”，包含可选的可配置参数（例如thread_id）。

类似于NetworkX，您可以使用add_node方法将这些节点添加到图形中

#示例：node_case.py
from langchain_core.runnables import RunnableConfig
from langgraph.graph import StateGraph, START
from langgraph.graph import END

# 初始化 StateGraph，状态类型为字典
graph = StateGraph(dict)

# 定义节点
def my_node(state: dict, config: RunnableConfig):
    print("In node: ", config["configurable"]["user_id"])
    return {
   
   "results": f"Hello, {
     
     state['input']}!"}

def my_other_node(state: dict):
    return state

# 将节点添加到图中
graph.add_node("my_node", my_node)
graph.add_node("other_node", my_other_node)

# 连接节点以确保它们是可达的
graph.add_edge(START, "my_node")
graph.add_edge("my_node", "other_node")

graph.add_edge("other_node", END)

# 编译图
print(graph.compile())

在幕后，函数被转换为RunnableLambda，它为您的函数添加了批处理和异步支持，以及本地跟踪和调试。

如果您在没有指定名称的情况下将节点添加到图形中，它将被赋予一个默认名称，该名称等同于函数名称。

graph.add_node(my_node)
# You can then create edges to/from this node by referencing it as `"my_node"`

`START`节点

START节点是一个特殊节点，它代表将用户输入发送到图形的节点。引用此节点的主要目的是确定哪些节点应该首先被调用。

from langgraph.graph import START

graph.add_edge(START, "my_node")
graph.add_edge("my_node", "other_node")

`END`节点

END节点是一个特殊节点，它代表一个终端节点。当您想要指定哪些边在完成操作后没有动作时，会引用此节点。

from langgraph.graph import END

graph.add_edge("other_node", END)

Edges(边)

边定义了逻辑如何路由以及图形如何决定停止。这是您的代理如何工作以及不同节点如何相互通信的重要部分。有一些关键类型的边

普通边：直接从一个节点到下一个节点。
条件边：调用一个函数来确定下一个要转到的节点。
入口点：用户输入到达时首先调用的节点。
条件入口点：调用一个函数来确定用户输入到达时首先调用的节点。

一个节点可以有多个输出边。如果一个节点有多个输出边，则所有这些目标节点将在下一个超级步骤中并行执行。

普通边

如果您总是想从节点 A 到节点 B，您可以直接使用add_edge方法。

#示例：edges_case.py
graph.add_edge("node_a", "node_b")

条件边

如果您想选择性地路由到一个或多个边（或选择性地终止），您可以使用add_conditional_edges方法。此方法接受节点的名称和一个“路由函数”，该函数将在该节点执行后被调用

graph.add_conditional_edges("node_a", routing_function)

类似于节点，routing_function接受图形的当前state并返回一个值。

默认情况下，返回值routing_function用作要将状态发送到下一个节点的节点名称（或节点列表）。所有这些节点将在下一个超级步骤中并行运行。

您可以选择提供一个字典，该字典将routing_function的输出映射到下一个节点的名称。

graph.add_conditional_edges("node_a", routing_function, {
   
   True: "node_b", False: "node_c"})

入口点

入口点是图形启动时运行的第一个节点。您可以从虚拟的START节点使用add_edge方法到要执行的第一个节点，以指定进入图形的位置。

from langgraph.graph import START

graph.add_edge(START, "my_node")

条件入口点

条件入口点允许您根据自定义逻辑从不同的节点开始。您可以从虚拟的START节点使用add_conditional_edges来实现这一点。

from langgraph.graph import START

graph.add_conditional_edges(START, routing_function)