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

原创秋山墨客 2025-07-24 08:30 江苏

体验京东开源通用智能体项目JDGenie

?k=defb30c8&u=https%3A%2F%2Fmmbiz.qpic

点击上方

蓝字

关注我们

?k=c4576a99&u=https%3A%2F%2Fmmbiz.qpic

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

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

项目原理与架构
本地部署与测试
二次开发与扩展
总结

项目原理与架构

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

?k=4b0100b5&u=https%3A%2F%2Fmmbiz.qpic

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

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

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

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

?k=ae476e45&u=https%3A%2F%2Fmmbiz.qpic

要点如下：

每个Agent配备必要的工具（Tools），比如规划、文件管理、搜索、报告、编码。
支持直接的ReAct （边想边做）和 Plan-and-Executor（想好再做）的智能体工作范式；事实上两者也是协作的：规划（Plan）的某个任务步骤在执行（Execute）时可能又是ReAct的模式。
所有Agent共享上下文，包括Memory（任务历史）、Files（中间文件结果）、Tools（工具）、Config（配置）等；任务与工具支持并发方式执行，以最大化智能体的能力并提高响应性能。

?k=a79d6101&u=https%3A%2F%2Fmmbiz.qpic

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

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

本地工具：目前预置code（写代码）、deepsearch（深度搜索）、report（报告）、file（文件管理）等，涵盖了从文本处理、信息检索到格式化输出的常见需要。
MCP工具：支持连接到配置好的MCP Servers，加载其开放的工具；并仍然以FastAPI方式公开给智能体层使用。（Agent不直接访问MCP Server）

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

?k=ca5da788&u=https%3A%2F%2Fmmbiz.qpic

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

本地部署与测试

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

【1. 代码下载】

克隆项目代码：

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

需要的基本环境如下：

Java：JDK 17
Python：python 3.11+
Node.js：Node.js 16（用于前端UI项目）
依赖管理工具：Maven, uv/pip, pnpm

【2. 启动UI模块】

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

pnpm install
pnpm run dev

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

?k=14c8deed&u=https%3A%2F%2Fmmbiz.qpic

【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 sync
source .venv/bin/activate
python -m genie_tool.db.db_engine(首次启动需要）
./start.sh(或uv run server.py)

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

?k=42a63c71&u=https%3A%2F%2Fmmbiz.qpic

【5. 启动MCP工具】

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

uv venv
source .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工具形式的好处）：

?k=7d995bdd&u=https%3A%2F%2Fmmbiz.qpic

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

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

?k=e7a96797&u=https%3A%2F%2Fmmbiz.qpic

【踩坑记录】

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

智能体的任务编排与规划非常依赖于LLM。如果你无法取得预期行为（比如不调用某个工具），可以先尝试更换LLM或者调整提示词（application.yml中）
确保搜索引擎API的并行可用。系统默认的搜索会借助LLM进行“扩展深度搜索”，且采用了并行，要小心你使用的搜索API是否有限制，否则可能无法搜出结果

二次开发与定制

实际开发中，你可以基于 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());

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

总结

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

相较许多只提供框架或协议的项目，JDGenie 将前后端、工具和智能体完整打包，开箱即用且支持扩展。
多智能体架构。结合多种智能体设计模式（Plan-and-Executor与ReAct），支持多层级的规划和思考（Work级与Task级别）。
GAIA 基准测试中，其综合准确率达到较高的水平。在我们的体验过程中，整体上Agent运行比较稳定，虽然并非每次都能输出完全符合期望的结果，但这通常也和使用的LLM、搜索引擎等有一定关系，需要进一步的微调。
项目有良好的层次与模块化设计，易于理解与二次开发，有的模块如genie-tool也可以作为单独项目应用。各个层次的功能与接口清晰，也有着较好的扩展能力，比如借助MCP的工具扩展。相信未来在可扩展性上还会有更多演进。