深入理解 LangGraph：构建复杂智能体的状态管理与执行流

---

深入理解 LangGraph：构建复杂智能体的状态管理与执行流

---

在构建高级AI应用时，我们经常会遇到需要协调多个工具、模型和决策步骤的复杂场景。传统的链式调用往往难以应对这种复杂性，而 LangGraph 则提供了一种强大且灵活的解决方案，通过图形化的方式编排AI工作流。然而，对于初学者来说，LangGraph 的状态管理和执行机制可能存在一些疑问。

本文将深入探讨 LangGraph 中的以下核心概念，帮助你更好地理解和运用它：

• 节点返回值的处理机制：LangGraph 如何“理解”节点返回的普通字典？
• 状态的更新策略：Annotated 与 lambda 表达式在状态合并中的作用。
• 用户可见的输出：哪些信息会直接呈现给用户，哪些是内部调试信息？

---

from typing import TypedDict, Annotated, Sequence
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolExecutor

# --- 1. 定义工具 (Tool) ---
# 我们使用 Tavily 搜索工具。LangChain 已经为我们封装好了。
# 这里为了演示，我们也可以创建一个自定义工具。
@tool
def search_tool(query: str):
    """当需要获取网络上的最新信息时，调用此搜索工具。"""
    print(f"---正在执行搜索: {query}---")
    # 在真实场景中，这里会调用真正的搜索引擎 API
    if "langchain" in query.lower():
        return "LangChain 最近发布了 LangGraph，一个用于构建可控智能体的库。"
    return "未找到相关信息。"

# 创建一个工具执行器，它可以调用我们定义的所有工具
tools = [search_tool]
tool_executor = ToolExecutor(tools)

# --- 2. 定义状态 (State) ---
# 状态是图在执行过程中传递的数据结构。它会聚合所有节点产生的信息。
class AgentState(TypedDict):
    # messages 是一个消息序列，它会随着图的执行不断累积
    messages: Annotated[Sequence[BaseMessage], lambda x, y: x + y]

# --- 3. 定义节点 (Nodes) ---
# 节点是图中的计算单元。它可以是一个函数或一个可运行对象。

# 定义模型节点：负责调用大语言模型
llm = ChatOpenAI(model="gpt-4o")

def call_model(state: AgentState):
    """调用 LLM 的节点"""
    messages = state['messages']
    # 将工具信息绑定到模型，让模型知道它可以调用哪些工具
    model_with_tools = llm.bind_tools(tools)
    # 调用模型
    response = model_with_tools.invoke(messages)
    # 将模型的回复（可能包含工具调用）添加到状态中
    return {"messages": [response]}

# 定义工具节点：负责执行工具
def call_tool(state: AgentState):
    """执行工具的节点"""
    last_message = state['messages'][-1]  # 获取模型最新的回复
    
    # 如果最新的消息中有工具调用
    if last_message.tool_calls:
        # 执行工具调用
        tool_calls = last_message.tool_calls
        tool_names = [call['name'] for call in tool_calls]
        print(f"---检测到工具调用: {tool_names}---")
        
        # langchain 的 ToolExecutor 可以方便地批量执行
        tool_outputs = tool_executor.batch(tool_calls)

        # 将工具执行的结果（ToolMessage）返回，以便模型下一步使用
        return {"messages": tool_outputs}
    else:
        # 如果没有工具调用，则不返回任何消息
        return {}

# --- 4. 定义边 (Edges) ---
# 边决定了节点之间的跳转逻辑。

def should_continue(state: AgentState) -> str:
    """条件边：决定是继续调用工具还是结束"""
    last_message = state['messages'][-1]
    # 如果模型的最后一条消息没有工具调用，说明它认为任务完成了，就结束 (END)
    if not last_message.tool_calls:
        return "end"
    # 否则，就去调用工具 (continue)
    else:
        return "continue"

# --- 5. 构建图 (Graph) ---
# 现在，我们将上面定义的所有部分组装成一个图。

# 创建一个 StateGraph 对象，并绑定我们定义的状态
workflow = StateGraph(AgentState)

# 添加节点
# 'agent' 是调用模型的节点
# 'action' 是执行工具的节点
workflow.add_node("agent", call_model)
workflow.add_node("action", call_tool)

# 设置入口点
# 图的执行将从 'agent' 节点开始
workflow.set_entry_point("agent")

# 添加条件边
workflow.add_conditional_edges(
    # 起始节点是 'agent'
    "agent",
    # 判断函数是 should_continue
    should_continue,
    # 根据判断函数的返回值，决定下一个节点
    {
        "continue": "action",  # 如果返回 "continue"，则跳转到 'action' 节点
        "end": END             # 如果返回 "end"，则结束图的执行
    }
)

# 添加普通边
# 当 'action' 节点（工具执行）完成后，总是应该再次调用 'agent' 节点，
# 让模型根据工具返回的结果进行下一步思考。
workflow.add_edge("action", "agent")

# 编译图，生成一个可运行的 app
app = workflow.compile()


# --- 6. 运行图 ---
# 现在我们可以像调用普通函数一样来运行这个图了

