手把手教你本地部署！京东JoyAgent全攻略：从零拥有一个企业级的AI Agent

今年世界人工智能大会（WAIC 2025）最让人兴奋的，不是又多了几个参数惊人的大模型。当你看遍800家企业的展台、上百种机器人后，那个最强烈的感受会告诉你：AI，终于不“飘”在天上了。一股“深度应用”的浪潮，正让技术真正落地，创造价值。

它不再是隔空炫技，而是真的被用起来了，实实在在地解决着问题。

在加速产业走向AI深度应用这条道路上，国内巨头京东无疑按下了“加速键”。大会期间，京东不仅将其大模型品牌全面升级为JoyAI，更向全球开发者亮出了一张源自复杂业务场景的王牌——正式开源其企业级多智能体平台 JoyAgent-JDGenie。

它致力于解决开发者快速构建多智能体应用的“最后一公里”问题，其核心理念是提供一个端到端的、轻量化的完整产品，而非仅仅是一个SDK或框架。

本文将为你详细解读这款“开箱即用”的多智能体产品的核心能力，并提供完整的本地部署教学，带你全面拥抱这个强大的AI Agent工具👇

01 | JoyAgent-JDGenie：企业级多智能体“全能选手”

JoyAgent-JDGenie 是京东JoyAI大模型体系下的核心产品。不同于许多依赖特定云生态（如阿里云百炼、火山引擎）的工具，它是一个相对轻量且完整的解决方案。它不仅在GAIA等权威榜单上性能超越众多知名产品，更重要的是，它源自于京东在零售、物流、供应链等真实、严肃且复杂场景中的大规模实践。

✅ 端到端完整产品： 开箱即用，对于输入的任务（如“给我做一个最近美元和黄金的走势分析”），可以直接生成网页或PPT报告，而非仅提供开发框架。

✅ 100%全栈开源： 完整开源了前端、后端、框架、引擎及核心子智能体（报告生成、代码、PPT、文件处理等），赋予开发者极高的自由度和二次开发能力。

✅ 轻量化与高兼容性： 无需强制绑定特定云服务，可与多种模型（如DeepSeek）轻松集成，部署更灵活。

✅ 经过实战检验： 已在京东内部超过1.4万个智能体的庞大规模下得到验证，保证了其在复杂场景下的稳定性和可靠性。

✅ 其核心优势清单如下

• 支持多种智能体设计模式（React模式、Plan-and-Executor模式等）。
• 具备高并发的DAG（有向无环图）执行引擎，实现极致的执行效率。
• 子智能体（Agent）和工具可轻松插拔、自由扩展。
• 支持HTML、PPT、Markdown等多种格式的文件交付。
• 具备跨任务级别的记忆能力（Cross task workflow memory）。

02 | 上手实践：本地部署 JoyAgent-JDGenie

现在，让我们动手将JoyAgent-JDGenie完整部署到本地。

✅ 部署指南（一）：Docker 一键启动 (推荐)

1. 1. 准备工作：

• 硬件：CPU 2核及以上，内存 4GB及以上。
• 软件：安装好 Docker 并启动服务。
• 2. 获取源码：
git clone https://github.com/jd-opensource/joyagent-jdgenie.git
cd joyagent-jdgenie

1. 3. 配置模型服务：
• 后端配置： 手动更新 genie-backend/src/main/resources/application.yml 文件，填入你的大模型 base_url, apikey, 和 model 等信息。
• 工具配置： 手动更新 genie-tool/.env_template 文件，填入如 OPENAI_API_KEY, SERPER_SEARCH_API_KEY 等（如果使用DeepSeek，则配置 DEEPSEEK_API_KEY 等）。
• 4. 构建镜像：
docker build -t genie:latest .

1. 5. 启动与访问：
docker run -d -p 3000:3000 -p 8080:8080 -p 1601:1601 --name genie-app genie:latest

1. 6. 部署成功后，通过浏览器访问 http://localhost:3000/ 即可。

部署若遇问题，可参考官方视频：【5分钟使用deepseek启动开源智能体应用joyagent-genie-哔哩哔哩】 https://b23.tv/8VQDBOK

---

✅ 部署指南（二）：手动启动服务

