LangGraph 01：生态与环境

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

前言

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

概要

本文先对比 create_agent 与直接写 StateGraph 的分工。
再给出用 uv 初始化工程、安装 langgraph 等依赖的步骤。
接着配置 Coding Plan 的环境变量，并跑通一个不调 LLM 的最小图。
最后补充图的 ASCII 与 Mermaid 可视化，以及本系列后续篇目从哪里接。

依赖

在空目录初始化工程并声明依赖。
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())

可视化

编译后可通过 get_graph() 导出结构，便于对照边是否连对。

1
2
3
4
5
# ASCII（终端可读）
graph.get_graph().print_ascii()

# Mermaid 文本（可粘贴到支持 Mermaid 的编辑器）
print(graph.get_graph().draw_mermaid())

Notebook 里还可用 draw_mermaid_png() 生成图片；脚本环境有时依赖额外渲染包，失败时用 Mermaid 文本即可。

直接查看图

1
2
3
from IPython.display import display

display(graph)

系列路线

完整分工与跳读建议见 《LangGraph 00：系列概要》。
本篇只负责环境与最小图；下一篇进入状态定义与 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。