langchain-ai.github.io/langgraph

1.Quickstart

LangGraph 开发Agen的两大核心范式——Graph API（基于显式节点、边和状态构建有向图）与 Functional API（通过轻量级任务装饰器与原生 Python 控制流编写函数式工作流）。

1.智能体设计的前置核心要素

在进入具体的架构设计之前，教科书式的智能体开发必须明确并定义以下三个核心物理实体，无论是采用何种 API 范式，这些要素都构成了智能体与外界交互的基石。

1.  大语言模型（LLM）的初始化与配置：智能体的“大脑”。在实际开发中，需要指定具体的基础模型（例如 Claude）并设置温度（Temperature）等超参数。
2.  工具箱（Tools）的声明：智能体的“四肢”。利用 LangChain 的 `@tool` 装饰器将标准的 Python 函数声明为智能体可调用的外部工具。这些工具必须包含详尽的文档字符串（Docstring）和类型提示（Type Hints），以便 LLM 能够准确理解何时以及如何调用它们。
3.  工具与模型的绑定（Tool Binding）：通过大语言模型自带的 `.bind_tools()` 接口，将工具列表作为控制信道传递给模型。此时，模型在生成文本之余，获得了生成结构化“工具调用指令（Tool Calls）”的能力。

2.Graph API 开发范式（状态机架构）

Graph API 将智能体视为一个结构严密的有向图。这一范式是软件工程中传统状态机（State Machine）思想的延续，非常适合架构复杂、具有多轮循环和分支决策的工业级应用。 

1. 显式状态定义（State）

在 Graph API 中，状态是图在运行期间唯一的信息源，也是跨节点传递数据的物理载体。
定义媒介：通常使用 Python 的 `TypedDict` 进行定义。
增量追加机制：为了防止后续节点输出的信息覆盖前面的历史记录，需要引入类型批注（如 `Annotated[list[AnyMessage], operator.add]`）。这里的 `operator.add` 充当了“Reducer”的作用，确保新生成的消息被追加到已有列表中，而不是进行整体替换。

2. 计算节点（Nodes）

计算节点是图中执行具体业务逻辑的最小单元。每一个节点本质上都是一个接收当前状态（State）作为输入、并返回修改后的状态片段（State Slice）的 Python 函数。
模型节点（llm_call）：负责接收包含所有历史上下文的最新状态，向 LLM 发起请求，并将生成的 AI 消息（AIMessage）写回状态。
工具执行节点（tool_node）：负责拦截最新消息中的 `tool_calls` 参数，根据工具名称在预设的工具字典中查找对应的实体并执行，最后将执行结果以 `ToolMessage` 的形式写入状态。

3. 控制边（Edges）

控制边用于定义数据和控制流在各个计算节点之间的转移路径。
静态边（Normal Edges）：确定性的无条件跳转，例如从开始（START）直接进入模型节点，或者工具节点执行完后无条件返回模型节点。
条件边（Conditional Edges）：基于节点当前的运行时状态进行动态路由。例如，通过决策函数（`should_continue`）评估 LLM 是否产生工具调用需求：若有，则路由至工具执行节点；若无，则直接路由至结束标志（END）。

4. 编译与实例化（Compile）

在将所有的节点和边加入到 `StateGraph` 构建器后，必须调用 `.compile()` 方法。这一步骤会将抽象的图结构转化为可执行的模型管道，内部会自动进行图的拓扑校验和运行时状态持久化机制的初始化。 

3.Functional API 开发范式（命令式控制流架构）

Functional API 是 LangGraph 提供的一种轻量级、更符合 Python 开发者原生编码习惯的命令式开发范式。它不要求开发者显式地定义节点、配置路由边和编译图，而是将整个图的执行逻辑浓缩在单个函数内，由底层的任务调度器来自动化管理。

1. 任务原子化（@task 装饰器）

传统的“节点”被声明为由 `@task` 装饰的轻量级函数。这些任务可以像普通 Python 函数一样在执行入口内被同步或异步调用，从而解耦了具体的底层服务（例如调用模型或调用工具）。

2. 统一入口与原生控制流（@entrypoint 装饰器）

开发者的主逻辑被放置在一个由 `@entrypoint()` 装饰的业务函数中。
循环与条件分支的回归：不需要再编写繁琐的条件路由边，而是使用最直观的 Python 关键字（如 `while True`、`if not` 和 `break`）来控制“LLM 决策 -> 工具调用 -> 回到 LLM”的闭环。
未来对象与异步结果：在入口函数内部，通过调用任务的 `.result()` 方法来显式等待上一个异步步骤的完成，从而支持并行任务的高效调度。

3. 辅助的状态更新工具

