LangGraph 入门教程:Python 安装、核心概念与跑通第一个状态图智能体

面向搜「python 安装 langgraph」和「langgraph 中文 文档」的初学者:本文按 LangChain 官方最新 Graph API 规范,讲清安装步骤、State/Node/Edge 四大概念,并从零写出第一个带工具调用循环的 StateGraph。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. LangGraph 的核心思想只有一句话:把智能体工作流写成一张「共享状态(State)在函数节点(Node)之间顺着边(Edge)循环流转」的有向图。
  2. Python 安装需要拆成「核心图引擎 + 模型集成包」两部分:先装 langgraph,再按你手里的密钥装 langchain-openai、langchain-anthropic 或本地 langchain-ollama。
  3. 关于「中文文档」的避坑提醒:官方唯一实时维护的主文档在 docs.langchain.com(英文)。看第三方中文搬运教程时,凡是还在教旧版 MessageGraph 而不用 StateGraph + START / END 的,说明版本已经落后,照抄容易报弃用警告。
  4. 写第一个带工具的图只需四个固定积木:MessagesState(存对话)、模型调用节点、ToolNode(跑工具)和 tools_condition(判断继续循环还是结束)。

LangGraph 四个核心概念对照表

图:本站根据 LangGraph 官方文档 Graph API 整理的示意图

本文根据 LangChain / LangGraph 官方文档与 langchain-ai/langgraph 官方 GitHub 仓库整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。

适用于谁

  • 搜「python 安装 langgraph」「langgraph 中文 文档」「langgraph 入门教程」的人;
  • 想摆脱黑盒框架封装,用清晰的图节点与条件边自己控制智能体每一步流转的 Python 开发者;
  • 在网上搜到过时教程(还在用废弃类或跑不通导入语句),需要一份对齐新版 StateGraph 标准写法的最小可运行模板的人。

如果你还不确定项目该选代码级状态图还是选现成引擎,可先对比 /guides/claude-agent-sdk-vs-langchain-how-to-choose 与 /guides/multi-agent-what-is-when-to-use。

一、Python 环境准备与安装命令

建议使用 Python 3.10 及以上版本,并在独立的虚拟环境里安装,避免和全局旧版 langchain 包产生依赖冲突:

bash
mkdir lg-demo && cd lg-demo
python -m venv .venv
# macOS / Linux 激活:
source .venv/bin/activate
# Windows PowerShell 激活:
# .venv\Scripts\Activate.ps1

pip install -U langgraph langchain-core langchain-openai

如果你使用的是 Claude 官方 API Key,把最后一行的 langchain-openai 换成 langchain-anthropic 即可。接着在终端设置好对应的环境变量(例如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY)。

二、动手前先读懂四个核心原语

在敲代码之前,先把 LangGraph 图里的四个角色对上号,后面多复杂的编排(见 /guides/multi-agent-orchestration-patterns)都是这四样东西的排列组合:

  • 状态(State):整张图流转时唯一传递的字典数据结构。对于聊天与工具智能体,官方内置了开箱即用的 MessagesState,里面自带一个配好了 add_messages 追加规则的 messages 列表;
  • 节点(Node):就是一个普通的 Python 函数——输入是当前 State,输出是「这一步新增或修改的字典字段」(而不是整份旧状态);
  • 普通边(add_edge):无条件从节点 A 走到节点 B,例如工具跑完后固定回到大模型节点汇报结果;
  • 条件边(add_conditional_edges):相当于图里的红绿灯。检查大模型上一句回复里有没有发起工具调用(tool_calls),有就拐去工具节点执行,没有就直接走向终点 END。

Python 安装并跑通第一个图四步

图:本站根据 LangGraph 官方 Quickstart 文档 整理的示意图

三、完整代码:从零跑通第一个工具调用图

新建 first_graph.py,粘贴下面这段不到 50 行的标准 Graph API 代码。它定义了一个简单的单位换算工具,并构建「模型思考 → 调工具 → 再思考 → 输出最终答案」的完整闭环:

python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition

# 1. 定义一个带清晰类型注解和文档注释的工具函数
@tool
def convert_celsius_to_fahrenheit(celsius: float) -> float:
    """将摄氏温度换算为华氏温度。"""
    return celsius * 9 / 5 + 32

tools = [convert_celsius_to_fahrenheit]

# 2. 初始化大模型并绑定工具表
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

# 3. 定义大模型推理节点:接收当前消息历史,返回新生成的回复
def chatbot_node(state: MessagesState):
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

# 4. 组装状态图
builder = StateGraph(MessagesState)
builder.add_node("chatbot", chatbot_node)
builder.add_node("tools", ToolNode(tools))

builder.add_edge(START, "chatbot")
# 如果模型发起了工具调用就去 tools 节点,否则跳向 END 结束
builder.add_conditional_edges("chatbot", tools_condition)
builder.add_edge("tools", "chatbot")

# 5. 编译并运行
graph = builder.compile()

if __name__ == "__main__":
    result = graph.invoke({
        "messages": [("user", "今天室温 25 摄氏度,换算成华氏度是多少?")]
    })
    for msg in result["messages"]:
        msg.pretty_print()

运行 python first_graph.py,你会依次看到四条消息轨迹:人类提问 → 模型发出 convert_celsius_to_fahrenheit(celsius=25.0) 工具请求 → ToolNode 算出 77.0 返回 → 模型汇总输出最终中文答复。

四、加三行代码开启多轮对话记忆

上面的 graph.invoke 默认是无状态的——第二次调用 invoke 时它不记得上一句聊了什么。想在本地开启多轮会话记忆,只需引入内置的内存检查点保存器 InMemorySaver 并传入 thread_id:

python
from langgraph.checkpoint.memory import InMemorySaver

memory = InMemorySaver()
graph_with_memory = builder.compile(checkpointer=memory)

config = {"configurable": {"thread_id": "demo-user-1"}}
graph_with_memory.invoke({"messages": [("user", "我叫小周,住在北京")]}, config)
res = graph_with_memory.invoke({"messages": [("user", "刚才说我叫什么?")]}, config)
print(res["messages"][-1].content)

如果团队希望不写 Python 代码、直接通过拖拽画布先验证节点流程,也可以对比无代码工作流工具 /guides/dify-how-to-use-cloud-getting-started;日常借助网页端 ChatGPT 或 Claude 辅助阅读官方英文源码文档时,个人账号订阅说明可参考 /chongzhi/chatgpt-plus。

常见问题

Q:安装时报错找不到 langgraph.prebuilt 或版本冲突怎么办?

多半是因为旧项目环境里残留了很老版本的 langchain-core。新建干净的 .venv 虚拟环境,执行 pip install -U langgraph langchain-core 统一升到最新稳定版即可解决。

Q:什么时候用高层快捷函数、什么时候手写 StateGraph?

如果只是做标准「单模型 + 一组工具」循环,用官方预置封装几行就能跑起来;但一旦你需要在图里插入自定义业务字段(比如记录重试次数、审批状态)或编排多个不同职责的节点,上面这种显式手写 StateGraph 的方式最直观、最好改。

Q:InMemorySaver 能直接用在正式生产环境吗?

不能。内存保存器只活在当前 Python 进程里,服务一重启所有历史对话就清空了。生产上线时应切换到官方提供的持久化检查点包(例如基于 PostgreSQL 或 SQLite 的保存器),节点代码完全不用改,只替换 compile(checkpointer=...) 传入的对象即可。

相关教程

参考资料

  • LangChain / LangGraph 官方文档 — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~