[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81694":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":12,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},81694,"spring-ai-agentx","bigchuidw3\u002Fspring-ai-agentx","bigchuidw3","基于原生 Spring AI 的智能体（Agent）开发框架，提供 ReAct 执行引擎、分层记忆、工具调度、Human-in-the-Loop 等核心能力，形成完整的 Harness Engineering 方案，帮助开发者快速构建 AI Agent，可以快速搭建 Java 版的 Claude Code。",null,"Java",52,6,22,1,0,14,30,52.54,"Apache License 2.0",false,"main",true,[],"2026-06-12 04:01:34","# Spring AI AgentX\n\n基于原生 Spring AI 的智能体（Agent）开发框架，提供 ReAct 执行引擎、分层记忆、工具调度、Human-in-the-Loop 等核心能力，形成完整的 Harness Engineering 方案，帮助开发者快速构建 AI Agent，可以快速搭建 Java 版的 Claude Code。\n\n> 当前版本：1.0.0-M1 | JDK 21+ | Spring Boot 3.5.x | Spring AI 1.1.0\n\n## Spring AI AgentX 是什么\n\n![img.png](img.png)\n\nSpring AI AgentX 是一款面向 Java 开发者的 AI Agent 开发框架。基于 **Spring AI** 和 **Reactor** 构建，专注于 Agent 执行引擎，不引入 Graph 编排范式，以简洁的方式帮助开发者构建 AI Agent。\n\n### 设计理念\n\n**不造轮子，只做 Agent 引擎。** 框架基于 Spring AI 原生机制（ChatClient、ToolCallback、ChatMemory）构建，不引入额外的抽象层。开发者无需学习新的编程范式，只要会用 Spring AI，就会用 AgentX。\n\n**不用 Graph，基于 Reactor 实现。** 不引入 LangGraph 等 Graph 编排框架复杂的节点和边定义，执行引擎基于 Reactor 构建，以声明式的响应式流驱动 Agent 的多轮推理与工具调用。从流式输出到工具执行全链路响应式，天然适配 WebFlux 等异步场景。\n\n**Harness Engineering。** 借鉴 Claude Code 的架构理念，大模型是引擎，框架是底盘（Harness）。框架不限定模型选择，但模型以外的一切 —— 工具调度、分层记忆、执行控制、Human-in-the-Loop、上下文管理、技能体系 —— 全部由框架统一提供，让开发者只需关注业务逻辑和模型选型。\n\n## 写在前面\n\n这个框架源于我近三年在 Agent 产品领域的持续深耕。最初只是出于好奇 —— 不论是 Python 的 LangChain、LangGraph、AutoGen……还是 Java 的 Spring AI、Spring AI Alibaba、AgentScope，就想搞清楚这些框架底层到底在做什么，不只是知其然，更想知其所以然。\n\n后来在公司主导 Agent 产品开发的过程中，踩了不少坑，也遇到了开源框架的一些局限性。与其在各种框架之间反复适配修补，不如把积累的经验沉淀成一套自己的框架。AgentX 的每个功能模块都源自真实业务场景，是反复打磨的成果。框架完全基于原生 Spring AI，只用基础能力来实现 Agent 的各种功能。\n\n最初的代码根基，也就是 ReAct 主循环，完全是我手搓实现。随着 vibe coding 的发展、大模型能力的增强，现在框架中大部分代码在我的架构设计和思路引导下由 AI 辅助完成，但每个模块的设计决策、技术选型和边界把控，都来自实战中的思考。\n\n希望这个框架能让大家对 Agent 开发有更深层次的理解。\n\n## 功能概览\n\n### v1.0.0-M1（当前版本）\n\n| 功能 | 说明 |\n|------|------|\n| ReAct Agent 引擎 | 基于 Reasoning + Acting 范式构建多轮执行闭环，自动驱动模型推理与工具调用 |\n| 同步与流式输出 | 同步调用（call）与流式输出（stream）两种模式，流式基于 Reactor Flux 实现 |\n| 统一工具调度 | 原生支持 Function Calling \u002F MCP，工具执行由框架统一接管 |\n| 运行时参数注入 | 通过 RunnableParams 动态覆盖工具参数，精准控制工具行为 |\n| 任务管理与执行控制 | 会话级并发控制与中断机制，保障同一会话执行的有序性与可控性 |\n| 分层记忆体系 | 短期记忆、用户画像、长期记忆（RAG）三层结构，多粒度上下文管理 |\n| 分阶段输出 | StageOutputProvider SPI，在 Agent 生命周期钩子点注入自定义输出 |\n| Human-in-the-Loop | 暂停\u002F恢复机制，支持输入工具与操作工具，支持自定义用户输入工具 |\n| 内置工具能力集 | Bash、文件系统、文本检索（Grep）、Python 等通用工具 |\n| Skills 技能体系 | 基于渐进式披露机制，按需加载技能内容，支持多技能注册与组合 |\n| 思考模型适配 | 新增 `ThinkingMode` 枚举统一 `THINK_TAG` \u002F `REASONING_CONTENT` \u002F `DISABLED` 三种模式，支持 DeepSeek、Qwen3.6-plus 等模型的 `reasoning_content` 字段解析 |\n| DeepSeek-V4 兼容 | 内置 `DeepSeekV4ChatModel`，解决 Spring AI 原生模块在思考模式 + 工具调用场景下的兼容性问题（[spring-ai#6026](https:\u002F\u002Fgithub.com\u002Fspring-projects\u002Fspring-ai\u002Fissues\u002F6026)） |\n| 异常处理与重试 | 内置透明重试机制，统一异常处理（AgentException + AgentErrorCode） |\n| 上下文压缩 | 两层自动压缩策略（micro_compact + auto_compact），控制长对话 Token 消耗 |\n| ToolSearch 工具检索 | 工具按需发现，LLM 通过 tool_search 元工具搜索加载 deferred 工具 |\n| 结构化输出 | 非流式调用输出标准 JSON，支持单对象和泛型集合 |\n\n## 快速开始\n\n### 1. 构建安装\n\n当前版本需从源码构建安装到本地 Maven 仓库：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbigchuidw3\u002Fspring-ai-agentx.git\ncd spring-ai-agentx\nmvn clean install -DskipTests\n```\n\n后续会考虑发布到 Maven Central，届时可直接通过坐标引入，无需手动构建。\n\n### 2. 引入依赖\n\n在项目 `pom.xml` 中引入：\n\n```xml\n\u003Cdependency>\n    \u003CgroupId>com.agentx.ai\u003C\u002FgroupId>\n    \u003CartifactId>spring-ai-agentx-core\u003C\u002FartifactId>\n    \u003Cversion>1.0.0-M1\u003C\u002Fversion>\n\u003C\u002Fdependency>\n```\n\n框架基于 Spring AI 1.1.0，core 模块已内置 `spring-ai-starter-model-openai`，无需额外引入。\n\n### 3. 构造 ChatModel\n\n框架本身不绑定特定大模型，任何 Spring AI 支持的 ChatModel 都可以直接传入。\n\n**方式 A：兼容 OpenAI 接口的模型（Qwen \u002F DeepSeek \u002F Moonshot 等）**\n\n```java\nChatModel chatModel = OpenAiChatModel.builder()\n        .openAiApi(OpenAiApi.builder()\n                .baseUrl(\"https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002F\")  \u002F\u002F 替换为对应厂商的 base URL\n                .apiKey(\"your-api-key\")\n                .build())\n        .defaultOptions(OpenAiChatOptions.builder()\n                .model(\"qwen-plus\")\n                .temperature(0.7)\n                .build())\n        .build();\n```\n\n推荐模型 base URL 参考：\n\n| 厂商 | base URL | 推荐模型 | 类型 |\n|------|----------|---------|------|\n| 通义千问 (DashScope) | `https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002F` | qwen-plus | 普通模型 |\n| 智谱 AI (GLM) | 需引入 `spring-ai-starter-model-zhipuai` | glm-4.7 \u002F glm-5.1 | 普通模型 |\n| DeepSeek | `https:\u002F\u002Fapi.deepseek.com\u002F` | deepseek-v4-flash | reasoning_content 模型（需使用框架内置 `DeepSeekV4ChatModel`，详见 [15-DeepSeek-V4兼容](docs\u002Fcore\u002F15-DeepSeek-V4兼容.md)） |\n| MiniMax | `https:\u002F\u002Fapi.minimaxi.com\u002F` | minimax-M2.7 | Think 模型 |\n\n> **模型选择建议**：一般场景推荐 qwen-plus；需要 Agent 展示思考过程时，根据模型类型选择对应的 `ThinkingMode`：\n> - `\u003Cthink\u002F>` 标签格式（MiniMax 等）→ `thinkingMode(ThinkingMode.THINK_TAG)`\n> - `reasoning_content` 字段格式（DeepSeek、Qwen3.6-plus）→ `thinkingMode(ThinkingMode.REASONING_CONTENT)`\n>\n> 详见 [09-思考模型适配](docs\u002Fcore\u002F09-思考模型适配.md)。\n\n> **关于模型兼容性**：虽然各家模型厂商都声称兼容 OpenAI 接口，但实际在请求参数和响应格式上往往存在差异（如思考模式入参出参的差异、字段校验）。框架会优先适配主流模型（如上表所列），但无法保证当前框架兼容市面上所有模型，希望各位理解。\n\n**方式 B：智谱 AI（GLM 系列，需额外引入 `spring-ai-starter-model-zhipuai`）**\n\n```java\nChatModel chatModel = new ZhiPuAiChatModel(\n        ZhiPuAiApi.builder().apiKey(\"your-api-key\").build(),\n        ZhiPuAiChatOptions.builder()\n                .model(\"glm-4.7\")\n                .temperature(0.7)\n                .build()\n);\n```\n\n**方式 C：DeepSeek V4 思考模型（必须使用框架内置 `DeepSeekV4ChatModel`）**\n\n```java\nChatModel chatModel = DeepSeekV4ChatModel.builder()\n        .deepSeekApi(DeepSeekApi.builder()\n                .apiKey(\"your-api-key\")\n                .baseUrl(\"https:\u002F\u002Fapi.deepseek.com\")\n                .build())\n        .defaultOptions(DeepSeekChatOptions.builder()\n                .model(\"deepseek-v4-flash\")\n                .temperature(0.4)\n                .build())\n        .build();\n```\n\n> **注意**：DeepSeek V4 等思考模型存在 `reasoning_content` 回传兼容性问题，不能使用 OpenAI 兼容接口或 Spring AI 原生模块。详见 [15-DeepSeek-V4兼容](docs\u002Fcore\u002F15-DeepSeek-V4兼容.md)。\n\n**方式 D：Spring Boot 自动注入**\n\n```yaml\n# application.yml\nspring:\n  ai:\n    openai:\n      base-url: https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002F\n      api-key: your-api-key\n      chat:\n        options:\n          model: qwen-plus\n          temperature: 0.7\n```\n\n```java\n@Autowired\nChatModel chatModel;  \u002F\u002F Spring Boot 自动注入，直接传给 Agent\n```\n\n### 4. 最简单的 Agent\n\n3 行代码构建一个可用的智能体：\n\n```java\nReactAgent agent = ReactAgent.builder()\n        .chatModel(chatModel)\n        .build();\n\nString answer = agent.call(\"帮我分析一下 Java 和 Go 的优劣势\");\n```\n\n流式输出：\n\n```java\nagent.stream(\"用三句话介绍 Spring AI\")\n        .doOnNext(chunk -> System.out.print(chunk))\n        .blockLast();\n```\n\n### 5. 自定义系统提示词\n\n通过 `instructions` 设置 Agent 的角色和行为规则：\n\n```java\nReactAgent agent = ReactAgent.builder()\n        .chatModel(chatModel)\n        .instructions(\"\"\"\n                你是一个 Java 架构师助手。\n                遵循以下原则：\n                - 给出可落地的方案，不写空话\n                - 优先使用成熟框架和最佳实践\n                \"\"\")\n        .build();\n\nString answer = agent.call(\"帮我设计一个订单系统的架构\");\n```\n\n---\n\n## 功能文档\n\n> 详细的功能说明和使用示例请查看 [docs\u002Fcore\u002F](docs\u002Fcore\u002F) 目录下的文档。\n\n| # | 功能 | 说明 | 文档 |\n|---|------|------|------|\n| 1 | 同步与流式输出 | call\u002Fstream 双模式，基础 API 和高级 API | [01-同步与流式输出](docs\u002Fcore\u002F01-同步与流式输出.md) |\n| 2 | 工具与 MCP | 内置工具、自定义工具、MCP 协议支持 | [02-工具与MCP](docs\u002Fcore\u002F02-工具与MCP.md) |\n| 3 | 动态会话参数 | RunnableParams、addParam \u002F addToolParam 参数注入 | [03-动态会话参数](docs\u002Fcore\u002F03-动态会话参数.md) |\n| 4 | 任务管理与并发控制 | 会话级并发控制、外部中断 | [04-任务管理与并发控制](docs\u002Fcore\u002F04-任务管理与并发控制.md) |\n| 5 | 分层记忆体系 | 短期记忆、用户画像、长期记忆三层架构 | [05-分层记忆体系](docs\u002Fcore\u002F05-分层记忆体系.md) |\n| 6 | 分阶段输出 | StageOutputProvider SPI，三阶段钩子 | [06-分阶段输出](docs\u002Fcore\u002F06-分阶段输出.md) |\n| 7 | Human-in-the-Loop | 暂停\u002F恢复机制，用户输入工具与操作审批 | [07-Human-in-the-Loop](docs\u002Fcore\u002F07-Human-in-the-Loop.md) |\n| 8 | Skills 技能体系 | 渐进式披露，按需加载技能 | [08-Skills技能体系](docs\u002Fcore\u002F08-Skills技能体系.md) |\n| 9 | 思考模型适配 | 支持 `\u003Cthink\u002F>` 标签和 `reasoning_content` 两种思考输出格式 | [09-思考模型适配](docs\u002Fcore\u002F09-思考模型适配.md) |\n| 10 | 异常处理与重试 | 透明重试机制，统一异常处理 | [10-异常处理与重试](docs\u002Fcore\u002F10-异常处理与重试.md) |\n| 11 | 上下文压缩 | 两层自动压缩策略，控制 Token 消耗 | [11-上下文压缩](docs\u002Fcore\u002F11-上下文压缩.md) |\n| 12 | ToolSearch 工具检索 | 工具按需发现，keyword + LLM 双模式搜索 | [12-ToolSearch工具检索](docs\u002Fcore\u002F12-ToolSearch工具检索.md) |\n| 13 | 结构化输出 | 非流式调用输出标准 JSON，支持单对象和泛型集合 | [13-结构化输出](docs\u002Fcore\u002F13-结构化输出.md) |\n| 14 | 综合示例 | Skills + HITL + 分阶段输出完整示例 | [14-综合示例](docs\u002Fcore\u002F14-综合示例.md) |\n| 15 | DeepSeek-V4 兼容 | reasoning_content 回传兼容性修复与使用指南 | [15-DeepSeek-V4兼容](docs\u002Fcore\u002F15-DeepSeek-V4兼容.md) |\n\n---\n\n## 示例参考（Samples）\n\n项目提供了完整的示例代码，位于 `spring-ai-agentx-samples` 模块，可直接运行体验各功能。\n\n### 配置\n\n示例需要真实 API Key 和数据库连接。首次运行前复制配置模板并填入真实值：\n\n```bash\ncd spring-ai-agentx-samples\u002Fsrc\u002Fmain\u002Fresources\ncp secrets.properties.example secrets.properties\n# 编辑 secrets.properties，填入真实配置\n```\n\n- `secrets.properties.example` — 模板文件（仅占位符），提交到 Git\n- `secrets.properties` — 真实配置，已在 `.gitignore` 中排除，不提交\n\n### 示例列表\n\n| 示例类 | 涵盖功能 | 说明 |\n|--------|---------|------|\n| `RunnableParamsTest` | 运行时参数注入 | addParam \u002F addToolParam 参数覆盖 |\n| `AgentSkillsTest` | Skills 技能体系 | 技能加载与多技能组合 |\n| `TaskManagerTest` | 任务管理与并发控制 | 会话级并发控制与中断 |\n| `RetryErrorTest` | 异常处理与重试 | 重试机制与错误码处理 |\n| `HumanInTheLoopTest` | Human-in-the-Loop | 暂停\u002F恢复、ask_user、操作审批 |\n| `StageOutputTest` | 分阶段输出 | StageOutputProvider、多时机钩子、Think 标签 |\n| `ThinkingModeTest` | 思考模型适配 | REASONING_CONTENT \u002F THINK_TAG \u002F DISABLED 三种模式 |\n| `MemoryTest` | 分层记忆体系 | 短期记忆、用户画像、长期记忆 |\n| `ContextManagementTest` | 上下文压缩 | 默认配置、自定义配置、保护工具 |\n| `FullIntegrationTest` | 完整集成 | 三层记忆 + Skills + 全量工具 |\n| `ToolSearchTest` | ToolSearch 工具检索 | 同步\u002F流式调用、Session 隔离验证 |\n| `StructuredOutputTest` | 结构化输出 | call\u002FcallForResult 单对象与集合输出 |\n\n> 各示例内部通过 `testNumber` 切换测试场景，修改后直接运行 `main` 方法即可。\n\n---\n\n## 版本发布\n\n| 版本 | 状态 | 说明 |\n|------|------|------|\n| [v1.0.0-M1](#v100-m1当前版本) | 当前版本 | 首个里程碑版本，ReAct 引擎 + 分层记忆 + 工具调度 + 思考模型适配 + DeepSeek-V4 兼容等核心能力 |\n\n## 版本路线图\n\n### v1.0.0-M1（当前版本）\n\n- [x] ReAct Agent 引擎 — 基于 Reasoning + Acting 范式的多轮执行闭环\n- [x] 同步调用与流式输出 — call \u002F stream 双模式，流式基于 Reactor Flux\n- [x] 统一工具调度 — 原生支持 Function Calling \u002F MCP，框架统一接管执行\n- [x] 运行时参数注入 — RunnableParams 动态覆盖工具参数\n- [x] 任务管理与执行控制 — 会话级并发控制与中断机制\n- [x] 分层记忆体系 — 短期记忆、用户画像、长期记忆（RAG）\n- [x] Human-in-the-Loop — Agent 主动提问与操作审批，暂停\u002F恢复执行\n- [x] 阶段式输出 — StageOutputProvider SPI，三种钩子时机\n- [x] 内置工具能力集 — Bash、文件系统、Grep、Python\n- [x] Skills 技能体系 — 渐进式披露，按需加载\n- [x] 思考模型适配 — `ThinkingMode` 枚举统一 THINK_TAG \u002F REASONING_CONTENT \u002F DISABLED 三种模式\n- [x] DeepSeek-V4 兼容 — 内置 `DeepSeekV4ChatModel`，解决思考模式 + 工具调用兼容性问题\n- [x] 异常处理与重试 — 内置透明重试机制，AgentException + AgentErrorCode\n- [x] 上下文压缩 — 两层自动压缩策略，控制 Token 消耗\n- [x] ToolSearch 工具检索 — 工具按需发现，keyword + LLM 双模式搜索\n- [x] 结构化输出 — 非流式调用输出标准 JSON，支持单对象和泛型集合\n\n### v1.0.0-M2（规划中）\n\n- [ ] todowrite — 复杂的多步骤任务，保证智能体不会遗漏任何步骤\n- [ ] SubAgent 机制（Agent Tools） — 将 Agent 封装为另一个 Agent 的工具\n- [ ] 后置任务校验机制 — 任务完成后引入模型校验或规则校验\n\n### v1.0.0-M3（规划中）\n\n- [ ] 执行沙箱 — 为工具调用与代码执行提供隔离运行环境\n- [ ] Plan & Execute 架构 — 在 ReAct 基础上引入显式规划阶段\n- [ ] Agent Teams — 多 Agent 按角色协同\n\n### v1.0.0-GA（远期规划）\n\n- [ ] 可观测性体系 — 全链路追踪，支持接入 Langfuse 等观测系统\n- [ ] 外部记忆系统对接 — 支持 mem0 等外部长期记忆系统\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n","Spring AI AgentX 是一个基于原生 Spring AI 的智能体（Agent）开发框架，旨在帮助开发者快速构建功能丰富的 AI Agent。它提供了 ReAct 执行引擎、分层记忆、工具调度和 Human-in-the-Loop 等核心能力，形成了一套完整的 Harness Engineering 方案。该框架基于 Spring AI 和 Reactor 构建，不引入额外的抽象层，支持同步与流式输出，并且天然适配 WebFlux 等异步场景。Spring AI AgentX 适合于需要在 Java 环境中快速搭建类似 Claude Code 的 AI Agent 应用场景，尤其适用于那些希望专注于业务逻辑而不需要从头开始构建复杂 AI 交互机制的开发者。",2,"2026-06-11 04:05:59","CREATED_QUERY"]