由于摆脱了基于 TypedDict Reducer 的隐式状态合并，Functional API 推荐使用 `add_messages` 等官方内置工具，以手动合并与追加在循环过程中产生的新消息。 [LangGraph Quickstart](https://docs.langchain.com/oss/python/langgraph/quickstart)

2.Graph API

LangGraph 提供了声明式的 Graph API 和命令式的 Functional API 两套体系。前者适用于需要显式状态管理、并行逻辑与复杂决策树的可视化图结构；后者更适合于过程式控制流、快速原型设计和极简代码结构的线性逻辑。

1.LangGraph 双 API 架构概览

LangGraph 框架底层运行着统一的运行时引擎（Runtime），但向上为开发者封装了两种完全不同的编程接口（API）。这两套接口在底层能力上完全等价，都支持持久化（Persistence）、流式输出（Streaming）、人在环路（Human-in-the-loop）以及短期/长期记忆（Memory）等核心功能，但它们在设计哲学和适用场景上有着根本性的分野。

2.声明式 Graph API（图 API）核心规范

Graph API 采用声明式（Declarative）设计哲学。开发者需要显式定义状态模式（State Schema）、计算节点（Nodes）和控制边（Edges）来静态构建一个图结构。这种结构天然具备极强的工程约束力。 

其核心适用准则包括：

1. 显式状态共享与管理：当工作流包含多个独立组件，且这些组件需要频繁读取、修改和同步一个全局共享的上下文数据（如状态字典 `TypedDict`）时，应当采用 Graph API。
2. 复杂条件决策树：当业务逻辑中包含多级、复杂的条件分支路由，且不同分支之间存在循环跳转时，通过 `add_conditional_edges` 能够将决策路径显式暴露出来，极其利于系统维护。
3. 并行执行与多路同步：若系统需要并行调度多个独立的计算任务（如同时向多个数据源请求数据），并在最终节点（如 `combine_data`）进行汇聚与同步等待，Graph API 可以通过天然的图拓扑结构进行优雅处理。
4. 可视化、调试与团队协同：Graph API 的图结构可以被自动渲染为可视化图表（如 Mermaid），有助于跨职能团队（如产品、算法和工程）共同理解和维护，也大幅降低了复杂日志调试的难度。

3.命令式 Functional API（函数式 API）核心规范

Functional API 采用命令式设计哲学。它允许开发者直接在标准的 Python 过程式代码中嵌入 LangGraph 的高级特性，规避了繁琐的图结构声明与全局状态定义，更符合传统的软件开发直觉。

其核心适用准则包括：

1. 现有过程式代码重构最小化：对于已经存在的大量传统 Python 业务代码，如果只需低侵入式地引入状态保持、时间旅行或中断机制，使用 `@task` 和 `@entrypoint` 装饰器可以实现无缝升级。
2. 函数作用域的局部状态：当数据流仅在局部函数内流动，不需要在整个工作流中广播或全局共享状态时，应当使用 Functional API，直接通过函数传参（Arguments & Return Values）来流转数据。
3. 快速原型迭代（Rapid Prototyping）：在产品开发初期，开发者无需耗费精力去设计繁琐的状态字典（State Schema）和拓扑关系，可以专注于核心 Prompt 的调试，实现极速上线。
4. 线性或简单分支流：若智能体的核心工作流主要是顺序执行，只包含少数简单的 `if/else` 判断且无复杂多重循环时，使用原生的 Python 控制流更加清晰直观。

4.协同设计与平滑迁移规范

在实际的工业级系统中，两套 API 并不是孤立和对立的，设计者应当掌握混合使用与相互迁移的工程技巧。

• 混合架构（Combining Both APIs）：

  可以将一个使用 Functional API 构建的纯数据处理管道（如通过 `@entrypoint` 处理原始输入）作为一个子节点，嵌入到由 Graph API 构建的多智能体协同图（`StateGraph`）中。这种模式能够同时兼顾局部代码的极简性与全局架构的可视化。

• 从 Functional API 迁移至 Graph API（渐进式演进）：

  当一个轻量级的函数式工作流随着业务发展变得愈发臃肿、内部充斥着嵌套的 `if/else` 条件和复杂的并发同步等待时，应当及时将其重构。将其局部变量抽取为全局共享的 `TypedDict` 状态，并使用 `StateGraph` 的条件边将深层嵌套的条件分支拉平为图的拓扑边，以此提升系统的可控性。

• 从 Graph API 迁移至 Functional API（简化过度设计）：

  如果最初设计的 `StateGraph` 经过迭代后，发现大部分节点退化为了纯粹的线性单向流，且不存在任何循环或复杂的多智能体决策，应当将其简化为 Functional API 的原生控制流，消除不必要的样板代码（Boilerplate Code），让代码回归直观。