
LangGraph教程:用Python构建有状态AI代理
深入了解LangGraph框架,学习如何利用Python构建功能强大且具有记忆能力的有状态AI代理。本教程将引导您从基础概念到高级应用,助您在2026年掌握AI代理开发的核心技术。通过实际代码示例,您将学会如何设计、实现和部署复杂的AI工作流。
LangGraph教程:用Python构建有状态AI代理
在2026年,AI代理的开发已经进入了一个新的阶段,对能够维持上下文和执行复杂多步骤任务的系统需求日益增长。LangGraph作为LangChain生态系统的重要扩展,提供了一种强大的框架,用于构建具有持久记忆和复杂决策逻辑的有状态AI代理。本篇LangGraph教程将深入探讨如何利用Python,从零开始构建这些智能代理,涵盖从基本概念到高级工作流的方方面面。无论您是希望优化客户服务机器人,还是开发能够自主完成研发任务的智能体,LangGraph都能为您提供所需的工具和灵活性。我们将探索其独特的图结构和状态管理机制,帮助您理解其核心优势,并在实际项目中加以应用。
LangGraph的核心优势在于其能够显式地管理代理的状态和流程,这对于构建可靠且可控的复杂AI系统至关重要。与传统无状态的LLM调用不同,有状态AI代理能够记住过去的交互,并根据这些记忆做出更明智的决策。这意味着您的AI代理不再是简单的问答机器,而是能够进行多轮对话、规划任务、使用工具,甚至与其他代理协作的智能实体。例如,一个基于LangGraph构建的研发代理可以逐步分析问题、查阅文档、编写代码、运行测试,并根据结果迭代改进,所有这些都通过其内部状态和图结构进行协调。本文将详细介绍这些构建模块,并提供实用的代码示例,确保您能轻松上手。
理解LangGraph核心概念:有状态与图结构
LangGraph之所以强大,在于其对“状态”和“图”的明确定义。状态是代理在执行任务过程中累积的知识和上下文,它允许代理在不同步骤之间保持连贯性。图结构则定义了代理可能采取的所有路径和决策点,每个节点代表一个操作(例如,调用LLM、执行工具、人工干预),每条边则表示状态转换或流程控制。这种LangGraph基于图的架构提供了极高的灵活性,能够轻松地实现条件路由、循环和多代理协作。例如,一个复杂的金融分析代理可以根据市场数据自动决定是进行深度报告分析,还是直接执行交易模拟,并在每个步骤中更新其内部状态,确保决策的连续性和一致性。
- 状态 (State):代理的记忆和上下文,随时间演进。
- 节点 (Nodes):图中的基本操作单元,可以是LLM调用、工具执行或自定义函数。
- 边 (Edges):连接节点,定义状态转换和流程逻辑。
- 条件路由 (Conditional Routing):根据状态动态选择执行路径。
- 循环 (Loops):实现迭代和自修正行为,例如代码编写和测试循环。
为什么选择LangGraph构建您的AI代理?
在2026年,市场上有多种AI代理框架,但LangGraph因其卓越的状态管理和图式控制脱颖而出。它提供了对代理行为的细粒度控制,这对于构建可预测、可调试且高效的生产级AI应用程序至关重要。例如,与一些更抽象的框架相比,LangGraph允许开发者精确地定义每个步骤的输入、输出和状态更新方式。这使得调试变得更加容易,并且可以更好地集成人工审核(human-in-the-loop)机制。许多企业,如Klarna和Uber,已经利用LangGraph在复杂业务流程中节省了大量资源,这充分证明了其在构建企业级有状态AI代理方面的价值。 延伸阅读: CrewAI 教程:构建 AI 团队自动化复杂任务
提示
LangGraph特别适合需要多步骤决策、循环反馈和持久记忆的复杂工作流。如果您的AI代理需要超越简单的问答,LangGraph是您的理想选择。
LangGraph入门:构建您的第一个有状态代理
构建基本LangGraph代理
- 1
步骤 1: 安装LangGraph和依赖
首先,确保您的Python环境中安装了LangGraph和LangChain。您还需要安装一个LLM提供商的客户端库,例如OpenAI或Google Gemini。建议使用虚拟环境进行管理。
- 2
步骤 2: 定义代理的状态
代理的状态是其记忆和上下文。使用TypedDict定义一个清晰的状态结构,以便在图中的不同节点之间传递信息。例如,可以包含用户输入、LLM响应、工具结果等。
- 3
步骤 3: 创建LLM和工具节点
定义图中的各个节点。通常,您会有一个调用大型语言模型(LLM)的节点和一个或多个执行特定工具(如搜索、API调用)的节点。这些节点将接收当前状态作为输入,并返回更新后的状态。
- 4
步骤 4: 构建图结构
使用`StateGraph`类来构建您的代理图。添加您定义的节点,并使用`add_edge`和`add_conditional_edges`方法定义节点之间的连接和条件逻辑。这将决定代理的执行流程和决策路径。
- 5
步骤 5: 编译并运行代理
使用`compile()`方法将您的图转换为可执行的`Runnable`对象。然后,您可以像调用任何LangChain `Runnable`一样调用它,传入初始状态并观察代理如何根据您的定义进行交互和状态更新。
在构建有状态AI代理时,定义清晰的初始状态至关重要。这个初始状态将作为代理执行流程的起点,并随着代理的运行而不断更新。例如,一个简单的问答代理的初始状态可能只包含用户提出的问题,而一个复杂的规划代理的初始状态可能包含目标、可用工具列表和当前的观察结果。理解状态如何在节点之间传递和修改,是掌握LangGraph的关键。我们推荐使用像 GPT-5.3-Codex 这样的高级编码模型来辅助您编写和调试这些复杂的图结构,它们在理解和生成Python代码方面表现出色。
from typing import TypedDict, Annotated, List
import operator
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
# 1. 定义代理状态
class AgentState(TypedDict):
messages: Annotated[List[BaseMessage], operator.add]
current_task: str
tool_output: str
# 2. 初始化LLM
llm = ChatOpenAI(model="gpt-5-chat", temperature=0)
# 3. 定义LLM节点
def call_model(state: AgentState):
messages = state["messages"]
response = llm.invoke(messages)
return {"messages": [response]}
# 4. 定义工具节点 (示例,实际工具需实现)
def call_tool(state: AgentState):
# 假设这里调用一个搜索工具
print(f"执行工具进行搜索: {state['current_task']}")
tool_result = "搜索结果:LangGraph是一个用于构建有状态AI代理的框架。"
return {"tool_output": tool_result, "messages": [HumanMessage(content=tool_result)]}
# 5. 构建图
workflow = StateGraph(AgentState)
workflow.add_node("llm", call_model)
workflow.add_node("tool", call_tool)
workflow.add_edge(START, "llm")
# 条件路由:如果LLM响应需要工具,则转到工具节点
def should_continue(state: AgentState):
last_message = state["messages"][-1]
if "需要工具" in last_message.content:
return "tool"
else:
return "end"
workflow.add_conditional_edges("llm", should_continue, {"tool": "tool", "end": END})
workflow.add_edge("tool", END) # 工具执行完直接结束,或返回LLM继续处理
# 编译图
app = workflow.compile()
# 运行代理
inputs = {"messages": [HumanMessage(content="请告诉我LangGraph是什么,并模拟一次工具搜索。")],
"current_task": "查询LangGraph信息"}
for s in app.stream(inputs):
print(s)
print("----")
# 更复杂的运行,模拟LLM需要工具
inputs_with_tool_request = {"messages": [HumanMessage(content="请使用工具查询最新的AI发展。我需要工具。")],
"current_task": "查询最新AI发展"}
print("\n--- 模拟LLM需要工具的场景 ---")
for s in app.stream(inputs_with_tool_request):
print(s)
print("----")
高级LangGraph应用:多代理协作与循环
LangGraph的真正威力在于其支持复杂的多代理系统和循环工作流。在2026年,构建能够模拟人类团队协作的AI系统已成为可能。例如,您可以设计一个由“规划代理”、“执行代理”和“审核代理”组成的团队,它们各自负责图中的不同节点。规划代理使用 Gemini 3.1 Pro Preview 来生成任务计划,执行代理调用工具或API完成具体操作,而审核代理则使用 Qwen3 Max Thinking 来评估结果并提供反馈。这种模式允许代理在遇到问题时自动进行迭代和修正,极大地提高了AI系统的鲁棒性和自主性。
实现循环是LangGraph的另一个关键特性。例如,在一个代码生成与测试的场景中,代理可以先生成代码,然后执行测试。如果测试失败,代理会根据错误信息再次调用LLM进行代码修改,并重新运行测试,直到通过为止。这种循环机制通过条件边和状态更新来实现,确保了复杂任务的自动化和自修正能力。为了实现高效的循环,选择一个能够快速理解和处理复杂指令的LLM至关重要,例如 DeepSeek V3.2 或 GLM 4.6V,它们在代码生成和逻辑推理方面表现卓越。通过精细地设计这些循环,我们可以构建出真正意义上的自主AI工作流。 延伸阅读: LlamaIndex 教程: 使用本地LLM构建知识库
from typing import TypedDict, Annotated, List
import operator
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
# 1. 定义更复杂的代理状态,包含任务、代码和测试结果
class CodeAgentState(TypedDict):
task: str
code: Annotated[str, operator.setitem]
test_results: Annotated[List[str], operator.add]
iterations: int
# 2. 初始化LLM (假设GPT-5.3-Codex用于代码生成)
code_llm = ChatOpenAI(model="gpt-5-3-codex", temperature=0.2)
# 3. 定义代码生成节点
def generate_code(state: CodeAgentState):
prompt = f"根据任务 '{state['task']}' 生成Python代码。当前代码:{state.get('code', '无')}"
response = code_llm.invoke([HumanMessage(content=prompt)])
print(f"生成代码: {response.content[:50]}...")
return {"code": response.content, "iterations": state['iterations'] + 1}
# 4. 定义代码测试节点 (模拟执行和测试)
def test_code(state: CodeAgentState):
code = state["code"]
# 模拟执行代码并返回测试结果
if "def add(a, b):" in code and state['iterations'] < 3: # 模拟前几次测试失败
result = "测试失败:加法函数未正确处理负数。请修改。"
print(f"测试结果:{result}")
return {"test_results": [result]}
else:
result = "测试通过:所有测试用例均通过。"
print(f"测试结果:{result}")
return {"test_results": [result]}
# 5. 构建图
workflow = StateGraph(CodeAgentState)
workflow.add_node("generate_code", generate_code)
workflow.add_node("test_code", test_code)
workflow.add_edge(START, "generate_code")
workflow.add_edge("generate_code", "test_code")
# 条件路由:根据测试结果决定是否循环
def should_loop(state: CodeAgentState):
if "测试失败" in state["test_results"][-1] and state["iterations"] < 5:
print("测试失败,返回重新生成代码...")
return "generate_code"
else:
print("测试通过或达到最大迭代次数,结束。")
return END
workflow.add_conditional_edges("test_code", should_loop, {"generate_code": "generate_code", END: END})
# 编译图
app = workflow.compile()
# 运行代理
initial_state = {"task": "编写一个Python函数,实现两个数字的加法,并能处理正负数",
"code": "",
"test_results": [],
"iterations": 0}
print("\n--- 运行代码生成与测试代理 ---")
for s in app.stream(initial_state):
print(s)
print("----")
LangGraph与其他AI代理框架的比较
在2026年,AI代理框架的生态系统日益成熟。虽然许多框架致力于简化代理开发,但LangGraph通过其图式和有状态方法提供了独特的优势。例如,与AutoGen等框架相比,AutoGen更侧重于通过对话来协调多代理,而LangGraph则提供了更显式的图结构来定义代理间的工作流和状态传递。这使得LangGraph在需要精细控制流程、处理复杂条件逻辑和实施严格错误恢复机制的场景中表现出色。对于企业级应用,例如Klarna和Uber,这种精细控制是必不可少的,因为它们需要高度可靠和可审计的AI系统。
AI代理框架比较 (2026)
| Критерий | LangGraph | AutoGen | CrewAI | OpenAI Swarm |
|---|---|---|---|---|
| 状态管理 | 显式有状态✓ | 隐式对话 | 有状态 | 实验性/轻量 |
| 工作流控制 | 图式/细粒度✓ | 对话式 | 任务驱动 | 有限 |
| 多代理支持 | 优秀 | 优秀 | 良好 | 中等 |
| 循环/迭代 | 原生支持✓ | 通过对话实现 | 有限 | 不适用 |
| 调试性 | 高 (图可视化)✓ | 中等 | 中等 | 低 |
| 生产就绪 | 高✓ | 中等 | 中等 | 低 |
从性能角度来看,最新的基准测试显示,LangGraph在数据分析任务中通常展现出最低的延迟和最高的处理速度,这得益于其优化的图执行引擎。例如,与CrewAI或LangChain的原始代理相比,LangGraph的图编译方法减少了不必要的LLM调用和状态转换开销。对于需要处理大量并发请求或实时决策的场景,这种性能优势至关重要。因此,对于那些追求极致性能和可控性的开发者来说,LangGraph无疑是构建下一代有状态AI代理的首选框架。您可以通过集成像 O1 这样的高性能模型来进一步提升代理的响应速度和处理能力。
最佳实践与未来展望
在2026年,构建高效且健壮的LangGraph代理需要遵循一些最佳实践。首先,清晰地定义代理在不同阶段的状态结构,确保状态更新的原子性和一致性。其次,将复杂的逻辑分解为小的、可重用的节点,每个节点负责一个明确的任务。这不仅有助于提高代码的可读性,也方便调试和测试。最后,积极利用LangGraph提供的可视化工具(例如,通过LangSmith),以便更好地理解代理的执行流程和状态变化。这些工具在诊断复杂循环和条件路由问题时尤其宝贵。随着AI技术的不断发展,LangGraph将继续支持更复杂的工具集成、更智能的条件逻辑以及更强大的多模态能力,例如与 GPT-5 Image Mini 结合进行视觉推理。 延伸阅读: 如何构建多智能体AI系统:架构指南
- 保持状态定义简洁明了。
- 将每个节点视为一个独立的、可测试的单元。
- 利用条件路由实现灵活的决策逻辑。
- 设计健壮的错误处理机制,例如重试或人工干预节点。
- 定期审查和优化图结构,以提高效率和可维护性。
- 考虑将更专业的模型用于特定节点,例如使用 Qwen3 Coder Plus 进行代码生成,或使用 Nemotron Nano 12B 2 VL 进行视觉信息处理。
重要提示
随着AI代理变得越来越自主,确保透明度和可解释性至关重要。LangGraph的图结构有助于可视化代理的决策路径,这对于审计和理解复杂行为非常有益。务必在设计阶段就考虑这些因素。
常见问题解答
常见问题解答
总结
本篇LangGraph教程深入探讨了如何利用Python构建强大的有状态AI代理。我们了解了LangGraph的核心概念,包括状态、节点、边和条件路由,并通过实际代码示例展示了如何从零开始构建一个基本代理,并进一步扩展到多代理协作和循环工作流。在2026年,LangGraph凭借其卓越的状态管理能力和灵活的图结构,已成为开发复杂、自主AI系统的首选框架。掌握LangGraph将使您能够创建更智能、更健壮、更具生产力的AI应用程序,从而在快速发展的AI领域保持领先。现在就开始您的LangGraph之旅,构建下一代智能代理吧!


