京东开源轻量化通用Agent产品 jdgenie，开箱即用！二次开发及踩坑指南

今天来体验一个新的开源智能体项目：JoyAgent-JDGenie，来自京东开源的端到端多智能体系统（Multi-Agent System）。与传统仅提供SDK或框架的智能体方案不同，它定位为产品级的多智能体协同系统，开箱即用且支持轻量化本地部署 。

用户只需输入自然语言的任务描述，系统就能自动组织多个子智能体协同工作并输出结果（如分析报告、代码片段或PPT文档），打通从任务输入到结果输出的“最后一公里” 。你可以在其基础上进行二次开发与扩展，形成自己的定制化智能体产品。

• 项目原理与架构

• 本地部署与测试

• 二次开发与扩展

• 总结

01

项目原理与架构

开源的JoyAgent-JDGenie项目整体架构大致如下：

这是一个包含前后端的端到端智能体系统。主要组成如下：

• 前端交互层（UI ）：基于 React 实现的人机交互界面，支持用户输入自然语言请求，并实时展示任务过程与结果 。用户可以通过网页直接与智能体系统对话，获取报告、答案等输出。

• 后端智能体层（Backend）：Java构建，负责接收前端请求、调用多智能体引擎以及整合使用后端的各类工具，并协调处理工具与各智能体的响应。

  这是系统的核心层次，也是一个多智能体的执行引擎与任务的核心调度模块。当前版本主要依赖于以下几种Agent的协作来完成任务的规划、拆解与执行。

要点如下：

• 每个Agent配备必要的工具（Tools），比如规划、文件管理、搜索、报告、编码。

• 支持直接的ReAct （边想边做）和 Plan-and-Executor（想好再做）的智能体工作范式；事实上两者也是协作的：规划（Plan）的某个任务步骤在执行（Execute）时可能又是ReAct的模式。

• 所有Agent共享上下文，包括Memory（任务历史）、Files（中间文件结果）、Tools（工具）、Config（配置）等；任务与工具支持并发方式执行，以最大化智能体的能力并提高响应性能。

官方架构说明中的智能体层，但与当前版本有一定出入

• 工具层（Tools）：用来给智能体提供各种工具。在本项目中工具层统一以FastAPI的方式提供，可以通过FastAPI的docs查看工具列表和规格。工具分两种：

• 本地工具：目前预置code（写代码）、deepsearch（深度搜索）、report（报告）、file（文件管理）等，涵盖了从文本处理、信息检索到格式化输出的常见需要。

• MCP工具：支持连接到配置好的MCP Servers，加载其开放的工具；并仍然以FastAPI方式公开给智能体层使用。（Agent不直接访问MCP Server）

官方说明中有更多工具方面的规划，比如工具的组合与拆解：

但目前版本还没有看到太多这方面特性的展示。

02

本地部署与测试

按照如下步骤，我们将该项目在本地部署并启动测试。我们采用直接从源代码开始、并分模块逐个启动的方式：

【1. 代码下载】

克隆项目代码：

git clone https://github.com/jd-opensource/joyagent-jdgenie.gitcd joyagent-jdgenie

需要的基本环境如下：

• Java：JDK 17

• Python：python 3.11+

• Node.js：Node.js 16（用于前端UI项目）

• 依赖管理工具：Maven, uv/pip, pnpm

【2. 启动UI模块】

该项目位于UI子目录中，进入该目录后执行如下命令启动开发Server：

pnpm installpnpm run dev

现在你应该可以访问http://localhost:3000/，并看到如下界面：

【3. 启动智能体层】

智能体层位于genie-backend目录中，进入该目录中，完成如下工作：

配置模型：首先找到src/main/resources目录中的application.yml配置文件，对其中的llm（大模型），以及各个agent使用的模型进行配置。其他部分默认即可。

项目Build：运行genie-backend目录下的build.sh脚本即可。如果出现错误，注意检查JDK版本。

项目启动：最后运行目录下的start.sh脚本，或如下命令启动：

echo "启动 genie-backend..."java -jar ./target/genie-backend-0.0.1-SNAPSHOT.jar \    --spring.profiles.active=local \    --logging.file.name=./genie-backend.log \    --server.port=8080

【4. 启动本地工具】

本地工具位于genie-tool目录，进入该目录中，完成：

