关于 langgraph-fundamentals
面向 LangGraph 开发者的工作流设计、实现与调试指南，涵盖有状态编排、分支、循环、流式处理和持久化。
主要功能
- 01StateGraph 设计与编译
- 02状态与归约器指南
- 03静态及条件路由
- 04Command 与 Send 模式
- 05调用与流式输出模式
- 06错误处理策略
适用场景
- 01规划带分支的 Agent 工作流
- 02管理累积的图状态
- 03向 UI 流式传递图进度
- 04处理暂时性及需用户修复的错误
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/langgraph-fundamentals确认已加载。
附带文件references/python.mdreferences/typescript.md
详细介绍
- StateGraph：用于构建有状态图的主类
- 节点：执行工作并更新状态的函数
- 边：定义执行顺序（静态或条件式）
- START/END：标记入口点和出口点的特殊节点
- 带 Reducer 的状态：控制状态更新的合并方式
执行图之前，必须先调用 compile()。
设计 LangGraph 应用
构建新图时，遵循以下 5 个步骤：
- 梳理离散步骤 — 绘制工作流流程图。每个步骤都对应一个节点。
- 确定每个步骤的作用 — 对节点进行分类：大模型步骤、数据步骤、操作步骤或用户输入步骤。对于每个步骤，确定静态上下文（提示词）、动态上下文（来自状态）、重试策略和期望结果。
- 设计状态 — 状态是所有节点共享的内存。存储原始数据，并在节点内部按需格式化提示词。
- 构建节点 — 将每个步骤实现为一个接收状态并返回部分更新的函数。
- 连接各部分 — 使用边连接节点，添加条件路由，并在需要时通过 checkpointer 编译。
| 适用 LangGraph 的场景 | 适用替代方案的场景 |
|---|---|
| 需要对 Agent 编排进行细粒度控制 | 快速原型开发 → LangChain agents |
| 构建包含分支或循环的复杂工作流 | 简单的无状态工作流 → LangChain direct |
| 需要人机协作、持久化 | 需要开箱即用的功能 → Deep Agents |
状态管理
| 需求 | 解决方案 | 示例 |
|---|---|---|
| 覆盖值 | 不使用 reducer（默认） | 计数器等简单字段 |
| 追加到列表 | Reducer（operator.add / concat） | 消息历史、日志 |
| 自定义逻辑 | 自定义 reducer 函数 | 复杂合并 |
节点
节点函数返回部分状态更新。配置和运行时访问的函数签名因语言而异；请参考适用的实现指南。
边
| 需求 | 边类型 | 适用场景 |
|---|---|---|
| 始终前往同一节点 | add_edge() | 固定、确定性流程 |
| 根据状态路由 | add_conditional_edges() | 动态分支 |
| 更新状态并进行路由 | Command | 在单个节点中组合逻辑 |
| 扇出至多个节点 | Send | 使用动态输入进行并行处理 |
Command
Command 在单个返回值中组合状态更新和路由。字段：
update：要应用的状态更新（类似于从节点返回一个 dict）goto：要导航到的下一个节点名称resume：在interrupt()之后用于恢复执行的值 — 参见 human-in-the-loop skill
Python：使用 Command[Literal["node_a", "node_b"]] 作为返回类型注解，声明有效的 goto 目标。
TypeScript：将 { ends: ["node_a", "node_b"] } 作为第三个参数传递给 addNode，以声明有效的 goto 目标。
警告：Command 只会添加动态边 — 使用 add_edge / addEdge 定义的静态边仍会执行。如果 node_a 返回 Command(goto="node_c")，且你还添加了 graph.add_edge("node_a", "node_b")，则 node_b 和 node_c 都会运行。
Send API
使用 Send 扇出：从条件边返回 [Send("worker", {...})]，以启动并行工作节点。结果字段需要配置 reducer。
运行图：调用与流式传输
调用 graph.invoke(input, config) 可运行图直至完成，并返回最终状态。
| 模式 | 流式传输的内容 | 使用场景 |
|---|---|---|
values | 每一步之后的完整状态 | 监控完整状态 |
updates | 状态增量 | 跟踪增量更新 |
messages | LLM 令牌和元数据 | 聊天 UI |
custom | 用户定义的数据 | 进度指示器 |
错误处理
根据错误类型选择合适的处理程序：
| 错误类型 | 修复者 | 策略 | 示例 |
|---|---|---|---|
| 暂时性（网络、速率限制） | 系统 | RetryPolicy(max_attempts=3) | add_node(..., retry_policy=...) |
| LLM 可恢复（工具故障） | LLM | ToolNode(tools, handle_tool_errors=True) | 错误作为 ToolMessage 返回 |
| 用户可修复（信息缺失） | 人工 | interrupt({"message": ...}) | 收集缺失数据（参见 HITL skill） |
| 意外错误 | 开发者 | 让错误向上冒泡 | raise |
核心约束
- 从节点返回部分状态更新，而不是直接修改状态。
- 通过命名节点路由循环；
START仅用于入口。 - 为累积列表字段定义 reducer；否则，最后一次写入会覆盖之前的值。
- 使用
Command和goto时，考虑静态边，因为两条路由都会执行。
实现参考
编写、修改或调试 LangGraph 代码时，先根据项目现有文件确定项目使用的语言，再阅读适用的参考文档，然后再进行实现：
- 对于 Python，请阅读 references/python.md。
- 对于 TypeScript，请阅读 references/typescript.md。
仅当任务涉及两种语言时才阅读两份文档。对于无需编写代码的概念性问题，不要加载任何一份参考文档。