# LangGraph 的 Hexagonal Architecture 实践：Ports 与 Adapters 的解耦之道 > 解析 LangGraph 如何通过 Ports & Adapters 模式实现 agent 执行流与外部服务的解耦，涵盖 StateGraph SDK、PregelLoop 运行时以及 110 测试覆盖的工程实践。 ## 元数据 - 路径: /posts/2026/01/26/langgraph-hexagonal-architecture-agent-orchestration/ - 发布时间: 2026-01-26T01:32:35+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 当开发者从简单的顺序链式调用转向复杂的多步智能体时，一个核心问题浮现出来：如何让 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 构建的最佳实践总结。 ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。