> ## 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.

# Graph api

您提供的文档是 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 构建复杂的、状态驱动的、可能包含循环和并行执行的智能体工作流提供了全面的指导。