配置环境：从.env_template复制出一个.env文件，然后对其中少量参数配置。这里仍然是LLM的配置，以及使用的几个搜索引擎。请根据自己实际情况配置即可；

安装、初始化与启动

uv syncsource .venv/bin/activatepython -m genie_tool.db.db_engine(首次启动需要）./start.sh(或uv run server.py)

如果看到下面的输出画面，就代表启动成功：

【5. 启动MCP工具】

最后启动连接远程MCP Server的FastAPI服务器，进入genie-client目录。执行：

uv venvsource .venv/bin/activate./start.sh(或uv run server.py）

注意，本项目默认使用了一个远程MCP Server，但其地址并非在genie-client项目中配置，而是在智能体层（genie-backend项目）的application.yml文件中配置（找到mcp_server_url参数）。

【6. 测试】

如果上述步骤都成功完成，一般就可以正常运行。你也可以对工具层做单独测试，因为它们都是FastAPI服务。比如访问http://localhost:1601/docs#/，可以看到其中的工具并独立测试（这也是采取FastAPI工具形式的好处）：

如果访问http://localhost:8188/docs，则可以测试远程的MCP工具。

现在可以直接在主界面输入任务测试！比如规划一个假期旅行；接着你可以看到Agent的工作进展，而界面右边则是工作空间，用来展示各种格式的工作成果输出。你可以要求用网页、Word、PPT等多种方式输出任务结果：

【踩坑记录】

项目启动并不复杂，但是在第一次运行时未必能取得预期的结果，以下是两个需要注意的“坑”：

• 智能体的任务编排与规划非常依赖于LLM。如果你无法取得预期行为（比如不调用某个工具），可以先尝试更换LLM或者调整提示词（application.yml中）

• 确保搜索引擎API的并行可用。系统默认的搜索会借助LLM进行“扩展深度搜索”，且采用了并行，要小心你使用的搜索API是否有限制，否则可能无法搜出结果

03

二次开发与定制

实际开发中，你可以基于 JDGenie 定制垂直领域的多智能体应用。目前主要支持工具的扩展，有两种方式，一种是通过MCP Server扩展，一种是直接在智能体层注册添加自定义工具。

比如你需要添加一个Tool用来比较两个产品的参数，并生成易于理解的对比结果。

• 方式A：对接外部的MCP Server – 可以将工具逻辑封装到一个MCP Server，并通过 JDGenie 的 MCP 接口挂载进来。具体做法是在智能体层的配置文件中添加该MCP Server地址：在 genie-backend/src/main/resources/application.yml 中加入如下配置 （模拟）：

mcp_server_url: "http://<你的MCP Server>:<端口>/mcp"

通过上述配置，JDGenie 的引擎在需要时会调用指定的 MCP  Tool。这种插件式集成非常简便且无侵入性：只需提供符合协议的MCP Server并配置URL。

• 方式B：也可以直接在 JDGenie 内部新增工具来扩展功能，只需实现 BaseTool 接口并注册这个工具即可 。比如创建一个 ProductCompareTool 类，用 Java 编写如下逻辑（模拟）：

public class ProductCompareTool implements BaseTool {    @Override public String getName() { return "agent_product_compare"; }      @Override public String getDescription() { return "查询并比较两个商品信息"; }    @Override public Map<String, Object> toParams() {        // 定义工具接受的参数：两个商品名称        return Map.of("type","object","properties", Map.of(                      "product1", Map.of("description","商品1名称","type","string"),                      "product2", Map.of("description","商品2名称","type","string")                 ),                 "required", List.of("product1","product2"));    }    @Override public Object execute(Object input) {        // 在这里调用商品API或数据库，获取product1和product2的信息        // 简化处理：假设已得到两个商品的price和spec信息        Map info = fetchProductInfo((Map)input);         return compareProducts(info);    }}

接着将此自定义工具注册到系统中即可：只需在智能体层的工具准备方法中（对应GenieController.java文件中的buildToolCollection方法）添加一行注册代码 ：

toolCollection.addTool(new ProductCompareTool());

保存后重启服务，剩余的工作由引擎自动协调完成。

04

总结

整体上看，作为开源项目的JoyAgent-JDGenie具有较为鲜明的特点：

• 相较许多只提供框架或协议的项目，JDGenie 将前后端、工具和智能体完整打包，开箱即用且支持扩展。

• 多智能体架构。结合多种智能体设计模式（Plan-and-Executor与ReAct），支持多层级的规划和思考（Work级与Task级别）。

•  GAIA 基准测试中，其综合准确率达到较高的水平。在我们的体验过程中，整体上Agent运行比较稳定，虽然并非每次都能输出完全符合期望的结果，但这通常也和使用的LLM、搜索引擎等有一定关系，需要进一步的微调。

• 项目有良好的层次与模块化设计，易于理解与二次开发，有的模块如genie-tool也可以作为单独项目应用。各个层次的功能与接口清晰，也有着较好的扩展能力，比如借助MCP的工具扩展。相信未来在可扩展性上还会有更多演进。

当然，由于是刚发布的版本，在很多功能上还有所缺失，比如多模态支持、输入文件处理、以及一些在官方说明中的能力也尚未完全交付，期望后面的版本迭代能够带来更多的惊喜。

如何学习AI大模型 ？

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。【保证100%免费】🆓

优快云粉丝独家福利

这份完整版的 AI 大模型学习资料已经上传优快云，朋友们如果需要可以扫描下方二维码&点击下方优快云官方认证链接免费领取 【保证100%免费】

读者福利： 👉👉优快云大礼包：《最新AI大模型学习资源包》免费分享 👈👈

（👆👆👆安全链接，放心点击）

对于0基础小白入门：

如果你是零基础小白，想快速入门大模型是可以考虑的。

一方面是学习时间相对较短，学习内容更全面更集中。
二方面是可以根据这些资料规划好学习计划和方向。

👉1.大模型入门学习思维导图👈

要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。

对于从来没有接触过AI大模型的同学，我们帮你准备了详细的学习成长路线图&学习规划。可以说是最科学最系统的学习路线，大家跟着这个大的方向学习准没问题。（全套教程文末领取哈）

👉2.AGI大模型配套视频👈

很多朋友都不喜欢晦涩的文字，我也为大家准备了视频教程，每个章节都是当前板块的精华浓缩。

👉3.大模型实际应用报告合集👈

这套包含640份报告的合集，涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师，还是对AI大模型感兴趣的爱好者，这套报告合集都将为您提供宝贵的信息和启示。（全套教程文末领取哈）

👉4.大模型实战项目&项目源码👈

光学理论是没用的，要学会跟着一起做，要动手实操，才能将自己的所学运用到实际当中去，这时候可以搞点实战项目来学习。（全套教程文末领取哈）

👉5.大模型经典学习电子书👈

随着人工智能技术的飞速发展，AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型，如GPT-3、BERT、XLNet等，以其强大的语言理解和生成能力，正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。（全套教程文末领取哈）

👉6.大模型面试题&答案👈

截至目前大模型已经超过200个，在大模型纵横的时代，不仅大模型技术越来越卷，就连大模型相关的岗位和面试也开始越来越卷了。为了让大家更容易上车大模型算法赛道，我总结了大模型常考的面试题。（全套教程文末领取哈）

为什么分享这些资料?

只要你是真心想学AI大模型，我这份资料就可以无偿分享给你学习，我国在这方面的相关人才比较紧缺，大模型行业确实也需要更多的有志之士加入进来，我也真心希望帮助大家学好这门技术，如果日后有什么学习上的问题，欢迎找我交流，有技术上面的问题，我是很愿意去帮助大家的！

这些资料真的有用吗?

这份资料由我和鲁为民博士共同整理，鲁为民博士先后获得了北京清华大学学士和美国加州理工学院博士学位，在包括IEEE Transactions等学术期刊和诸多国际会议上发表了超过50篇学术论文、取得了多项美国和中国发明专利，同时还斩获了吴文俊人工智能科学技术奖。目前我正在和鲁博士共同进行人工智能的研究。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

优快云粉丝独家福利

这份完整版的 AI 大模型学习资料已经上传优快云，朋友们如果需要可以扫描下方二维码&点击下方优快云官方认证链接免费领取 【保证100%免费】

读者福利： 👉👉优快云大礼包：《最新AI大模型学习资源包》免费分享 👈👈

（👆👆👆安全链接，放心点击）