---

方案A：一键脚本启动 (推荐)

1. 1. 环境准备： 确保已安装 JDK 17 和 Python 3.11。
2. 2. 执行脚本： 在项目根目录下，依次执行：
# 1. 检查所有依赖和端口占用情况
sh check_dep_port.sh

# 2. 一键启动所有服务
sh Genie_start.sh

提示： 这种方式最便捷。使用 control+c 可一键停止所有相关服务。

---

方案B：手动分步启动 (适用于问题排查) 此方案需要手动启动四个服务：前端、后端、Tools 和 MCP。

---

Step 1: 环境准备：

• Java > 17: 确保已安装并正确配置 JAVA_HOME 环境变量。
• pnpm > 7: 用于安装前端依赖。安装方法见 pnpm官网 https://pnpm.io/zh/installation。
• Python (推荐3.11): 用于启动工具服务。

---

Step 2: 启动前端服务 (UI)

• 打开一个新终端：
cd joyagent-jdgenie/ui
sh start.sh

• 当看到 Local: http://localhost:3000/ 输出时，表示前端启动成功。

---

Step 3: 启动后端服务 (Backend)

• 另外打开一个终端：
cd joyagent-jdgenie/genie-backend
sh build.sh
sh start.sh

• 当看到 [INFO] BUILD SUCCESS 时表示编译成功。你可以通过 tail -f genie-backend_startup.log 查看日志。

---

Step 4: 启动Tools服务

• 另外打开一个终端：
cd joyagent-jdgenie/genie-tool
pip install uv
uv sync
source .venv/bin/activate

• 首次启动需执行以下命令初始化数据库：
python -m genie_tool.db.db_engine

• 配置环境变量并启动服务：
cp .env_template .env
# 编辑 .env 文件, 填入你的 SERPER_SEARCH_API_KEY 等
uv run python server.py

---

Step 4: 启动MCP服务

• 另外打开一个终端：
cd joyagent-jdgenie/genie-client uv venv source .venv/bin/activate sh start.sh

---

03 | 进阶玩法：二次开发与定制

---

JoyAgent-JDGenie 的强大之处在于其高度的可扩展性。你可以轻松添加外部工具或创建全新的自定义智能体。

---

✅ 如何添加外部MCP工具？

1. 1. 修改配置文件：

   mcp_server_url: "http://ip1:port1/sse,http://ip2:port2/sse"

• （可选）在 ui/.env 文件中，可以修改前端请求后端的路径。
• 在 genie-backend/src/main/resources/application.yml 文件中，添加你的 mcp_server 服务地址，多个地址用逗号分隔。
• 2. 重启服务：
sh start_genie.sh

1. 3. 开始对话：

例如，添加一个12306查票工具后，你可以提问：“规划7月7天2人从北京出发去新疆的旅行计划，并查询相关火车票信息”。Genie在规划后会自动调用你新增的MCP工具查询车票，并最终输出完整报告。



---

✅ 如何新增自定义子Agent？

1. 1. 实现BaseTool接口：
• 创建一个Java类，实现 BaseTool 接口，并定义工具的名称、描述、参数和核心执行逻辑。
/**
 * 工具基接口
 */public interface BaseTool {
    String getName(); // 工具名称String getDescription(); // 工具描述MaptoParams(); // 工具参数Object execute(Object input); // 调用工具
}

// 天气智能体示例public class WeatherTool implements BaseTool {
    @Overridepublic String getName() {
        return "agent_weather";
    }

    @Overridepublic String getDescription() {
        return "这是一个可以查询天气的智能体";
    }

    @Overridepublic MaptoParams() {
        return "{\"type\":\"object\",\"properties\":{\"location\":{\"description\":\"地点\",\"type\":\"string\"}},\"required\":[\"location\"]}";
    }

    @Overridepublic Object execute(Object input) {
        return "今日天气晴朗";
    }
}

1. 2. 注册新的Agent：
• 在 com.jd.genie.controller.GenieController#buildToolCollection 方法中，添加代码来引入你的自定义Agent。
WeatherTool weatherTool = new WeatherTool();
toolCollection.addTool(weatherTool);

1. 3. 重启服务：
sh start_genie.sh

---

