How to Set Up JoyAgent‑JDGenie on macOS – Lesson 1

JoyAgent‑JDGenie is JD's open‑source general‑agent framework hosted at https://github.com/jd-opensource/joyagent-jdgenie (725 stars as of July 2025). It provides a lightweight, high‑completion multi‑agent product comparable to other general‑agent efforts such as ByteDance’s 扣子空间, OpenManus, Suna, JManus, and ChatGPT Agent.

Core capabilities

Multi‑mode agent support – includes ReAct and plan‑executor patterns.

Multi‑level reasoning – combines work‑level and task‑level problem solving.

High‑concurrency DAG execution engine – processes directed acyclic graphs for efficient execution.

Cross‑task workflow memory – retains context across similar tasks to improve performance.

Real‑time stream output – uses Server‑Sent Events (SSE) to deliver agent thoughts, plans, and results.

Tool evolution and integration

Pluggable agents and tools with an extensible architecture.

Support for HTML, PowerPoint, and Markdown output formats.

Automatic tool generation by composing existing atomic tools.

Custom tool integration via the BaseTool interface.

Built‑in agent types

Planning agent – creates and manages task execution plans.

Executor agent – performs specific tool calls and operations.

ReAct agent – implements reasoning‑and‑action loops for complex problem solving.

Summary agent – generates comprehensive task summaries and reports.

Local testing showed that the reasoning process follows the ReAct pattern even when a non‑thinking model is used.

System architecture

The backend is a Java Spring Boot application (SpringBoot 3.2.2, OpenJDK 17) that orchestrates two Python services: genie-client (MCP client) and genie-tool (tool service). The frontend is built with React, Vite, Node.js, and Ant Design. All services are coordinated by the start_genie.sh script, exposing the UI on port 3000 and the backend API on port 8080.

Environment prerequisites

Node.js and pnpm for the frontend.

Java 17 and Maven for the backend.

Python 3.11 with UV for the Python services.

An AI large‑model service compatible with OpenAI API.

MCP Server instances for specialized testing.

Frontend setup

registry=https://registry.npmmirror.com/

pnpm install

pnpm run dev

Java backend setup

Import the project into an IDE (e.g., IntelliJ IDEA), configure Maven, and edit application.yml to set the model name and endpoint. Start the Spring Boot application from the IDE.

Python services setup

pip install uv

cd joyagent-jdgenie/genie-tool
uv sync
source .venv/bin/activate

OPENAI_API_KEY=xxxxxx
OPENAI_BASE_URL=xxxxxx

python -m genie_tool.db.db_engine

uv run python server.py

MCP service setup

cd joyagent-jdgenie/genie-client
uv venv
source .venv/bin/activate
sh start.sh

After all services start, the UI is reachable at http://localhost:3000. In document mode, questions can be submitted to verify functionality. To connect a custom MCP service, modify mcp_server_url in application.yml (e.g., mcp_server_url: "http://ip1:port1/sse,http://ip2:port2/sse").

The provided steps reproduce a working JoyAgent‑JDGenie environment on macOS, demonstrating the feasibility of building and experimenting with a general AI agent framework.