inputs = {"messages": [HumanMessage(content="LangChain 最近有什么更新?")]}
for output in app.stream(inputs):
    # stream() 会流式返回每个节点的输出
    # 我们只打印出最终的输出
    for key, value in output.items():
        print(f"节点 '{key}' 的输出:")
        print("---")
        print(value)
    print("\n---\n")

# 获取最终的、聚合后的状态
final_state = app.invoke(inputs)
print("\n===最终AI回复===")
print(final_state['messages'][-1].content)

核心概念解析

1. 节点返回值：一个智能的字典合并过程

在 LangGraph 中，你定义的每个节点（无论是调用大模型的 call_model 还是执行工具的 call_tool）通常会返回一个普通的 Python 字典。例如：

def call_model(state: AgentState):
    # ... 省略代码 ...
    response = model_with_tools.invoke(messages)
    return {"messages": [response]} # 节点返回一个字典

这里并没有什么特殊的返回类型，它确实只是一个键为 "messages"、值为消息列表的字典。

那么，LangGraph 是如何处理这个字典的呢？它并没有“检查”返回值的类型，而是智能地将其与当前图的全局 state 进行合并。这个合并过程的奥秘在于你在定义**状态（State）**时所做的配置。

2. 状态的更新策略：Annotated 与 lambda 的魔力

这是 LangGraph 强大之处的核心。让我们回顾一下 AgentState 的定义：

from typing import TypedDict, Annotated, Sequence
from langchain_core.messages import BaseMessage

class AgentState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], lambda x, y: x + y]

这里的关键是 Annotated[Sequence[BaseMessage], lambda x, y: x + y]。

• Annotated：这是一个 Python 类型提示的特性，允许你为类型添加元数据。LangGraph 利用它来附加关于状态字段的额外行为信息。

• Sequence[BaseMessage]：这指定了 messages 字段的数据类型是一个 BaseMessage 对象的序列（通常是列表）。

• lambda x, y: x + y：这才是真正的“幕后英雄”。它是一个匿名函数，定义了 LangGraph 如何将节点返回的新数据合并到现有状态中。

  • x 代表该字段的旧值（即节点执行前的状态）。
  • y 代表节点返回字典中该字段的新值。

  因此，lambda x, y: x + y 的含义是：将节点返回的 messages (y) 追加到当前状态的 messages (x) 之后。 这种策略非常适合聊天记录这种需要持续累积的序列数据。

总结一下： 每当一个节点执行完毕并返回一个字典时，LangGraph 会：

1. 识别返回字典中的键（例如 "messages"）。
2. 查找 AgentState 中对应键的定义。
3. 如果该键使用了 Annotated 且定义了合并函数，LangGraph 就会调用该函数，将旧状态值和节点返回的新值作为参数传入，计算出更新后的状态值。
4. 如果该键没有 Annotated 或没有定义合并函数，默认行为是直接用新值替换旧值。

这种设计使得你能够对状态的演变拥有细粒度的控制，实现复杂的累积或替换逻辑。

---

3. 用户可见的输出：区分中间步骤与最终结果

在 LangGraph 中，所有节点对状态的修改本质上都是内部的。这意味着节点执行过程中产生的中间数据并不会自动地展示给最终用户。用户的可见输出取决于你如何使用 LangGraph 应用的运行方法。

在你的示例中：

• 流式输出 (app.stream(inputs))：
  当你使用 stream() 方法运行图时，它会流式返回每个节点执行完成后，该节点对图状态的“增量”修改。例如，{"agent": {"messages": [AIMessage(...)]}} 表示 agent 节点向状态的 messages 字段添加了一个 AIMessage。通过遍历 stream() 的输出来打印这些增量，你实际上是在观察每个节点对共享状态的贡献。这些信息对于调试非常有用，也可以用于构建更详细的用户界面，实时展示AI的思考和工具调用过程。

• 最终状态 (app.invoke(inputs))：
  invoke() 方法会等待整个图执行完毕，并返回最终的、完整的状态。你通常会从这个最终状态中提取用户最关心的信息。例如，final_state['messages'][-1].content 会获取 messages 列表中最后一条消息的内容，这通常是模型给出的最终答案或结论，也是你希望直接呈现给最终用户的核心“回复”。

简而言之：

• stream() 提供的是过程性、调试性的输出，显示每个节点对状态的贡献。
• invoke() 后访问的最终状态则包含整个工作流的最终结果，是用户最直接的“答案”。

你可以根据实际应用的需求，选择性地展示这些信息。例如，在聊天机器人中，你可能只向用户显示最终的 AIMessage；而在一个需要用户等待较长时间的复杂任务中，你可能会通过流式输出来展示“AI正在思考”、“正在调用搜索工具”等中间状态，以提升用户体验。

---

总结

LangGraph 通过巧妙地结合 TypedDict、Annotated 和 lambda 表达式，提供了一种极其灵活的状态管理机制。这种机制使得开发者能够精确地定义状态的演变规则，从而构建出能够处理复杂逻辑和动态流程的智能体。理解这些核心概念，将有助于你更高效地设计、实现和调试你的 LangGraph 应用，让你的AI工作流更加智能和可控。

现在，你对 LangGraph 的状态管理和执行流程有了更清晰的理解了吗？你是否考虑在自己的项目中尝试这种强大的编排框架呢？

---