纲要
LangGraph概述:图结构替代链式调用- 核心概念
State:节点间共享的数据流Node:功能单元,输入 → 输出Edge:普通边与条件边Graph:编排节点与边的执行流程
- 基础入门:第一个 LangGraph
- 定义
State与节点函数 - 构建图并可视化
- 定义
- 工作流控制模式
- 串行执行
- 并行分支
- 条件分支与循环
- 运行时动态配置
Map-Reduce模式
- 完整可运行示例
- 环境准备
- 综合演示代码
- API 速览
- 参考文档
- 总结
LangGraph 是什么
LangChain 中的 Chain 概念适用于线性串联任务,但当应用需要复杂的分支、循环或并行处理时,链式结构难以应对。LangGraph 将应用建模为有向图:节点代表任务单元,边控制数据流动方向。这种范式天然适合多步推理、人机协同和多智能体编排。
LangGraph 建立在 LangChain 之上,与其生态系统完全兼容,开发者可以无缝复用现有的 LCEL 链、工具和模型。
核心概念:State、Node、Edge、Graph
一切工作流都由四个核心元素构成:
- State:在节点之间传递的共享数据,通常用
TypedDict或Pydantic模型定义。State的更新遵循 reducer 函数指定的合并逻辑。 - Node:一个 Python 可调用对象(函数或
Runnable),接收State并返回部分更新的State。节点可以封装大模型调用、工具执行或任意业务逻辑。 - Edge:
- 普通边:固定指向下一个节点,表示确定性流转。
- 条件边:根据
State中的某个字段或函数返回值动态决定目标节点,支持分支和循环。
- Graph:组合节点和边的执行引擎,通过
compile()生成可运行对象,支持invoke、stream和ainvoke等接口。
基础入门:第一个 LangGraph
从一个极简示例开始:一个节点响应消息,然后结束。
from typing import TypedDict
from langgraph.graph import StateGraph, END
from langchain_core.messages import HumanMessage, AIMessage
# 1. 定义 State
class SimpleState(TypedDict):
messages: list
# 2. 定义节点
def greeting_node(state: SimpleState) -> dict:
# 安全地获取最后一条用户消息
user_msg = state["messages"][-1].content if state.get("messages") else "未提供内容"
reply = AIMessage(content=f"你好,你刚才说:「{user_msg}」")
return {"messages": state.get("messages", []) + [reply]}
# 3. 构建图
builder = StateGraph(SimpleState)
builder.add_node("greet", greeting_node)
builder.set_entry_point("greet")
builder.add_edge("greet", END)
app = builder.compile()
# 4. 运行
result = app.invoke({"messages": [HumanMessage(content="大家好")]})
for m in result["messages"]:
print(m.content)
这段代码展示了 StateGraph 的基本用法:定义状态、添加节点、设置入口和出口,最后编译运行。
图可视化
LangGraph 支持将图结构渲染为 Mermaid 图表,便于调试和文档生成:
# 生成 Mermaid 代码
print(app.get_graph().draw_mermaid())
# 在 Jupyter 中直接渲染
# from IPython.display import Image
# Image(app.get_graph().draw_mermaid_png())
工作流控制模式
串行执行
多个节点按顺序执行,上一节点的输出自动传递到下一节点。这是最基础的工作流模式。
from typing import TypedDict
from langgraph.graph import StateGraph, END
class SerialState(TypedDict):
value: str
def step_a(state: SerialState) -> dict:
return {"value": state["value"] + " -> A"}
def step_b(state: SerialState) -> dict:
return {"value": state["value"] + " -> B"}
def step_c(state: SerialState) -> dict:
return {"value": state["value"] + " -> C"}
builder = StateGraph(SerialState)
builder.add_node("a", step_a)
builder.add_node("b", step_b)
builder.add_node("c", step_c)
builder.set_entry_point("a")
builder.add_edge("a", "b")
builder.add_edge("b", "c")
builder.add_edge("c", END)
app = builder.compile()
result = app.invoke({"value": "START"})
print(result["value"]) # START -> A -> B -> C
并行分支
从一个节点出发,可以同时触发多个后继节点,它们的输出会按 State 中定义的 reducer 规则(如列表追加)自动汇合。
from typing import TypedDict, Annotated
import operator
from langgraph.graph import StateGraph, END
class BranchState(TypedDict):
items: Annotated[list, operator.add]
def source(state: BranchState) -> dict:
# 确保 items 不为空,供下游节点安全访问
return {"items": ["root"]}
def branch_x(state: BranchState) -> dict:
last = state["items"][-1] if state.get("items") else "root"
return {"items": [f"X({last})"]}
def branch_y(state: BranchState) -> dict:
last = state["items"][-1] if state.get("items") else "root"
return {"items": [f"Y({last})"]}
builder = StateGraph(BranchState)
builder.add_node("src", source)
builder.add_node("x", branch_x)
builder.add_node("y", branch_y)
builder.set_entry_point("src")
builder.add_edge("src", "x")
builder.add_edge("src", "y")
builder.add_edge("x", END)
builder.add_edge("y", END)
app = builder.compile()
result = app.invoke({"items": []})
print(result["items"]) # 输出: ['root', 'X(root)', 'Y(root)'](顺序可能不同)
注意:并行分支的执行顺序是不确定的,如果业务逻辑依赖顺序,应使用串行模式或在 State 中维护排序信息。
条件分支与循环
条件边根据当前 State 动态选择下一个节点。配合循环可以实现类似 Agent 的“思考-行动”循环。
from typing import TypedDict, Annotated, Sequence
from langchain_core.messages import BaseMessage
from langgraph.graph import StateGraph, END
import operator
class LoopState(TypedDict):
messages: Annotated[Sequence[BaseMessage], operator.add]
counter: int
def thinker(state: LoopState) -> dict:
# 模拟思考:每轮递增计数器
return {"counter": state.get("counter", 0) + 1}
def router(state: LoopState) -> str:
if state.get("counter", 0) < 5:
return "continue"
return "end"
builder = StateGraph(LoopState)
builder.add_node("think", thinker)
builder.set_entry_point("think")
builder.add_conditional_edges(
"think",
router,
{
"continue": "think",
"end": END
}
)
app = builder.compile()
result = app.invoke({"messages": [], "counter": 0})
print(result["counter"]) # 输出 5
运行时动态配置
在调用时传入配置,可以动态切换节点内使用的资源,例如选择不同的 LLM 或调整超参数。
from typing import TypedDict
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
class ConfigState(TypedDict):
query: str
answer: str
def model_node(state: ConfigState, config: dict) -> dict:
# 从运行时配置中读取模型名称
model_name = config.get("configurable", {}).get("model", "gpt-3.5-turbo")
llm = ChatOpenAI(model=model_name, temperature=0)
response = llm.invoke(state["query"])
return {"answer": response.content}
builder = StateGraph(ConfigState)
builder.add_node("model", model_node)
builder.set_entry_point("model")
builder.add_edge("model", END)
app = builder.compile()
# 使用默认模型
res1 = app.invoke({"query": "说一个关于程序员的简短笑话"})
print(res1["answer"])
# 动态切换模型(假设已配置相应的 API Key)
res2 = app.invoke(
{"query": "说一个关于程序员的简短笑话"},
{"configurable": {"model": "deepseek-chat"}}
)
print(res2["answer"])
Map-Reduce 模式
将一个任务拆分为多个子任务并行处理(Map),再汇总结果进行最终决策(Reduce)。以下示例将一个主题扩展为多个子话题,分别生成笑话,最后评选最佳笑话。
from typing import TypedDict, List, Annotated
import operator
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.schema.output_parser import StrOutputParser
class JokeState(TypedDict):
topic: str
subtopics: List[str]
jokes: Annotated[list, operator.add]
best_joke_id: int
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0.7)
def generate_subtopics(state: JokeState) -> dict:
prompt = ChatPromptTemplate.from_template(
"围绕「{topic}」生成3个搞笑段子主题,以逗号分隔,只返回主题本身。"
)
chain = prompt | llm | StrOutputParser()
result = chain.invoke({"topic": state["topic"]})
subtopics = [t.strip() for t in result.split(",")]
return {"subtopics": subtopics}
def generate_jokes(state: JokeState) -> dict:
jokes = []
prompt = ChatPromptTemplate.from_template("写一个关于「{subtopic}」的短笑话")
chain = prompt | llm | StrOutputParser()
for sub in state.get("subtopics", []):
joke = chain.invoke({"subtopic": sub})
jokes.append(joke)
return {"jokes": jokes}
def pick_best(state: JokeState) -> dict:
jokes_text = "\n".join([f"{i}: {j}" for i, j in enumerate(state.get("jokes", []))])
if not jokes_text:
return {"best_joke_id": -1}
prompt = ChatPromptTemplate.from_template(
"以下是几个笑话,选出最搞笑的一个,只返回它的编号:\n{jokes}"
)
chain = prompt | llm | StrOutputParser()
best_id = int(chain.invoke({"jokes": jokes_text}))
return {"best_joke_id": best_id}
builder = StateGraph(JokeState)
builder.add_node("gen_subtopics", generate_subtopics)
builder.add_node("gen_jokes", generate_jokes)
builder.add_node("best_joke", pick_best)
builder.set_entry_point("gen_subtopics")
builder.add_edge("gen_subtopics", "gen_jokes")
builder.add_edge("gen_jokes", "best_joke")
builder.add_edge("best_joke", END)
app = builder.compile()
result = app.invoke({"topic": "程序员", "subtopics": [], "jokes": [], "best_joke_id": -1})
print("最佳笑话ID:", result["best_joke_id"])
print("笑话列表:", result["jokes"])
完整可运行示例
环境准备
确保已安装以下依赖(版本要求基于 langgraph>=0.0.20):
pip install langgraph langchain langchain-openai
如使用 DeepSeek 等第三方模型,需额外配置环境变量:
export OPENAI_API_KEY="your-api-key"
export DEEPSEEK_API_KEY="your-deepseek-key" # 如使用 DeepSeek
综合演示代码
以下代码演示了一个包含条件分支、循环和动态配置的完整 Agent 工作流:
"""
LangGraph 综合演示:带条件循环和动态配置的问答 Agent
适用版本:langgraph >= 0.0.20
"""
from typing import TypedDict, Annotated, Sequence
import operator
from langgraph.graph import StateGraph, END
from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
from langchain_openai import ChatOpenAI
class AgentState(TypedDict):
messages: Annotated[Sequence[BaseMessage], operator.add]
iteration: int
max_iterations: int
def call_model(state: AgentState, config: dict) -> dict:
model_name = config.get("configurable", {}).get("model", "gpt-3.5-turbo")
llm = ChatOpenAI(model=model_name, temperature=0.3)
response = llm.invoke(state["messages"])
return {"messages": [response]}
def should_continue(state: AgentState) -> str:
# 检查是否达到最大迭代次数或消息中包含结束信号
if state.get("iteration", 0) >= state.get("max_iterations", 3):
return "end"
# 检查最后一条 AI 消息是否包含结束标记
last_msg = state["messages"][-1] if state.get("messages") else None
if last_msg and hasattr(last_msg, "content") and "STOP" in last_msg.content.upper():
return "end"
return "continue"
builder = StateGraph(AgentState)
builder.add_node("agent", call_model)
builder.set_entry_point("agent")
builder.add_conditional_edges(
"agent",
should_continue,
{
"continue": "agent",
"end": END
}
)
app = builder.compile()
result = app.invoke(
{"messages": [HumanMessage(content="请用三句话解释什么是 AI Agent,然后输出 STOP")],
"iteration": 0,
"max_iterations": 5},
{"configurable": {"model": "gpt-3.5-turbo"}}
)
for msg in result["messages"]:
if isinstance(msg, AIMessage):
print(f"AI: {msg.content}")
API 速览
| API | 所属模块 | 方法签名 | 说明 |
|---|---|---|---|
StateGraph | langgraph.graph | StateGraph(state_schema: Type) | 图构建器,需传入 State 类型 |
add_node | StateGraph | add_node(name: str, action: Callable) | 添加节点,action 接收 state 和可选的 config |
add_edge | StateGraph | add_edge(from: str, to: str) | 添加普通边 |
add_conditional_edges | StateGraph | add_conditional_edges(from: str, condition: Callable, mapping: dict) | 添加条件边 |
set_entry_point | StateGraph | set_entry_point(name: str) | 设置入口节点 |
compile | StateGraph | compile() | 编译为可运行的图对象 |
invoke | CompiledGraph | invoke(input: dict, config: dict = None) | 同步执行 |
ainvoke | CompiledGraph | ainvoke(input: dict, config: dict = None) | 异步执行 |
stream | CompiledGraph | stream(input: dict, config: dict = None) | 流式输出 |
参考文档
官方文档
参考链接
总结
LangGraph 通过图结构重新定义了 AI 工作流的组织方式,让开发者可以像搭积木一样组合节点,实现从简单串行到复杂 Map-Reduce 的各种控制模式。掌握这些基础后,构建多智能体系统、Human-in-the-loop 等高级应用将水到渠成。
本文覆盖了 LangGraph 核心概念、节点与可控制性的所有模式(串行、分支、条件循环、运行时配置、Map-Reduce),并给出了代码示例。核心技术栈要点:
- 状态管理:使用
TypedDict定义状态结构,Annotated+ reducer 函数控制状态合并逻辑 - 图构建:
StateGraph作为图构建器,节点、边、条件边形成完整的执行流程图 - 执行模式:支持
invoke同步执行、ainvoke异步执行和stream流式输出 - 运行时配置:通过
configurable字段实现节点级动态参数注入 - 条件路由:条件边支持复杂的分支逻辑和循环控制,是实现 Agent 自主决策的核心
- 生态兼容:完全兼容
LangChain的模型、工具和提示模板
363



被折叠的 条评论
为什么被折叠?



