安装与环境配置

把依赖分三层看：编排层 = langgraph（图、State、Checkpointer，不绑定任何模型）；模型适配层 = langchain-openai / langchain-anthropic（把厂商 SDK 包成统一的 chat model 接口）；基础抽象层 = langchain-core（Message、Runnable，被上面两层共享，无需手动声明）。Python 版本要求 3.10 及以上（langgraph 0.3+ 已不再支持 3.9）。

安装核心包

先建一个干净的虚拟环境，再按用到的模型厂商选装适配包。下面命令同时给了 OpenAI 与 Anthropic 两种适配层，实际只需装你要用的那一个。

# 1) 建一个 3.10+ 的独立虚拟环境（LangGraph 不支持 3.9）
python3.11 -m venv .venv-lg
source .venv-lg/bin/activate

# 2) 核心编排包（自动带入 langchain-core）
pip install -U langgraph

# 3) 按厂商选装模型适配层 —— 二选一或都装
pip install -U langchain-openai     # 用 OpenAI 模型时
pip install -U langchain-anthropic  # 用 Anthropic Claude 模型时

# 4) 验证装了哪些版本
pip show langgraph langchain-core langchain-openai 2>/dev/null | grep -E '^(Name|Version)'

配置 API Key 与可选追踪

模型调用的密钥一律走环境变量，LangChain 的 chat model 会自动从约定的变量名里读取。开发期建议放进项目根目录的 .env，再用 python-dotenv 加载；生产环境则由部署平台注入。

# .env —— 放项目根目录，务必加进 .gitignore，绝不提交

# 模型密钥（用哪个厂商就填哪个）
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# 可选：开启 LangSmith 追踪（不需要可整段删掉）
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=langgraph-learning

验证安装：最小可运行 StateGraph

光 import 成功不算装好——要能编译并跑通一张图。下面这段脚本不依赖任何 API key，纯粹用一个普通节点验证 StateGraph 的定义、compile() 与 invoke() 全链路。能打印出预期结果，说明 langgraph 本体正常。

# verify_install.py —— 不需要任何 API key，纯验证 langgraph 安装
from typing import Annotated, TypedDict
from operator import add

from langgraph.graph import StateGraph, START, END


# 1) 定义图的 State：steps 字段用 add 做 reducer，多次写入会拼接
class State(TypedDict):
    value: int
    steps: Annotated[list[str], add]


# 2) 定义两个节点：每个节点接收 state，返回要合并进 state 的增量
def double(state: State) -> dict:
    return {"value": state["value"] * 2, "steps": ["double"]}


def add_ten(state: State) -> dict:
    return {"value": state["value"] + 10, "steps": ["add_ten"]}


# 3) 组装图：节点 + 边，START -> double -> add_ten -> END
builder = StateGraph(State)
builder.add_node("double", double)
builder.add_node("add_ten", add_ten)
builder.add_edge(START, "double")
builder.add_edge("double", "add_ten")
builder.add_edge("add_ten", END)

# 4) 编译成可执行图，再 invoke
graph = builder.compile()
result = graph.invoke({"value": 5, "steps": []})

print(result)
# 预期输出：{'value': 20, 'steps': ['double', 'add_ten']}
# value: 5 * 2 = 10, 10 + 10 = 20；steps 经 reducer 拼接成两步
assert result == {"value": 20, "steps": ["double", "add_ten"]}
print("LangGraph 安装验证通过")

# verify_model.py —— 进一步验证模型适配层与 API key 是否配好（需要真实 key）
import os
from langchain_openai import ChatOpenAI

# ChatOpenAI 不传 api_key，自动读取环境变量 OPENAI_API_KEY
assert os.getenv("OPENAI_API_KEY"), "请先设置 OPENAI_API_KEY 环境变量"

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
resp = llm.invoke("用一句话说明 LangGraph 是做什么的")
print(resp.content)
# 能打印出模型回复，说明适配层 + key 链路全通
# 换 Anthropic 时：from langchain_anthropic import ChatAnthropic
#                  llm = ChatAnthropic(model="claude-sonnet-4-5")

本地可视化调试：langgraph-cli 与 Studio

想在浏览器里可视化看图的执行、单步调试、回放 checkpoint，需要 LangGraph 的本地开发服务器。装带 inmem extra 的 CLI，写一个 langgraph.json 声明你的图，再 langgraph dev 一键起服务并打开 Studio。

# 1) 安装带内存版运行时的 CLI（本地开发够用，无需 Docker）
pip install -U "langgraph-cli[inmem]"

# 2) 启动本地开发服务器（自动打开 LangGraph Studio）
langgraph dev
# 默认监听 http://127.0.0.1:2024
# Studio 入口：https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

{
  "dependencies": ["."],
  "graphs": {
    "my_graph": "./verify_install.py:graph"
  },
  "env": ".env"
}

1. langgraph.json 放在项目根目录，与 verify_install.py 同级。
2. graphs 的值是 文件路径:变量名，这里指向脚本里 compile 出来的 graph 对象。
3. env 指向你的 .env，dev server 启动时会自动加载里面的 key。
4. langgraph dev 起来后改代码会热重载，无需重启即可在 Studio 里重新跑。