LangGraph 01：生态与环境

发表于 更新于 分类于
厘清 LangGraph 与 LangChain create_agent 的分工，用 uv 搭建环境并对接 Coding Plan，跑通最小 StateGraph。

前言

用 LangChain 搭 Agent 时，常见入口是 create_agent：模型、工具、中间件一条龙，适合标准「模型 + 工具」循环。
一旦编排变成多分支、并行、人工审批、可恢复长任务，就需要直接操作 状态图运行时，这正是 LangGraph 的定位。
本文只做系列起点：对比两者、用 uv 装好依赖、配置火山方舟 Coding Plan，并跑通一个不调 LLM 的最小 StateGraph。
下文需要 Python 3.12+；模型示例对接 Coding Plan，便于与 LangChain 系列共用同一套 .env。

依赖

在空目录初始化工程并声明依赖。
langgraph 负责图编排；langchain-openai / python-dotenv 供后续接模型；rich 用于更清晰地打印结构化结果。

1
2
3
uv init
uv venv --python 3.12
uv add langgraph langchain-openai python-dotenv rich

后续示例用 uv run python xxx.py 执行即可，一般不必手动激活虚拟环境。
打印时推荐 from rich import print as rprint，嵌套 dict / 消息列表会比内置 print 更易读。

在项目根目录创建 .env（勿提交到 Git），写入 Coding Plan 的 Key 与专用 Base URL。

1
2
OPENAI_API_KEY=你的火山方舟 API Key
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/coding/v3

请勿写成普通方舟 .../api/v3，否则无法抵扣 Coding Plan 额度，还可能产生额外费用。
模型名下文统一用 ark-code-latest；也可用 ChatOpenAI 或 init_chat_model("openai:ark-code-latest", ...)。

实现

与 create_agent

可以这样理解分层：

  1. LangGraph：Agent Runtime，用 StateGraph 定义节点、边、状态合并与检查点，完全掌控执行路径。
  2. LangChain create_agent：在 LangGraph 之上封装常见 Agent 循环，少写图也能用到持久化、流式等能力。

只做单轮工具调用时，优先 create_agent。
需要自定义状态机、并行分支、条件路由、HITL 时，直接学 LangGraph 更划算。
本系列从手写图开始，再逐步接到消息、路由、检查点与工具节点。

最小 StateGraph

下面脚本定义 TypedDict 状态、一个节点，以及 START → hello → END。
节点只返回要更新的字段；未声明 reducer 的字段按「覆盖」合并。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from typing import TypedDict

from langgraph.graph import END, START, StateGraph
from rich import print as rprint


class State(TypedDict):
    name: str
    greeting: str


def hello(state: State) -> dict:
    return {"greeting": f"你好，{state['name']}！"}


builder = StateGraph(State)
builder.add_node("hello", hello)
builder.add_edge(START, "hello")
builder.add_edge("hello", END)

graph = builder.compile()
result = graph.invoke({"name": "LangGraph"})
rprint(result)

期望输出类似 {'name': 'LangGraph', 'greeting': '你好，LangGraph！'}。
compile() 得到可调用的图；invoke 传入初始状态字典，返回合并后的最终状态。

可选地打印 ASCII 或 Mermaid，方便核对拓扑（无需 LLM）。

1
2
graph.get_graph().print_ascii()
print(graph.get_graph().draw_mermaid())

系列路线

本系列共规划 13 篇，由浅入深覆盖官方图 API 与常见工作流。

  1. 《LangGraph 01：生态与环境》：定位、环境与最小图（本文）。
  2. 《LangGraph 02：StateGraph 基础》：TypedDict / dataclass / Pydantic、Annotated 与自定义 reducer。
  3. 《LangGraph 03：消息与多 Schema》：add_messages、Overwrite、输入输出 Schema 与 MessagesState。
  4. 《LangGraph 04：边与条件路由》：普通边、并行扇出、条件边、path_map 与 defer 汇合。
  5. 《LangGraph 05：Command 与动态扇出》：Command、Send 等动态路由能力。
  6. 《LangGraph 06：Map-Reduce 与循环》：扇入扇出、静态循环与 goto。
  7. 《LangGraph 07：重试缓存与步数》：Retry、Cache、remaining steps 与结束循环。
  8. 《LangGraph 08：Checkpointer 持久化》：内存 / SQL 检查点与按 thread_id 续跑。
  9. 《LangGraph 09：历史回放与分叉》：状态历史、错误定位、replay 与 fork。
  10. 《LangGraph 10：Store 与 Context》：跨线程存储与运行时上下文。
  11. 《LangGraph 11：人工审批 HITL》：中断、审批与检查点配合。
  12. 《LangGraph 12：ToolNode 与工具》：工具调用节点、并行与包装。
  13. 《LangGraph 13：流式子图与模式》：流式输出、子图，以及路由 / 编排等典型模式。

下一篇直接进入状态定义与 reducer：请看 《LangGraph 02：StateGraph 基础》。

验证

在项目根目录执行上面的最小脚本。

1
uv run python hello_graph.py

若 rprint 打出含 greeting 的字典，且 Mermaid / ASCII 中能看到 hello 节点，说明环境与最小图已就绪。
后续接 LLM 的文章会复用同一套 .env 与 Coding Plan 配置。

总结

  1. LangGraph 管「怎么跑图」；create_agent 管「快速拼标准 Agent」。
  2. 用 uv 安装 langgraph 等依赖，Coding Plan 走 OPENAI_* 变量与 ark-code-latest。
  3. 最小闭环：定义 State → 写节点 → add_edge → compile → invoke。