从 LangChain 到 LangGraph 构建可控 Agent 的工程实践

在之前的文章中，我们深入讲解了如何使用 LangChain + Ollama 构建本地大模型调用方案。
但是，随着业务需求不断增长，我们发现仅仅调用模型已经远远不够——我们希望构建具备条件判断、流程控制、工具调用以及状态记忆的智能 Agent。

这时候，LangChain 的 create_agent + LangGraph 的 StateGraph 就成为了真正面向工程的利器。

今天，我们就来讲清楚：

什么是 LangGraph？为什么它是构建可控 Agent 的未来？如何在最新 API 下用 create_agent 和 StateGraph 构建有状态智能体？

---

一、为什么要用 LangGraph 构建 Agent？

在 LangChain 最新版本中，Agent API 已经全面升级，官方推荐使用 create_agent 构建生产级智能体，并基于 LangGraph 对内部流程进行图结构编排。

create_agent
是一个高阶接口，用于构建图式 Agent。它内部依赖 LangGraph 执行器，在一个状态图中逐步完成模型推理、工具调用、决策流跳转等逻辑。

过去我们可能使用 Chain + Logic 组合来处理流程，但随着逻辑复杂度增加，线性写法很难维护、扩展和调试。
而 LangGraph 的图结构 可以让我们：

• 用 状态（state） 表达全局对话或任务信息
• 用 节点（nodes） 表达流程逻辑
• 用 边（edges） 表达不同分支与条件
• 用 记忆插件 实现短期和长期记忆

这组合起来，就形成了一个可控、有状态流程的智能 Agent。

---

二、什么是 StateGraph？

StateGraph 是 LangGraph 的核心抽象，它表示一个具有全局状态和节点流转逻辑的图。
每个节点本质上是一个函数，这个函数：

• 接收当前全局状态
• 返回修改后的状态或跳转指令

它非常适合把“复杂流程问题”映射为“图状态机”，无论是对话、工具调用还是多步骤任务。

简化后的 StateGraph 工作流程如下：

StateGraph(StateType)
    ├── add_node(name, function)
    ├── add_edge(source, target)
    └── compile()
        → graph.invoke({state input})

解释一下：

• StateType：定义全局状态结构
• add_node：定义节点行为逻辑
• add_edge：定义节点间的流程跳转关系

---

三、新 API：create_agent 如何使用？

从 LangChain 最新版本开始，旧的 create_react_agent 已被废弃，统一使用 create_agent。

一个最简单的示例：

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="qwen3:8b",
    base_url="http://localhost:11434/v1",
    api_key="your api key",
)

agent = create_agent(
    model=model,
    tools=[],
    system_prompt="你是一个智能助手，负责处理用户请求。",
)

response = agent.invoke({
    "messages": [{"role": "user", "content": "什么是 LangGraph？"}]
})
print(response)

📌 重点说明：

• model 可以是任何支持工具调用的聊天模型
• tools 是 Agent 可调用的外部能力（如检索、代码执行等）
• system_prompt 是 Agent 的基础角色指令

实际上，create_agent 内部会构建一个 StateGraph，并把模型 + 工具节点组合成可执行流程。

---

四、结合 StateGraph：构建更复杂的图式 Agent

如果你希望在 Agent 内部实现更复杂的流程（如输入校验、分支工具调用、状态记录等），可以直接使用 StateGraph。

下面是一个包含两个节点的示例：通过 LLM 生成回答并记录状态。

from typing import TypedDict, Annotated
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, END
from langgraph.graph.message import add_messages
from langchain_core.messages import HumanMessage

# 1. 定义全局状态
class ChatState(TypedDict):
    messages: Annotated[list, add_messages]

# 2. 初始化模型
llm = ChatOpenAI(
    model="qwen3:8b",
    base_url="http://localhost:11434/v1",
    api_key="your api key",
)

# 3. 定义节点
def chat_node(state: ChatState):
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

# 4. 构建 StateGraph
graph = StateGraph(ChatState)
graph.add_node("chat", chat_node)
graph.set_entry_point("chat")
graph.add_edge("chat", END)
graph = graph.compile()

# 生成可视化图
with open("/Users/zhoupb/workspace-ai/atnk-ai/data/demo.png", "wb") as f:
    f.write(graph.get_graph(xray=True).draw_mermaid_png())

# 5. 调用
result = graph.invoke(
    {"messages": [HumanMessage(content="用一句话介绍什么是 LangGraph？")]},
)
print(result["messages"][-1].content)

在这个例子中：

• ChatState：全局状态结构
• chat_node：处理模型逻辑的节点
• edges：从起点直接进入 chat_node，并更新消息状态

你可以在图内使用更复杂的节点连接和条件分支。([docs.langchain.org.cn][2])

---

五、记忆（Memory）如何集成？

智能体的核心能力之一，就是记住之前的对话或操作历史。

LangGraph 提供了开箱即用的短期记忆机制，基于 检查点（checkpoint） 存储状态。以下是短期记忆的示例：

from langgraph.checkpoint.memory import InMemorySaver

#...省略

# 使用检查点保存状态
checkpointer = InMemorySaver()
graph = graph.compile(checkpointer=checkpointer)

# 使用同一个 thread_id，触发“记忆”
config = {"configurable": {"thread_id": "local-chat"}}

# 第一轮
result = graph.invoke(
    {"messages": [HumanMessage(content="用一句话介绍什么是 LangGraph？")]},
    config=config
)
print(result["messages"][-1].content)
print("-" * 100)

# 第二轮（保留上下文）
result = graph.invoke(
    {"messages": [HumanMessage(content="用一句话介绍它和 LangChain 的关系？")]},
    config=config
)
print(result["messages"][-1].content)

同一个 thread_id 下的状态会被持续保存，实现短期记忆，非常适合多轮对话场景。

---

六、工程化建议：可控、可视化与部署

在真实工程场景下，图式 Agent 的能力远不止示例那么简单：

1️⃣ 自定义状态扩展

可以在 Agent 内定义更多状态字段，比如用户偏好、执行路径、决策数据等：

class CustomState(TypedDict):
    messages: list
    user_settings: dict

调用 create_agent 时，通过 state_schema 参数传入，Agent 就会自动维护这些字段。

---

2️⃣ 集成工具能力

Agent 可以调用检索、代码执行、数据库查询等工具。
工具可以作为节点，或者直接传入 tools 列表，由 Agent 在执行过程中调用，显著增强实际能力。

---

3️⃣ 可观测与调试

结合 LangSmith Trace 等可观测平台，可以：

• 可视化执行路径
• 追踪状态变化
• 调试复杂流程

大幅提高生产环境的可维护性。

---

七、工程化细节总结

技术点	最新 API
构建 Agent	create_agent()（替代旧的 create_react_agent）
状态管理	用 StateGraph 定义全局状态，并流转节点逻辑
记忆	基于 checkpoint 机制实现短期记忆
自定义状态	可通过 state_schema 扩展
可控流程	用节点 + 边 + Command 控制流程

---

八、结语：从链到图

如果说传统 Chain 是线性的能力组合，那么 StateGraph 就是有状态的全局控制流机；
如果说 Chain 是工具驱动流程片段，Graph 就是工程级的智能协同平台。

在 Agent 需求越来越复杂的今天，单靠 Chain 已无法应对多步骤决策、逻辑分支和记忆维护，而 LangGraph 的图式设计正是为可控 Agent 而生。

如果你正在做：

• 多步对话机器人
• 带外部工具调用的智能体
• 具有长期记忆的应用
• 需要可视化与调试的生产系统

那么，从 LangChain 到 LangGraph 的升级，将是你最值得投入的一条路线。