Agent 开源项目全景解析（上）：LangGraph、Spring AI 与 Agent Runtime

JoyT2026-08-12 11:00

很多 Agent 项目看起来都在做"模型 + 工具 + 工作流"，真正进入工程开发以后，它们解决的问题层级并不相同。有些项目负责把模型接进应用，有些负责管理状态和执行顺序，有些直接提供完整的 Agent Runtime。理解这几个层级之后，LangChain、LangGraph、Spring AI、Spring AI Alibaba 和 OpenAI Agents SDK 之间的关系会清晰很多。

目录

[一、先建立一张 Agent 开源项目地图](#一、先建立一张 Agent 开源项目地图 "#%E4%B8%80%E3%80%81%E5%85%88%E5%BB%BA%E7%AB%8B%E4%B8%80%E5%BC%A0%20Agent%20%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE%E5%9C%B0%E5%9B%BE")

[二、LangChain：先把 Agent 应用搭起来](#二、LangChain：先把 Agent 应用搭起来 "#%E4%BA%8C%E3%80%81LangChain%EF%BC%9A%E5%85%88%E6%8A%8A%20Agent%20%E5%BA%94%E7%94%A8%E6%90%AD%E8%B5%B7%E6%9D%A5")

[1. 核心抽象已经收敛到 Agent Harness](#1. 核心抽象已经收敛到 Agent Harness "#1.%20%E6%A0%B8%E5%BF%83%E6%8A%BD%E8%B1%A1%E5%B7%B2%E7%BB%8F%E6%94%B6%E6%95%9B%E5%88%B0%20Agent%20Harness")

[三、LangGraph：真正需要理解的是 State](#三、LangGraph：真正需要理解的是 State "#%E4%B8%89%E3%80%81LangGraph%EF%BC%9A%E7%9C%9F%E6%AD%A3%E9%9C%80%E8%A6%81%E7%90%86%E8%A7%A3%E7%9A%84%E6%98%AF%20State")

[1. Graph 只是表象，State 才是核心](#1. Graph 只是表象，State 才是核心 "#1.%20Graph%20%E5%8F%AA%E6%98%AF%E8%A1%A8%E8%B1%A1%EF%BC%8CState%20%E6%89%8D%E6%98%AF%E6%A0%B8%E5%BF%83")

[2. Checkpoint 让工作流具备恢复能力](#2. Checkpoint 让工作流具备恢复能力 "#2.%20Checkpoint%20%E8%AE%A9%E5%B7%A5%E4%BD%9C%E6%B5%81%E5%85%B7%E5%A4%87%E6%81%A2%E5%A4%8D%E8%83%BD%E5%8A%9B")

[四、Spring AI：Java 项目首先应该理解这一层](#四、Spring AI：Java 项目首先应该理解这一层 "#%E5%9B%9B%E3%80%81Spring%20AI%EF%BC%9AJava%20%E9%A1%B9%E7%9B%AE%E9%A6%96%E5%85%88%E5%BA%94%E8%AF%A5%E7%90%86%E8%A7%A3%E8%BF%99%E4%B8%80%E5%B1%82")

[1. Spring AI 解决的是 Java 应用如何接入 AI](#1. Spring AI 解决的是 Java 应用如何接入 AI "#1.%20Spring%20AI%20%E8%A7%A3%E5%86%B3%E7%9A%84%E6%98%AF%20Java%20%E5%BA%94%E7%94%A8%E5%A6%82%E4%BD%95%E6%8E%A5%E5%85%A5%20AI")

[2. Advisor 是理解 Spring AI 架构的重要入口](#2. Advisor 是理解 Spring AI 架构的重要入口 "#2.%20Advisor%20%E6%98%AF%E7%90%86%E8%A7%A3%20Spring%20AI%20%E6%9E%B6%E6%9E%84%E7%9A%84%E9%87%8D%E8%A6%81%E5%85%A5%E5%8F%A3")

[五、Spring AI Alibaba：Java 中补上 Graph 和 Agent Runtime](#五、Spring AI Alibaba：Java 中补上 Graph 和 Agent Runtime "#%E4%BA%94%E3%80%81Spring%20AI%20Alibaba%EF%BC%9AJava%20%E4%B8%AD%E8%A1%A5%E4%B8%8A%20Graph%20%E5%92%8C%20Agent%20Runtime")

[1. 它在 Spring AI 之上增加了 Agent Framework 与 Graph](#1. 它在 Spring AI 之上增加了 Agent Framework 与 Graph "#1.%20%E5%AE%83%E5%9C%A8%20Spring%20AI%20%E4%B9%8B%E4%B8%8A%E5%A2%9E%E5%8A%A0%E4%BA%86%20Agent%20Framework%20%E4%B8%8E%20Graph")

[2. Human-in-the-Loop 已经进入框架层](#2. Human-in-the-Loop 已经进入框架层 "#2.%20Human-in-the-Loop%20%E5%B7%B2%E7%BB%8F%E8%BF%9B%E5%85%A5%E6%A1%86%E6%9E%B6%E5%B1%82")

[六、OpenAI Agents SDK：理解 Agent Loop 的一个精简样本](#六、OpenAI Agents SDK：理解 Agent Loop 的一个精简样本 "#%E5%85%AD%E3%80%81OpenAI%20Agents%20SDK%EF%BC%9A%E7%90%86%E8%A7%A3%20Agent%20Loop%20%E7%9A%84%E4%B8%80%E4%B8%AA%E7%B2%BE%E7%AE%80%E6%A0%B7%E6%9C%AC")

七、上篇的工程选型结论

一、先建立一张 Agent 开源项目地图

截至 2026 年 8 月 11 日，LangGraph 主包最新正式版本为 1.2.10，Spring AI 当前 GA 版本为 2.0.0，Spring AI Alibaba 最新稳定 Release 为 1.1.2.2，OpenAI Agents SDK Python 最新正式版本为 0.19.4。LangChain 采用多包独立发布方式 ，目前 langchain-core 已到 1.5.3，langchain-openai 于 8 月 10 日更新至 1.4.3。

项目 主要语言 最适合解决的问题 重点源码入口
LangChain Python Agent 快速开发、模型与工具抽象 Agent、Middleware、Tool 体系
LangGraph Python 状态工作流、长任务、恢复、HITL StateGraph、Checkpointer
Spring AI Java Spring Boot 中接入模型、Tool、RAG、MCP ChatClient、Advisor、Tool Calling
Spring AI Alibaba Java Java Agent、Graph、多 Agent、持久状态 StateGraph、ReactAgent、CompiledGraph
OpenAI Agents SDK Python 轻量 Agent Runtime、Tools、Handoff、Guardrail Agent、Runner、Session

从工程层级看，可以把这些框架理解成三个位置。第一层负责模型、Prompt、Tool、Memory 等应用能力，Spring AI 和 LangChain主要位于这里 。第二层负责状态、节点、边和恢复执行，LangGraph 与 Spring AI Alibaba Graph 更接近这一层 。第三层直接提供 Agent 运行循环，负责模型调用、工具执行、Handoff、Session 和 Guardrail，OpenAI Agents SDK 的 Runner 是非常典型的实现。LangGraph 和 Spring AI Alibaba 也已经覆盖相当一部分 Runtime 能力。

二、LangChain：先把 Agent 应用搭起来

1. 核心抽象已经收敛到 Agent Harness

LangChain 当前文档把 Agent 描述为"模型 + Harness" 。其中模型负责推理，Harness 负责工具调用循环、Middleware、状态和执行控制。开发者通常通过 create_agent 创建 Agent，再配置模型、Tools、Prompt 与 Middleware。运行时会反复执行"模型判断下一步动作---调用工具---把结果重新交给模型"的循环，直到模型产生最终结果。

这意味着 LangChain 很适合快速构建具有工具调用能力的 Agent，例如企业知识助手、数据库查询 Agent、API 操作 Agent。它提供了大量模型与工具集成，开发者通常不用自己处理每一家模型供应商的底层协议。

当业务逐渐出现"任务必须暂停""失败后继续""某一步需要人工审批""多个节点按照明确图结构执行"等要求时，LangChain 官方本身也会把这些执行能力交给底层 LangGraph Runtime。LangChain 文档明确说明其 Agent 构建在 LangGraph 之上。

因此，学习 LangChain 时没有必要一开始深入所有 Integration。更值得先掌握 Agent、Tool、Middleware、Message 和 Structured Output，然后进入 LangGraph 理解 Runtime。

三、LangGraph：真正需要理解的是 State

1. Graph 只是表象，State 才是核心

LangGraph 官方把自己定位为面向长时间、状态化 Agent 的低层编排框架。一个 LangGraph 工作流主要由 State、Node 和 Edge 组成：State 保存任务当前数据，Node 执行某一步逻辑，Edge 决定下一步走向。

源码中最值得先看的文件是：

bash 复制代码 
libs/langgraph/langgraph/graph/state.py

其中核心类型是 StateGraph，compile() 会把开发阶段定义的状态图编译为可以执行的 Graph。当前源码仍然以 StateGraph 为主要图构建入口。

很多初学者第一次看 LangGraph 时容易把注意力放在节点数量上，例如"这里有规划节点、搜索节点和总结节点"。工程中更重要的问题是节点之间究竟共享什么状态。例如：

python 复制代码 
# TypedDict 用来定义整个工作流共享的数据结构。
# 每一个节点接收到的 state，都会遵守这个结构。
class TaskState(TypedDict):

    # 保存用户最初提交的问题。
    question: str

    # 保存检索阶段得到的文档。
    documents: list[str]

    # 保存最终生成的答案。
    answer: str

节点本质上就是"读取 State 中的一部分数据，再返回需要更新的数据"。这样设计以后，一个任务即使中途中断，只要状态能够持久化，后续执行就有机会从已保存的位置继续。

2. Checkpoint 让工作流具备恢复能力

LangGraph 的 Checkpointer 会在执行过程中保存 Graph State 。官方 Persistence 文档将 Checkpointer 用于短期状态持久化，同时另外提供 Store 保存跨线程的长期记忆。Interrupt 机制同样依赖持久化：节点调用 interrupt() 后，运行状态会保存下来，等待外部输入，再从中断位置恢复。

这也是 LangGraph 在 Agent 工程中很重要的原因。假设一个任务包含"查询客户信息---生成退款方案---等待人工审批---调用退款 API"，审批可能几个小时之后才能完成。HTTP 请求早已结束，模型上下文也无法一直驻留在内存中。Graph State 和 Checkpoint 可以把任务转变为可持久化的执行对象。

2026 年 8 月，LangGraph Checkpoint 还新增了可选的 omit_expired 读取机制，使运行时能够跳过已经过期的 Checkpoint。这说明状态生命周期已经进入 Runtime 的实际工程设计范围。

四、Spring AI：Java 项目首先应该理解这一层

1. Spring AI 解决的是 Java 应用如何接入 AI

Spring AI 官方将自己定位为 AI Engineering 的应用框架，其核心目标是连接企业数据、API 和 AI 模型。当前 2.0.0 已经与 Spring Boot 4.1、MCP SDK 2.0 等新一代 Spring 生态版本协同演进。

Spring AI 最重要的入口之一是：

bash 复制代码 
spring-ai-client-chat/
└── src/main/java/org/springframework/ai/chat/client/ChatClient.java

源码中的 ChatClient 明确被定义为面向 AI Model 的无状态请求客户端，并通过 Fluent API 组织 Prompt、模型调用、Advisor 和 Tool Calling。ChatClient.builder(ChatModel) 用于构建实例。

因此，在一个典型 Spring Boot 项目里，业务代码可以保持非常熟悉的结构：

java 复制代码 
// @RestController 告诉 Spring：
// 这个类负责接收 HTTP 请求，并把方法返回值直接写入 HTTP Response。
@RestController
public class AiController {

    // final 表示这个字段在构造完成之后不能重新指向另一个 ChatClient。
    // ChatClient 是 Spring AI 提供的模型调用客户端。
    private final ChatClient chatClient;

    // 这是构造器。
    // Spring 会通过依赖注入把 ChatClient.Builder 传进来。
    public AiController(ChatClient.Builder builder) {

        // builder.build() 根据 Spring Boot 已经配置好的模型信息
        // 创建真正用于请求大模型的 ChatClient。
        this.chatClient = builder.build();
    }

    // @GetMapping 表示浏览器或前端访问 /ai 时，
    // Spring MVC 会调用下面这个 ask 方法。
    @GetMapping("/ai")
    public String ask(
            // @RequestParam 表示从 URL 参数中获取 message。
            // 例如：GET /ai?message=你好
            @RequestParam String message) {

        // prompt()：开始创建一次新的模型请求。
        return chatClient.prompt()

                // user(message)：把用户输入封装成 User Message。
                .user(message)

                // call()：同步调用模型。
                // 当前线程会等待模型完成返回。
                .call()

                // content()：从模型响应中取出最终文本内容。
                .content();
    }
}

这段代码本身没有传统意义上的 Agent Loop，它展示的是 Spring AI 的基础应用抽象。后续可以继续在 ChatClient 上增加 Tool、Advisor、Memory、RAG 和 Structured Output。

2. Advisor 是理解 Spring AI 架构的重要入口

Spring AI 的 Advisor 可以介入一次 ChatClient 调用过程 ，例如加入 Memory、RAG 上下文、日志、结构化输出检查以及 Tool Calling。当前源码中 DefaultChatClient 会组织 Advisor Chain，项目中可以看到 ChatModelCallAdvisor、ChatModelStreamAdvisor、ToolCallingAdvisor、Memory Advisor 等实现。

这个设计和传统 Spring 后端里的 Filter、Interceptor 或 AOP 思维有一定相似性：业务代码保持简洁，横向能力通过独立组件进入调用过程。对于已有 Spring Boot 后端，这种架构的学习成本通常比较低。

源码建议优先阅读：

bash 复制代码 
spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/ChatClient.java

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/DefaultChatClient.java

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/advisor/ToolCallingAdvisor.java

官方仓库：

bash 复制代码 
https://github.com/spring-projects/spring-ai
https://github.com/spring-projects/spring-ai/releases
https://docs.spring.io/spring-ai/reference/

五、Spring AI Alibaba：Java 中补上 Graph 和 Agent Runtime

1. 它在 Spring AI 之上增加了 Agent Framework 与 Graph

Spring AI Alibaba 当前仓库已经明确拆分 spring-ai-alibaba-agent-framework 和 spring-ai-alibaba-graph 等模块。Agent Framework 提供面向 Agent 的高级抽象，Graph 提供底层工作流 Runtime。官方文档支持工作流、单 Agent、多 Agent、并行分支、子图、人工介入和状态持久化等场景。

这里值得重点关注两个源码入口：

bash 复制代码 
spring-ai-alibaba-graph-core/
└── src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java

spring-ai-alibaba-agent-framework/
└── src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java

StateGraph 负责图结构构建，编译之后生成 CompiledGraph；ReactAgent 则进一步把模型、Tool、Hook 和 Agent 执行语义组织起来。两者当前都可以在官方主仓库直接查看。

对于 Java 开发者，这一结构非常值得理解。Spring AI 可以承担模型调用、Tool、RAG 和 MCP 等应用能力 ；Spring AI Alibaba Graph 可以继续承担"任务如何流转、状态如何保存、什么时候中断、什么时候恢复"的问题。

2. Human-in-the-Loop 已经进入框架层

官方仓库当前提供 HumanInTheLoopExample，其中直接使用 StateGraph、ReactAgent、HumanInTheLoopHook、MemorySaver 和 InterruptionMetadata 来完成工具调用审批、拒绝和修改。

这类机制适合付款、删除数据、发送邮件、修改生产配置等操作。Agent 可以先完成规划和参数生成，在真正执行高风险 Tool 之前暂停，把状态写入 Checkpoint。人工批准以后，Runtime 再继续剩余节点。

官方源码：

bash 复制代码 
https://github.com/alibaba/spring-ai-alibaba

https://github.com/alibaba/spring-ai-alibaba/blob/main/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java

https://github.com/alibaba/spring-ai-alibaba/blob/main/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java

https://java2ai.com/

六、OpenAI Agents SDK：理解 Agent Loop 的一个精简样本

OpenAI Agents SDK Python 的结构相对集中。Agent 保存 Agent 的配置，Runner 是运行入口。Runner 每一轮调用当前 Agent；如果得到最终输出则结束，如果发生 Handoff 就切换 Agent，如果得到 Tool Call 就执行工具并把结果交回模型，然后进入下一轮。官方文档直接描述了这一 Run Loop。

值得优先阅读的源码结构是：

bash 复制代码 
src/agents/agent.py
src/agents/run.py
src/agents/run_internal/
src/agents/memory/session.py
src/agents/run_internal/session_persistence.py

官方仓库的贡献指南也明确指出，src/agents/run.py 是 Runner 和 AgentRunner 的 Runtime 入口，Session 的保存和恢复逻辑继续拆分到 run_internal/session_persistence.py。

当前 0.19.4 已经包含 Tool、Guardrail、Handoff、Session、Tracing、Sandbox 与 MCP 等能力。8 月 4---5 日的 0.19.3、0.19.4 更新还集中修复了恢复执行后的 Tool 名称冲突、Session 持久化、并发失败取消、Guardrail 结果保存和 MCP 重试等问题。这个仓库非常适合用来观察一个现代 Agent Runtime 需要管理哪些状态。

官方来源：

bash 复制代码 
https://github.com/openai/openai-agents-python
https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py
https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py
https://openai.github.io/openai-agents-python/

七、上篇的工程选型结论

如果目标是在已有 Spring Boot 服务中增加聊天、RAG、Tool Calling、Structured Output 和 MCP，Spring AI 是最自然的基础层。如果进一步需要明确的节点编排、状态持久化、人工审批和多 Agent，Spring AI Alibaba 的 Graph 与 Agent Framework 更接近完整 Java Agent Runtime。

Python 体系中，LangChain适合快速组织模型、Tool 和 Agent 应用，LangGraph适合控制复杂状态和长任务。希望直接理解 Agent Loop、Handoff、Guardrail、Session 和 Trace 的工程实现时，OpenAI Agents SDK 的源码规模和职责划分都很适合作为阅读对象。

下一篇继续看另一类项目：LlamaIndex 如何围绕数据与 RAG 构建 Agent，Dify 与 FastGPT 为什么更适合快速形成可运行产品，以及这些项目放在真实工程中应该怎样选择。

相关推荐
云技纵横1 小时前
线上接口突然超时，怎么判断卡在 Nginx、线程池、连接池还是 SQL？
后端·sql·mysql
Java内核笔记1 小时前
容错能力进入 spring-core:Spring Boot 4 原生重试机制全解析
java·后端
风卿1 小时前
知识库双路召回：BM25 关键词与语义向量 RRF 融合，附指标实测
后端
未秃头的程序猿1 小时前
虚拟线程上线一周后翻车了——pinning问题排查实录
java·后端·架构
AI_paid_community1 小时前
如何使用 Claude 在 AI 时代快速入局新的行业？（经验贴）
前端·javascript·后端
AI多Agent协作实战派1 小时前
AI多Agent协作系统实战（三十六）：代码里明明写了，编译完怎么没了？
后端
柠檬味拥抱1 小时前
代码看腻了，我让 Seed Evolving 把整个仓库搓成了一座能走进去的 3D 城市
后端
mit6.8242 小时前
archived
后端·python·flask
用户298698530142 小时前
效率工具分享：3 款免费 Markdown 转 Word 在线转换器
人工智能·后端
热门推荐
01VSCode+CodeX扩展，无法启动02GitHub 镜像站点03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06如何新建文件夹？ 电脑新建文件夹的4种方法07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路08历年考研数学一、数学二、数学三真题试卷及答案PDF092026年8月4日科技热点深度解析：AI大模型群雄逐鹿、卫星互联网组网提速、半导体封装材料革命10Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费