Skip to main content

Documentation Index

Fetch the complete documentation index at: https://langchain.idochub.dev/llms.txt

Use this file to discover all available pages before exploring further.

您提供的文档是 LangGraph 框架的 Graph API 概述，详细介绍了如何使用图（Graph）来建模和构建智能体（Agent）工作流。 以下是该文档的核心内容总结：

​
核心概念：图 (Graphs)

LangGraph 的核心是将智能体工作流建模为图，由三个关键组件构成：
  1. State (状态): 一个共享的数据结构，代表应用的当前快照。通常是 TypedDict (Python) 或 Zod Schema (JS)。
  2. Nodes (节点): 执行具体逻辑的函数。接收当前 State，进行计算或产生副作用，并返回更新后的 State。
  3. Edges (边): 决定下一步执行哪个 Node 的函数。可以是条件分支或固定跳转。
  • 核心原则: 节点做工作 (Nodes do the work)，边决定下一步做什么 (Edges tell what to do next)。
  • 底层机制: 基于消息传递（Message Passing）和类似 Google Pregel 的“超步”（Super-step）概念。节点在接收到消息（状态）时变为活跃，执行后发送消息给下游节点，直到所有节点都变为不活跃且无消息在传输时，图执行终止。

​
State (状态)

  • 定义: 包含图的模式 (Schema) 和归约器 (Reducers)。
  • 模式 (Schema):
    • Python: 推荐 TypedDict，需要默认值用 dataclass，需要递归验证用 Pydantic BaseModel。
    • JS: 推荐 Zod Schema 或 Annotation API。
    • 支持定义不同的输入/输出模式 (input_schema, output_schema) 和内部私有模式 (PrivateState)，实现更精细的控制。
  • 归约器 (Reducers):
    • 定义如何将节点的更新应用到 State 的各个键上。
    • 默认归约器: 直接覆盖该键的值。
    • 自定义归约器: 例如，使用 operator.add (Python) 或自定义函数 (JS) 来合并列表。这对于处理消息历史 (Messages) 非常重要。
    • 消息处理: 提供了 add_messages (Python) / MessagesZodMeta (JS) 预构建归约器，能智能地追加新消息或根据 ID 更新现有消息，并支持消息的序列化/反序列化。还提供了便捷的 MessagesState 类。

​
Nodes (节点)

  • 定义: 是函数（同步或异步），接收 state、config（配置，如 thread_id）和可选的 runtime（运行时上下文）。
  • 添加: 使用 add_node (Python) / addNode (JS) 方法。
  • 特殊节点:
    • START: 代表用户输入进入图的虚拟节点。
    • END: 代表图执行终止的虚拟节点。
  • 缓存: 支持基于节点输入的缓存，通过 cache_policy 和 compile(cache=...) 设置。
  • Command: 节点可以返回 Command 对象，同时进行状态更新 (update) 和控制流跳转 (goto)，是实现复杂逻辑（如多智能体交接、人机交互恢复）的关键。

​
Edges (边)

  • 类型:
    • 普通边 (add_edge / addEdge): 从一个节点固定跳转到另一个节点。
    • 条件边 (add_conditional_edges / addConditionalEdges): 通过一个路由函数决定下一步跳转到哪个（或哪些）节点。可以返回节点名或使用映射字典。
    • 入口点 (add_edge(START, ...) / addEdge(START, ...)): 定义图的起始节点。
    • 条件入口点 (add_conditional_edges(START, ...) / addConditionalEdges(START, ...)): 根据条件决定从哪个节点开始。
  • 并行执行: 一个节点可以有多个出边，所有目标节点将在下一个超步中并行执行。
  • 动态路由 (Send): 条件边的路由函数可以返回 Send 对象列表，用于实现 Map-Reduce 模式，动态创建未知数量的边并传递不同的状态给下游节点。

​
高级功能

  • 图迁移 (Graph Migrations): 支持在使用检查点（Checkpointer）时修改图的结构（节点、边）和状态模式，对已结束或中断的线程有不同的兼容性规则。
  • 运行时上下文 (Runtime Context): 可以在图定义时指定 context_schema，并在调用时传入上下文（如模型提供商、数据库连接），供节点内部使用。
  • 递归限制 (Recursion Limit): 设置单次执行的最大超步数（默认 25），防止无限循环。通过 config 传入（Python: {"recursion_limit": 5}, JS: { recursionLimit: 5 }）。
  • 可视化 (Visualization): 框架内置了图的可视化功能。

​
关键要点

  • Command vs Conditional Edges: 当需要同时更新状态和进行路由时，使用 Command；仅需条件路由时，使用条件边。
  • Send: 用于需要动态、并行处理多个子任务的场景（Map-Reduce）。
  • Reducers: 对于需要累积或智能合并的 State 键（尤其是消息列表），必须正确定义归约器。
  • Schema Flexibility: 利用输入/输出/私有模式可以构建更模块化和安全的图。
这份文档为理解和使用 LangGraph 构建复杂的、状态驱动的、可能包含循环和并行执行的智能体工作流提供了全面的指导。