Skip to main content

thinkInLangGraph

这篇文档通过构建一个客服邮件 Agent 的完整案例，系统阐述了用 LangGraph 构建 Agent 的思维方法。

心智模型​

LangGraph 的核心理念是将复杂的 Agent 工作流分解为一系列独立的节点（执行具体任务），并通过共享的状态（State）在节点间传递信息。节点通过返回 Command 对象显式声明路由逻辑，形成清晰、可追溯的执行路径。

核心步骤与关键内容​

文档以五个步骤展开构建过程：

1. 映射工作流为离散步骤 首先将业务流程（如处理客服邮件）分解为功能单一的节点，如读取邮件、分类意图、搜索文档、草拟回复等。明确每个节点的功能及它们之间可能的路径。

2. 明确每个步骤的职责 将每个节点归类为四种类型，明确其所需上下文和预期结果：

  • LLM 步骤：用于理解、分析、生成文本或进行推理决策（如分类意图、草拟回复）。
  • 数据步骤：用于从外部检索信息（如搜索文档、查询客户历史）。
  • 动作步骤：用于执行外部操作（如发送回复、创建Bug工单）。
  • 用户输入步骤：用于需要人工干预的场景（如人工复核）。

3. 设计状态 状态是节点间共享的“笔记本”。关键原则是状态中应存储原始数据，而非格式化文本。这允许不同节点按需格式化数据，便于调试、修改提示词和扩展Agent。

4. 构建节点 将每个步骤实现为Python函数。关键点是节点需要处理不同类型的错误：

  • 瞬时错误：如网络问题，使用 RetryPolicy 自动重试。
  • LLM可恢复错误：将错误存入状态并循环回LLM，让其自行调整。
  • 用户可修复错误：使用 interrupt() 暂停执行，等待用户输入。
  • 重试耗尽后的可恢复错误：使用 error_handler 运行补偿分支。
  • 意外错误：直接让异常抛出，以便调试。

5. 组合成图 将所有节点添加到 StateGraph 中，仅添加必要的边（如 START 和 END）。路由逻辑已在节点内部通过返回 Command 对象处理，使图结构保持简洁，控制流显式且可追溯。

最佳实践​

  • 节点功能单一：每个节点只做一件事，有利于调试、流式更新和持久化执行。
  • 状态存储原始数据：不在状态中存储格式化文本或提示词模板，保持数据纯净，让节点按需格式化。
  • 显式路由：节点通过返回 Command 对象决定下一步，而非在边中用复杂的条件逻辑。
  • 错误分类处理：根据不同错误类型（瞬时、可恢复、需要人工、未知）采用对应的处理策略。
  • interrupt() 前置：在节点中使用 interrupt() 时，该调用必须放在函数内部所有其他代码之前，以防恢复执行时重复逻辑。
  • 合理划分节点粒度：节点过大会导致出错时重做更多工作；节点过细则可能增加复杂度。需在可观测性和弹性之间权衡。这实质上也是上下文工程的实践——精确控制每个节点能看到和产出什么信息。