文章目录第1章 生产级中断机制深度实践1.1 interrupt 动态断点深入剖析1.1.1 核心原理1.1.2 启用中断的完整流程1.1.3 interrupt() 的使用规范1.2 HITL 人类审批完整工作流1.2.1 审批模式（Approval Pattern）1.2.2 审核与编辑模式（Review-and-Edit Pattern）1.2.3 工具执行审批模式（Tool Approval Pattern）1.2.4 人类输入验证模式（Input Validation Pattern）1.3 多中断并行与串行模式1.3.1 多中断并行（Parallel Interrupts）1.3.2 单节点串行中断（Sequential Interrupts in One Node）1.4 静态断点 interrupt_before / interrupt_after1.4.1 基本用法1.4.2 调用时设置断点（覆盖编译配置）1.4.3 静态断点与动态中断的区别1.5 超步边界与中断执行模型1.5.1 Pregel 超步模型1.5.2 中断在超步中的位置1.5.3 中断前后的检查点变化第2章 工具调用体系生产实践2.1 工具调用循环架构2.1.1 ReAct 式工具调用循环2.1.2 手动实现工具调用循环2.2 ToolNode 预构建节点2.2.1 基本使用2.2.2 ToolNode 的核心特性2.3 ToolRuntime 运行时上下文2.3.1 什么是 ToolRuntime2.3.2 使用 ToolRuntime 访问状态2.3.3 使用 context_schema 注入自定义上下文2.4 工具中更新状态 Command2.4.1 工具返回 Command2.4.2 工具中使用 Command(goto=...) 实现动态路由2.5 wrap_tool_call 容错机制2.5.1 什么是 wrap_tool_call2.5.2 实现重试机制2.5.3 实现缓存机制2.5.4 实现请求日志与审计第3章 流式输出与实时交互3.1 stream / astream 流式 API3.1.1 基本概念3.1.2 输出格式版本3.2 七种 stream_mode 详解3.2.1 values 模式——完整状态快照3.2.2 updates 模式——节点增量输出3.2.3 messages 模式——Token 级流式输出3.2.4 checkpoints 模式——检查点事件3.2.5 tasks 模式——任务生命周期事件3.2.6 debug 模式——全量调试信息3.2.7 custom 模式——自定义事件3.2.8 多模式同时启用3.3 stream_writer 自定义流3.3.1 基本用法3.3.2 工具中使用 stream_writer3.4 astream_events v1 / v2 / v33.4.1 Runnable 事件体系3.4.2 v1 与 v2 的区别3.4.3 v3——Pregel 原始流投影3.4.4 实战：构建终端聊天界面第4章 本地部署与工程化4.1 langgraph-cli 本地部署4.1.1 安装4.1.2 Windows 编码问题4.1.3 项目结构4.2 langgraph.json 配置详解4.2.1 完整配置示例4.2.2 各字段详解4.2.3 源码文件示例4.3 LangSmith 对接与追踪4.3.1 环境变量配置4.3.2 启动本地开发服务4.3.3 LangSmith Studio 调试4.3.4 LangSmith Tracing 追踪4.4 AgentChatUI 前端对接4.4.1 AgentChatUI 简介4.4.2 对接步骤4.4.3 支持 HITL 交互4.4.4 自托管 AgentChatUI第5章 子图架构与状态管理5.1 子图两种嵌入方式5.1.1 方式一：节点函数中调用子图5.1.2 方式二：子图直接作为父图节点5.2 子图持久化与命名空间5.2.1 检查点命名空间5.2.2 子图持久化策略5.3 子图状态共享机制5.3.1 状态字段的可见性5.3.2 子图间状态共享实战：多专家协作5.3.3 子图流式输出第6章 六大设计模式6.1 Prompt Chaining：提示词链6.1.1 核心思想6.1.2 生产级示例：内容创作管线6.2 Parallelization：并行化6.2.1 核心思想6.2.2 生产级示例：多角度内容审核6.3 Routing：路由6.3.1 核心思想6.3.2 生产级示例：智能客服路由6.4 Orchestrator-Worker：编排者-工作者6.4.1 核心思想6.4.2 生产级示例：动态文档分析6.5 Evaluator-Optimizer：评估-优化6.5.1 核心思想6.5.2 生产级示例：代码生成与优化循环6.6 Agent ReAct：智能体循环6.6.1 核心思想6.6.2 生产级示例：多工具 ReAct Agent第7章 生产最佳实践7.1 状态设计最佳实践7.1.1 状态建模原则7.1.2 状态变更原则7.2 错误处理与重试策略7.2.1 多层防御策略7.2.2 LLM 结构化输出重试7.2.3 防止无限循环7.3 性能优化策略7.3.1 并行执行7.3.2 模型调用优化7.3.3 检查点性能7.4 调试技巧与工具7.4.1 使用 LangSmith Studio7.4.2 使用 stream_mode=["debug"] 进行本地调试7.4.3 使用 get_state 和 get_state_history7.4.4 日志最佳实践7.4.5 Mermaid 可视化7.5 安全与权限控制7.5.1 工具权限分级7.5.2 敏感信息保护7.5.3 输入验证与注入防护7.6 监控与可观测性7.6.1 关键指标7.6.2 自定义元数据追踪7.6.3 健康检查端点附录：快速参考常用导入速查stream_mode 速查表常见问题排查生产部署 Checklist第1章 生产级中断机制深度实践中断（Interrupt）是 LangGraph 实现人机协同（Human-in-the-Loop, HITL）的核心机制。在生产环境中，中断不仅用于简单的暂停-恢复，更承担着审批流、人工审核、多级确认等关键业务职责。本章将从底层机制出发，系统讲解动态中断、静态断点以及二者在超步边界上的执行模型。1.1 interrupt 动态断点深入剖析1.1.1 核心原理interrupt()是 LangGraph 提供的动态中断函数，它可以在任意节点的任意位置调用，根据业务逻辑条件触发暂停。其底层机制是抛出一个特殊的GraphInterrupt异常，该异常被 Pregel 运行时捕获后，将当前完整状态序列化保存到检查点存储器中，然后将控制权交还给调用方。动态中断的三要素：检查点存储器（Checkpointer）：必须配置，用于保存中断时的完整状态快照，是恢复执行的基础。线程标识（thread_id）：通过config["configurable"]["thread_id"]指定，用于标识一次独立的对话/任务会话。同一 thread_id 下的多次调用共享状态历史。Command 恢复对象：恢复执行时，必须传入Command(r
文章目录第1章 生产级中断机制深度实践1.1 interrupt 动态断点深入剖析1.1.1 核心原理1.1.2 启用中断的完整流程1.1.3 interrupt() 的使用规范1.2 HITL 人类审批完整工作流1.2.1 审批模式（Approval Pattern）1.2.2 审核与编辑模式（Review-and-Edit Pattern）1.2.3 工具执行审批模式（Tool Approval Pattern）1.2.4 人类输入验证模式（Input Validation Pattern）1.3 多中断并行与串行模式1.3.1 多中断并行（Parallel Interrupts）1.3.2 单节点串行中断（Sequential Interrupts in One Node）1.4 静态断点 interrupt_before / interrupt_after1.4.1 基本用法1.4.2 调用时设置断点（覆盖编译配置）1.4.3 静态断点与动态中断的区别1.5 超步边界与中断执行模型1.5.1 Pregel 超步模型1.5.2 中断在超步中的位置1.5.3 中断前后的检查点变化第2章 工具调用体系生产实践2.1 工具调用循环架构2.1.1 ReAct 式工具调用循环2.1.2 手动实现工具调用循环2.2 ToolNode 预构建节点2.2.1 基本使用2.2.2 ToolNode 的核心特性2.3 ToolRuntime 运行时上下文2.3.1 什么是 ToolRuntime2.3.2 使用 ToolRuntime 访问状态2.3.3 使用 context_schema 注入自定义上下文2.4 工具中更新状态 Command2.4.1 工具返回 Command2.4.2 工具中使用 Command(goto=...) 实现动态路由2.5 wrap_tool_call 容错机制2.5.1 什么是 wrap_tool_call2.5.2 实现重试机制2.5.3 实现缓存机制2.5.4 实现请求日志与审计第3章 流式输出与实时交互3.1 stream / astream 流式 API3.1.1 基本概念3.1.2 输出格式版本3.2 七种 stream_mode 详解3.2.1 values 模式——完整状态快照3.2.2 updates 模式——节点增量输出3.2.3 messages 模式——Token 级流式输出3.2.4 checkpoints 模式——检查点事件3.2.5 tasks 模式——任务生命周期事件3.2.6 debug 模式——全量调试信息3.2.7 custom 模式——自定义事件3.2.8 多模式同时启用3.3 stream_writer 自定义流3.3.1 基本用法3.3.2 工具中使用 stream_writer3.4 astream_events v1 / v2 / v33.4.1 Runnable 事件体系3.4.2 v1 与 v2 的区别3.4.3 v3——Pregel 原始流投影3.4.4 实战：构建终端聊天界面第4章 本地部署与工程化4.1 langgraph-cli 本地部署4.1.1 安装4.1.2 Windows 编码问题4.1.3 项目结构4.2 langgraph.json 配置详解4.2.1 完整配置示例4.2.2 各字段详解4.2.3 源码文件示例4.3 LangSmith 对接与追踪4.3.1 环境变量配置4.3.2 启动本地开发服务4.3.3 LangSmith Studio 调试4.3.4 LangSmith Tracing 追踪4.4 AgentChatUI 前端对接4.4.1 AgentChatUI 简介4.4.2 对接步骤4.4.3 支持 HITL 交互4.4.4 自托管 AgentChatUI第5章 子图架构与状态管理5.1 子图两种嵌入方式5.1.1 方式一：节点函数中调用子图5.1.2 方式二：子图直接作为父图节点5.2 子图持久化与命名空间5.2.1 检查点命名空间5.2.2 子图持久化策略5.3 子图状态共享机制5.3.1 状态字段的可见性5.3.2 子图间状态共享实战：多专家协作5.3.3 子图流式输出第6章 六大设计模式6.1 Prompt Chaining：提示词链6.1.1 核心思想6.1.2 生产级示例：内容创作管线6.2 Parallelization：并行化6.2.1 核心思想6.2.2 生产级示例：多角度内容审核6.3 Routing：路由6.3.1 核心思想6.3.2 生产级示例：智能客服路由6.4 Orchestrator-Worker：编排者-工作者6.4.1 核心思想6.4.2 生产级示例：动态文档分析6.5 Evaluator-Optimizer：评估-优化6.5.1 核心思想6.5.2 生产级示例：代码生成与优化循环6.6 Agent ReAct：智能体循环6.6.1 核心思想6.6.2 生产级示例：多工具 ReAct Agent第7章 生产最佳实践7.1 状态设计最佳实践7.1.1 状态建模原则7.1.2 状态变更原则7.2 错误处理与重试策略7.2.1 多层防御策略7.2.2 LLM 结构化输出重试7.2.3 防止无限循环7.3 性能优化策略7.3.1 并行执行7.3.2 模型调用优化7.3.3 检查点性能7.4 调试技巧与工具7.4.1 使用 LangSmith Studio7.4.2 使用 stream_mode=["debug"] 进行本地调试7.4.3 使用 get_state 和 get_state_history7.4.4 日志最佳实践7.4.5 Mermaid 可视化7.5 安全与权限控制7.5.1 工具权限分级7.5.2 敏感信息保护7.5.3 输入验证与注入防护7.6 监控与可观测性7.6.1 关键指标7.6.2 自定义元数据追踪7.6.3 健康检查端点附录：快速参考常用导入速查stream_mode 速查表常见问题排查生产部署 Checklist第1章 生产级中断机制深度实践中断（Interrupt）是 LangGraph 实现人机协同（Human-in-the-Loop, HITL）的核心机制。在生产环境中，中断不仅用于简单的暂停-恢复，更承担着审批流、人工审核、多级确认等关键业务职责。本章将从底层机制出发，系统讲解动态中断、静态断点以及二者在超步边界上的执行模型。1.1 interrupt 动态断点深入剖析1.1.1 核心原理interrupt()是 LangGraph 提供的动态中断函数，它可以在任意节点的任意位置调用，根据业务逻辑条件触发暂停。其底层机制是抛出一个特殊的GraphInterrupt异常，该异常被 Pregel 运行时捕获后，将当前完整状态序列化保存到检查点存储器中，然后将控制权交还给调用方。动态中断的三要素：检查点存储器（Checkpointer）：必须配置，用于保存中断时的完整状态快照，是恢复执行的基础。线程标识（thread_id）：通过config["configurable"]["thread_id"]指定，用于标识一次独立的对话/任务会话。同一 thread_id 下的多次调用共享状态历史。Command 恢复对象：恢复执行时，必须传入Command(r
)
