langgraph

LangGraph

LangGraph 是 LangChain 的底层编排框架，用于通过有向图架构构建有状态、长时间运行的多 Agent AI 工作流（灵感来自 Pregel/Beam 和 NetworkX）。它将 Agent 建模为图中的节点，通过边控制流程，从而支持循环、条件分支、并行执行、人机协同以及子图组合，而这些都是线性链无法实现的。

本技能涵盖构建和部署 LangGraph 系统的所有主要模式：核心图架构、三种典型的多 Agent 模式（监督者、群组、分层）、持久化与状态管理、生产环境调试以及评估方法。

开始之前： 安装依赖：

pip install langgraph langchain langchain-openai langsmith

快速入门

用不到 10 行代码创建你的第一个 LangGraph Agent：

from langgraph.graph import StateGraph, MessagesState, START, END

def hello_agent(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "Hello, world!"}]}

graph = StateGraph(MessagesState)
graph.add_node("agent", hello_agent)
graph.add_edge(START, "agent")
graph.add_edge("agent", END)
graph = graph.compile()

graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})

后续步骤：

1. 使用下方的模式选择指南，选择监督者、群组或分层架构——每种模式都链接到推荐模板
2. 加载相应的参考文件，深入了解该模式
3. 使用下方的选择起点表格，根据任务选择脚手架、模板或参考资料
4. 如需与你的模式匹配的完整可运行示例，请使用 assets/templates/ 中链接的模板

设计原则——所有图决策都必须遵循

1. 状态是真实数据的唯一来源——节点间的所有通信都通过状态进行，而不是通过旁路或全局变量。
2. 节点应尽可能保持纯粹——节点接收状态、执行工作并返回更新。它不应依赖未传入的状态。
3. Reducer 可防止冲突——多个并行节点会写入的任何状态键都必须有 Reducer。
4. 从简单开始——带有优质提示词的单个 Agent，胜过路由不佳的多 Agent 系统。只有当单个提示词或工具集变得难以管理时，才添加 Agent。
5. 使用 Send() 实现动态扇出——如果在编译时无法确定所需工作节点的数量，就从编排器节点动态生成这些节点。
6. 隔离子图状态——状态架构不同的子图需要使用包装函数在边界处转换状态。共享架构的子图可直接作为节点添加。

何时使用

场景	加载内容
从头构建新的 LangGraph 工作流	references/architecture.md — 先了解核心概念
设计多 Agent 路由系统	references/multi-agent-supervisor.md 或 references/multi-agent-swarm.md — 比较不同模式
组合嵌套 Agent 团队	references/multi-agent-hierarchical.md — 子图组合
添加持久化、中断或长期记忆	references/persistence.md — 检查点保存器和存储
部署到生产环境或调试故障	references/production.md — 部署、可观测性、故障模式
设置用于路由准确率的评估流水线	references/evals.md — 评估方法
诊断特定故障（循环、上下文丢失、崩溃）	references/troubleshooting.md — 已知故障模式
在图中放置有类型的 System One 判断	references/architecture.md；决策约定和校准参见 System One，工作流权限和完整任务证据参见 harness-engineering

模式选择指南

你的约束	优先选择	原因
路由准确性优先于延迟	Supervisor	集中式路由节点，专注的提示词：准确率约为 94%
延迟是首要约束	Swarm	Agent 之间直接交接，LLM 调用次数减少约 40%
领域边界清晰	Swarm	Agent 很少错误路由，交接明确
领域边界模糊	Supervisor	由专用路由器解决关注点重叠问题
不足 3 个不同领域	跳过多 Agent 模式	专业化的单个 Agent 更简单
经常收到跨领域请求	Swarm	延迟节省会随着交接次数累积
需要集中式审计记录	Supervisor	路由决策都会显示在追踪记录中
嵌套团队结构	Hierarchical	将子图作为节点，每个团队自成一体

选择起点

你的目标	从这里开始	原因
从零开始构建项目，需要生成代码	scripts/lg-supervisor-scaffold.py 或 scripts/lg-swarm-scaffold.py	脚手架会生成完整的项目结构（state.py、agents.py、graph.py），并提供待填写的占位内容
了解完整、可运行的示例	assets/templates/ 中与你选择的模式匹配的模板	模板是自包含的可运行文件，已连接好所有模式——最适合通过阅读来学习
深入了解某种模式的内部机制	references/ 中对应的参考文档	参考文档会解释权衡、故障模式和设计原理——最适合用于定制
调试或优化现有系统	references/production.md 或 references/troubleshooting.md	生产环境参考文档涵盖部署和可观测性；故障排查参考文档包含症状→修复对照表

