当开发者从简单的顺序链式调用转向复杂的多步智能体时，一个核心问题浮现出来：如何让 agent 逻辑与外部服务保持松耦合，同时不牺牲可测试性与可维护性。LangGraph 在设计之初就选择了 hexagonal architecture（又称 ports and adapters architecture）作为其核心理念，这一选择直接决定了框架如今能够支撑 LinkedIn、Uber、Klarna 等企业级生产环境的架构基础。理解这一架构模式，对于任何想要构建可靠 agent 系统的工程师而言，都是值得深入研究的课题。
为何 agent 框架需要 hexagonal architecture
传统的 agent 实现往往将业务逻辑与 LLM 调用、数据存储、外部 API 请求混在一起。这种紧耦合带来的问题是：当你想将 LLM 从 GPT-4 切换到 Claude 时，或者将向量数据库从 Pinecone 迁移到 Weaviate 时，代码中遍布的改动点会让重构变成一场噩梦。更糟糕的是，这种结构使得单元测试几乎无法进行 —— 你无法在不调用真实 LLM API 的情况下测试 agent 的决策逻辑。hexagonal architecture 的核心思想正是通过依赖倒置原则，将核心业务逻辑（应用层）与外部依赖（基础设施层）彻底分离。应用层定义接口（ports），基础设施层提供具体实现（adapters），两者通过接口进行交互，从而实现真正的解耦。
LangGraph 对这一理念的实践体现在其运行时与 SDK 的分离设计上。开发者直接使用的是 StateGraph 这个高级 SDK，它提供了声明式的图构建接口，开发者只需定义节点（node）和边（edge），即可描述 agent 的执行流程。而在底层，PregelLoop 运行时负责实际的任务调度、状态管理与 checkpoint 保存。这种分离意味着 SDK 层可以演进、可以替换，而不影响运行时的稳定性，反之亦然。官方在设计文档中明确指出，LangGraph 的运行时是独立于开发者 SDK 的，这使得框架能够在两年内持续进行性能优化而不破坏公共 API 的兼容性。
ports 与 adapters 的具体实现
在 LangGraph 的语境下，port 对应的是 agent 与外部世界交互的抽象接口。例如，一个用于调用 LLM 的 port 可能定义了一个 generate 方法，它接收上下文信息并返回生成的文本；而对应的 adapter 则可以是 OpenAI adapter、Anthropic adapter 或者本地模型 adapter。开发者可以根据需要在运行时注入不同的 adapter，而无需修改核心 agent 逻辑。这种设计还带来了另一个重要好处：测试时可以使用 mock adapter，完全绕过高昂的 LLM API 调用，实现快速、可靠的单元测试。
状态管理是 agent 系统的另一个关键维度。LangGraph 通过 channels 机制实现状态持久化，每个 channel 都有唯一的名称和递增的版本号。当 agent 执行过程中需要暂停等待用户输入（human-in-the-loop 场景）时，系统会将当前状态序列化并 checkpoint 到持久化存储中。这种基于 checkpoint 的中断机制，使得 agent 可以在任意时刻被安全地挂起和恢复，即使服务器重启也不会丢失执行进度。从 hexagonal architecture 的视角看，状态持久化也是一个 port，而具体的数据库实现（如 PostgreSQL、Redis、文件系统）则是可替换的 adapters。
基于 BSP 的执行算法与确定性保证
LangGraph 的执行引擎采用了 BSP（Bulk Synchronous Parallel）算法，也称为 Pregel 算法。这一选择并非随意为之 —— 传统的 DAG 框架无法处理 agent 中常见的循环结构，而 BSP 天然支持带环路的计算图，并且提供了确定性的并发执行语义。在每个执行步骤中，系统会选择一个或多个节点并行执行，但这些节点在执行时会获得状态的独立副本，因此不会产生数据竞争。当所有并行节点完成后，它们的状态更新会按照确定性顺序应用到主状态中，确保无论执行顺序如何，最终结果都是一致的。
这种确定性对于生产环境至关重要。当 LLM 本身具有非确定性时，框架层面的确定性可以排除一个重要的变量，使得调试和问题定位变得更加简单。如果 agent 在生产环境中出现了异常行为，开发者可以确信这并非由并发执行时序导致，而是来自 LLM 的输出或业务逻辑本身。性能方面，BSP 算法的开销是可控的，官方给出的基准数据显示，启动调用的时间复杂度与节点数线性相关，而步骤规划的时间复杂度保持常数 —— 这意味着即使 agent 包含数百个节点，系统仍能保持可预测的响应延迟。
工程实践中的可观测性与测试策略
hexagonal architecture 的另一个优势是它为可观测性提供了天然的支持点。由于所有与外部世界的交互都通过 port 进行，开发者可以在 adapter 层统一注入 tracing、logging 和 metrics 收集逻辑，而无需修改核心业务代码。LangGraph 与 LangSmith 深度集成，能够自动记录 agent 执行过程中的每个步骤、输入输出以及状态变化。这种开箱即用的 observability 对于调试复杂的多步 agent 尤为重要 —— 开发者可以清晰地看到 agent 在哪个节点做出了何种决策，以及状态在节点之间如何流转。
测试覆盖是衡量框架成熟度的重要指标。LangGraph 维护了超过 110 个单元测试和集成测试，这些测试覆盖了从基本的图构建到复杂的并发执行场景。对于采用 LangGraph 构建生产 agent 系统的团队而言，借鉴其测试策略同样重要。建议在 port 接口层面编写契约测试，确保不同的 adapter 实现都符合预期的行为规范；在业务逻辑层面编写端到端测试，利用 mock adapter 模拟各种 LLM 响应和外部服务故障；在系统层面则利用 checkpoint 机制测试故障恢复和状态一致性。
落地参数与监控要点
在生产环境中部署基于 hexagonal architecture 的 agent 系统时，有几个关键参数值得关注。checkpoint 保存间隔决定了故障恢复的粒度，过于频繁会增加存储开销，过于稀疏则可能导致较多的重复计算；对于执行时间较长的多步 agent，建议在每个决策节点之后保存 checkpoint。状态序列化格式默认使用 MsgPack，对于敏感数据可以配置加密选项。并发执行时的节点数量上限需要根据 LLM 调用的延迟和服务器资源进行调优，过高的并发可能触发 LLM 服务的 rate limit。
监控层面应重点关注几个指标：节点执行耗时分布，用于识别异常慢的步骤；checkpoint 写入延迟，反映持久化存储的性能状态；human-in-the-loop 中断频率和平均等待时间，帮助评估用户参与度的合理性；以及不同 adapter（如不同 LLM 提供商）的调用成功率，便于及时发现和切换到备用方案。这些指标应当与 hexagonal architecture 的各个层次对齐，便于在出现问题时快速定位是 adapter 层、port 层还是核心运行时的问题。
资料来源：本文核心设计理念参考 LangChain 官方博客对 LangGraph 架构的设计阐述，以及生产环境 agent 构建的最佳实践总结。