Graph api

​

核心概念：图 (Graphs)

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: 利用输入/输出/私有模式可以构建更模块化和安全的图。