核心原语

LangGraph 使用两种 API：

API	适用场景	模式
Graph API（StateGraph）	完全控制图结构、条件边和子图	add_node() + add_edge()/add_conditional_edges()
Functional API（@task + @entrypoint）	更简单的线性工作流、更少的样板代码	基于装饰器，符合 Python 风格

两种 API 都会生成相同的编译后图——根据所需的控制程度进行选择。

重要注意事项

• 子图持久化默认按调用进行——每次调用子图都会从头开始。设置 checkpointer=True 可启用按线程记忆，设置 checkpointer=False 则完全无状态。
• 按线程运行的子图不能并行执行——同一命名空间的检查点会发生冲突。使用 ToolCallLimitMiddleware 或禁用并行工具调用。
• Supervisor 瓶颈——每次交互都需要调用一次路由 LLM，即使意图显而易见也不例外。对于明确的请求，可添加快速路径分类器（关键字匹配或小型模型）。
• Swarm 来回循环——没有自然的递归保护机制。在状态中跟踪 handoff_count 并将上限设为 3，然后升级给人工处理或转交给备用 Agent。
• 交接时消息丢失——Command.update 必须包含专家 Agent 工具调用循环中的成对消息，否则下一个 Agent 看到的历史记录会格式错误。
• 从父图访问子图状态——子图会管理自己的检查点命名空间。跨图边界共享数据时请使用 Store。
• 检查点膨胀——长对话会累积检查点。定期清理，或为基于 DB 的检查点保存器设置保留策略。
• 安装后不会自动加载——技能不会在会话开始时根据名称提及而自动发现。Agent 必须显式调用 skill_view(name='langgraph') 来加载此技能。

参考文件

文件	加载时机
references/architecture.md	需要了解 LangGraph 核心概念时：图结构、节点、边、状态、两种 API 以及 Agent 循环的基本构建方式。如果你是 LangGraph 新手，请先阅读此文件。
references/multi-agent-supervisor.md	设计基于 supervisor、带有中央路由节点的多 Agent 系统时。包含架构、结构化输出路由、专用 Agent 包装器和完整代码示例。
references/multi-agent-swarm.md	设计基于 swarm、支持 Agent 之间直接交接的多 Agent 系统时。包含交接工具模式、基于 Command 的路由，以及与 supervisor 的对比指标。
references/multi-agent-hierarchical.md	使用子图组合嵌套 Agent 团队时。涵盖子图连接方式（共享或不同的状态模式）、持久化模式、命名空间隔离和分层团队结构。
references/persistence.md	添加基于 checkpointer 的短期记忆或基于 store 的长期记忆时。涵盖按调用、按线程和无状态模式、检查点后端，以及跨线程记忆模式。
references/production.md	将 LangGraph 系统部署到生产环境时。涵盖 Agent Server 部署、LangSmith 可观测性、流式处理模式，以及常见的生产故障和修复方法。
references/evals.md	为多 Agent 系统设置评估流水线时。涵盖路由准确率、问题解决覆盖率、LangSmith 评估数据集和 LLM-as-judge 评估器。
references/troubleshooting.md	调试特定的 LangGraph 故障时。涵盖路由循环、上下文丢失、checkpointer 冲突、令牌浪费和状态检查技巧。
assets/templates/supervisor-graph.py	可运行的 supervisor 示例，包含账单、技术支持和账户专员；提供快速路径分类器、结构化输出路由、审计跟踪和递归保护。
assets/templates/swarm-graph.py	可运行的 swarm 示例，包含分诊 Agent 和 3 个专员；支持通过 Command 在 Agent 之间直接交接，并提供递归保护和完整的可追溯性。
assets/templates/subgraph-agent.py	可运行的子图组合示例，包含全部 3 种连接模式（不同的状态模式、共享状态键、带命名空间隔离的按线程模式）。

脚本

脚本	功能
scripts/lg-supervisor-scaffold.py	生成完整的 supervisor 模式项目，包含状态模式、路由 Agent、专员节点和图组装代码
scripts/lg-swarm-scaffold.py	生成完整的 swarm 模式项目，包含交接工具、分诊 Agent、专员 Agent 和条件路由
scripts/lg-eval-generator.py	生成评估数据集，并运行 LangSmith 评估器来评估路由准确率和问题解决覆盖率