小结

回归本文的起点，AI的价值在于“深度应用”。JoyAgent-JDGenie正是为此而生的实践产物。通过本文的介绍，我们可以清晰地看到它的核心价值所在：

首先，它是一个经过实战检验、开箱即用的完整产品。这解决了许多开源项目停留在框架或SDK层面，开发者仍需大量工作的痛点。其源自京东复杂业务的背景，是其稳定可靠的最好背书。

其次，它为开发者提供了全面的灵活性和掌控力。从最简单的Docker部署，到推荐的一键脚本，再到用于精细化排错的分步启动，不同的部署方式满足了从快速体验到深度开发的全方位需求。

最后，它拥有一个强大且易于扩展的内核。无论是通过配置接入外部MCP工具，还是通过实现BaseTool接口用Java创造全新的原生智能体，都展示了其作为平台“基座”的强大潜力。

总而言之，JoyAgent-JDGenie通过提供一个真正完整、灵活且可扩展的开源产品，切实降低了高质量AI Agent的开发门槛，让每一个开发者都能更专注于业务创新本身。

---

📌 从阅读到实践，我们与你同行

今天的分享暂告一段落。

我们深知，将一个系统化的方法应用到具体工作中并非易事。希望你能大胆尝试，持续迭代，亲手打造出解决你真实痛点的业务系统。

这条路你不是一个人在走。实践中若有困惑或心得，欢迎在评论区分享，我们更诚邀您根据自己需求通过以下方式加入幻象AI智能体共学社区系列社群，与更多优秀的实践者一同成长。



---

🚀 学习升级：我们把知识库，变成了你的专属AI

从阅读到实践，最大的挑战莫过于将海量信息内化为自己的能力。收藏夹里的文章越来越多，真正用到的却寥寥无几。

为了彻底解决这个问题，我们不止是建立了一个社群。我们更进一步，为你打造了一个会“说话”的AI知识库——幻象AI智能体共学社区 ima 知识库。欢迎扫码加入~



在这里，你无需再费力地一篇篇翻阅文档。遇到任何问题，你都可以直接向AI提问。

它被投喂了我们为你精选的、并持续更新的全部内容（如下图所示），能基于这些高质量信息，精准回答你的问题，成为你7x24小时在线的AI学习搭档。



无论是想了解最新的行业报告，还是查询某个AI案例的具体细节，你都可以通过对话，让AI帮你快速定位、总结、提炼。

这，才是AI时代最高效的学习方式。

---

社群里每天都有无数新想法，但99%都止步于畅聊。 如何成为那1%的行动派，让好想法真正落地？

公众号置顶文章，说透了我们“从想法到现实”的完整路径和方案。点击了解详情 👉《关于我们的共学社区和398元永久会员，想和你聊些实在的》

---

🎉 周年庆福利：会员权益即将升级！

值此团队成立一周年之际，为回馈广大会员的支持与厚爱，我们计划将于 今年8月 对会员权益进行重要升级。具体更新如下



---

✍️ 社群小公约

为了保障高质量的交流环境，群内禁止未经许可的广告，尤其禁止无官方认证的AI课程、考证等信息。违规发布者将被移出群聊，感谢大家的理解与配合。

---

期待你的加入！在群里，我们不止分享方法，更希望链接每一位有趣的思考者。

---

写在最后

Agent的赛道从不缺少新奇的创意，但将创意变为稳定、可靠、能在真实业务中创造价值的产品，却是一条充满挑战的工程之路。许多探索止步于“能用”，却难以达到“好用”和“敢用”的工业级标准。

在这样的背景下，JoyAgent-JDGenie的开源，提供了一种不同的思路：技术从最复杂的产业实践中来，再以更成熟、更完整的形态回馈给产业。 它所开放的，不仅仅是代码，更是经过海量业务捶打后的架构、协议与工程智慧。

这种源于实践的开源，将曾专属于少数大型企业内部、用以解决核心业务流程的“重武器”，带到了每一位开发者的面前。这从根本上降低了“深度应用”的门槛，让每一个有价值的想法，都有了被快速落地并推向市场的可能。

这不仅是技术的开放，更是工程能力的平权。

Agent 时代，属于每一位创造者。