If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jd-opensource/joyagent-jdgenie shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3mo ago
• 14 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jd-opensource/joyagent-jdgenie repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jd-opensource/joyagent-jdgenie.

What it runs against: a local clone of jd-opensource/joyagent-jdgenie — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jd-opensource/joyagent-jdgenie | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch data_agent exists | Catches branch renames | | 4 | Last commit ≤ 115 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jd-opensource/joyagent-jdgenie. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jd-opensource/joyagent-jdgenie.git
#   cd joyagent-jdgenie
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jd-opensource/joyagent-jdgenie and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jd-opensource/joyagent-jdgenie(\\.git)?\\b" \\
  && ok "origin remote is jd-opensource/joyagent-jdgenie" \\
  || miss "origin remote is not jd-opensource/joyagent-jdgenie (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify data_agent >/dev/null 2>&1 \\
  && ok "default branch data_agent exists" \\
  || miss "default branch data_agent no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 115 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~85d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jd-opensource/joyagent-jdgenie"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

JoyAgent-JDGenie is an end-to-end production-grade multi-agent system that solves complex tasks (data analysis, report generation, PPT creation, code execution) by orchestrating specialized sub-agents and tools. Users input natural language queries like 'analyze recent USD-gold trends' and receive complete deliverables (web reports, PowerPoint presentations) without intermediate development—it achieves 75.15% accuracy on GAIA Validation and 65.12% on GAIA Test, outperforming OWL, Smolagent, and AutoAgent. Monorepo structure: genie-backend/ contains Spring Boot 3.2.2 Java backend (main agent orchestration and REST API), with separate Python components (300K LOC) likely in subdirectories for LLM integration and data agents, and TypeScript/HTML/CSS frontend (175K TypeScript) in a sibling directory (not shown in file list but inferred from language stats). Sub-agents for reports, code, PPT, and files are mounted into the core orchestration engine.

Enterprise engineers and product teams building AI-powered applications who need a lightweight, self-hosted multi-agent framework (not dependent on cloud platforms like Aliyun or Volcano Engine). They want to plug in domain-specific agents and tools for internal knowledge management, table analysis, and structured/unstructured content handling without writing agent orchestration from scratch.

Production-ready with active development: the repo contains 521K Java + 300K Python LOC, deployed via Docker (Dockerfile present), includes comprehensive docs (README_DataAgent.md, README_mrag.md), and shows recent feature branches (data_agent, mrag). Test presence and CI setup not visible from file list, but the polish (Deploy.md, check_dep_port.sh, contributor guides) and GAIA benchmark results indicate mature, shipping code.

Low-to-moderate risk: single point of JD.com stewardship, large polyglot codebase (Java/Python/TypeScript) increases integration surface, last-commit visibility unclear from metadata. The mrag and data_agent branch strategy suggests active ongoing work, but multi-modal RAG features are still marked 'use mrag branch' indicating potential instability in main. No visible issue tracker or PR count limits risk assessment.

Active multi-modal expansion: mrag branch (multi-modal RAG for complex document handling) is released and documented; data_agent branch (DataAgent with DGP protocol, intelligent questioning, diagnostic analysis) is in active development; core agent framework receiving refinements. New release highlights knowledge management platform and structured table intelligence capabilities.

Clone the repo, then run the startup script: git clone https://github.com/jd-opensource/joyagent-jdgenie.git && cd joyagent-jdgenie && bash Genie_start.sh. Pre-requisites (ports, dependencies) are checked via bash check_dep_port.sh. Backend is Maven-based (mvn clean install in genie-backend/), frontend build mechanism inferred from TypeScript presence (likely npm/yarn).

Daily commands:

1. bash check_dep_port.sh to verify dependencies and port availability. 2. cd genie-backend && mvn clean install to build backend. 3. bash Genie_start.sh to start all services (backend API, Python agents, frontend dev server). Frontend likely runs on :3000, backend on :8080 (standard Spring Boot). Services interconnect locally; no cloud platform required.

• genie-backend/pom.xml: Maven build configuration for Spring Boot 3.2.2; defines all Java dependencies, compiler settings (Java 17), and module structure
• Genie_start.sh: Entry point script that orchestrates startup of all backend, Python agents, and frontend services
• check_dep_port.sh: Pre-flight check for system dependencies and required port availability; essential for local dev setup
• Dockerfile: Production containerization; shows how the full stack (backend, agents, frontend) is packaged for deployment
• README.md: Main documentation with architecture overview, GAIA benchmark results, and use-case examples
• README_DataAgent.md: Specific guide for structured table knowledge, data governance protocol (DGP), and intelligent Q&A capabilities
• README_mrag.md: Multi-modal RAG platform documentation for handling complex, unstructured documents (use with mrag branch)
• Deploy.md: Deployment and production setup guide; critical for understanding production configuration and scaling

For agent orchestration logic: modify genie-backend/src/main/java/com/example/joyagent/ (inferred structure based on Spring Boot convention). For new sub-agents: implement AgentInterface and register in the orchestration layer (look for AgentFactory or similar in core). For data-handling agents: use data_agent branch and DGP protocol helpers. For multi-modal RAG: use mrag branch. Frontend UI changes in the TypeScript/React tree (exact path not visible but standard React structure: src/components/, src/pages/). Add new tools in genie-backend/src/main/resources/tools/ or Python tools/ directory.

1. Branch-specific features: mrag and data_agent are separate branches (not main)—features documented in those READMEs only work on their respective branches. 2. Port availability: check_dep_port.sh must pass; common conflicts on :3000 (frontend), :8080 (backend), :5432 (database if used). 3. Python/Java bridge: polyglot codebase means Python agents must be discoverable at runtime; PATH and PYTHONPATH setup in Genie_start.sh is critical. 4. LLM provider config: no config file visible in listing—likely environment variables (LLM_API_KEY, LLM_MODEL, etc.) required in .env or system env; failure to set will cause agent execution to hang or fail silently. 5. Java 17 requirement: pom.xml locks to Java 17; older JDKs will fail compilation with cryptic errors.

• Multi-Agent Orchestration — JoyAgent's core—coordinating specialized agents (ReportAgent, CodeAgent, PPTAgent) to solve complex tasks; understanding agent composition and message routing is critical to extending the system
• Retrieval-Augmented Generation (RAG) — Both mrag (multi-modal RAG) and DataAgent rely on RAG patterns to ground LLM outputs in documents/tables; essential for knowledge management and accurate Q&A
• Tool Use / Function Calling — Agents invoke external tools (code execution, document parsing, data queries); understanding the tool interface and how LLMs choose tools is key to adding capabilities
• Agentic Reasoning / Chain-of-Thought — GAIA benchmark success (75.15% accuracy) stems from structured reasoning; agents decompose queries into sub-steps and call tools iteratively
• Data Governance Protocol (DGP) — DataAgent's innovation for structured table knowledge; DGP enforces schema validation and lineage tracking for intelligent data diagnostics and Q&A
• Polyglot Build and Runtime — 521K Java + 300K Python + 175K TypeScript requires coordinated build (Maven + pip/requirements.txt + npm) and process management; Genie_start.sh orchestrates this
• Containerized Multi-Service Deployment — Dockerfile packages the entire stack (Java backend, Python agents, TypeScript frontend) into one image; understand Docker multi-stage builds and port mapping for local dev and production

• langchain-ai/langchain — Similar agent orchestration framework; LangChain is likely used in genie-backend for LLM integration and tool chaining
• hwchase17/langchain-hub — Prompt templates and chain examples for agent reasoning; useful reference for adding new prompt strategies to JoyAgent sub-agents
• stanfordnlp/dspy — Declarative language model programming; alternative approach to agent instruction optimization, relevant for improving GAIA benchmark scores
• microsoft/autogen — Multi-agent conversation framework; AutoGen's agent-to-agent communication patterns are conceptually similar to JoyAgent's sub-agent orchestration
• openai/swarm — Lightweight agent coordination library from OpenAI; OpenAI models likely power JoyAgent's LLM backbone

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Agent orchestration (ReActAgent, PlanningAgent, ExecutorAgent)

The repo contains multiple agent classes (ReActAgent, PlanningAgent, ExecutorAgent, BaseAgent) in genie-backend/src/main/java/com/jd/genie/agent/agent/ but there's no evidence of unit/integration tests for agent interaction flows. This is critical for a production-grade multi-agent system where agents coordinate tasks. New contributors can add tests validating agent context passing, tool invocation chains, and error handling.

• [ ] Create genie-backend/src/test/java/com/jd/genie/agent/agent/ directory structure
• [ ] Add AgentContextTest.java testing context initialization and state management
• [ ] Add ReActAgentIntegrationTest.java testing react loop execution with mock tools
• [ ] Add AgentOrchestrationTest.java testing multi-agent task delegation and result aggregation
• [ ] Verify tests run with Maven (mvn test) in the pom.xml setup

Add GitHub Actions CI workflow for Java backend builds and tests

The repo has a Dockerfile and deployment scripts (Genie_start.sh, check_dep_port.sh) but no automated CI pipeline visible. For an open-source project, contributors should not have to manually verify their Java/Maven changes work. Add a GitHub Actions workflow to build and test the genie-backend module on PRs.

• [ ] Create .github/workflows/java-backend-ci.yml workflow file
• [ ] Configure job to run: mvn clean test -f genie-backend/pom.xml
• [ ] Add matrix strategy for Java 17 (specified in pom.xml properties)
• [ ] Include build step: mvn clean package -f genie-backend/pom.xml (skip tests to validate packaging)
• [ ] Add failure notifications and badge to README.md

Document Agent tool registration and custom tool development guide

The file structure shows agent classes but no clear documentation on how to add custom tools/agents. README.md and README_EN.md don't explain the extension mechanism. Contributors need a concrete guide showing how tools integrate with AgentContext and how to register new tools in the execution pipeline. This is blocking adoption for users wanting to customize agents.

• [ ] Create docs/TOOL_DEVELOPMENT.md with step-by-step guide
• [ ] Document AgentContext.java interface and how tools access/modify context state
• [ ] Provide code example: Creating a simple tool class that implements the tool interface
• [ ] Explain tool registration in ExecutorAgent.java (reference actual class implementation)
• [ ] Add example in docs/examples/ directory showing a custom tool integration (e.g., CustomWeatherTool)
• [ ] Update README.md with link to tool development guide and quick-start example

• Add unit tests for agent orchestration layer in genie-backend/src/test/; currently no test files visible in the top 60. Start with a basic SpringBootTest for the main AgentController to verify agent routing and response serialization.
• Document the sub-agent registration process: the README explains what agents do (ReportAgent, CodeAgent, PPTAgent, FileAgent) but not how to implement a new custom agent. Create a CONTRIBUTING.md with a worked example of a SimpleWeatherAgent using the existing agent interface.
• Standardize error handling across Python and Java layers: add a unified error response schema and document HTTP error codes (4xx, 5xx) for each agent type; currently error contract unclear from docs.

• High · Incomplete Maven POM.xml - Missing Security Dependencies — genie-backend/pom.xml. The provided pom.xml shows incomplete dependency declarations. Critical dependencies for security (Spring Security, authentication, HTTPS configuration) appear to be missing or not shown. This is a multi-agent system handling user queries and data, requiring robust security controls. Fix: Ensure pom.xml includes: spring-boot-starter-security, spring-security-web, input validation libraries. Review complete pom.xml for all security-related dependencies.
• High · Potential Code Injection via Agent Execution — genie-backend/src/main/java/com/jd/genie/agent/agent/ExecutorAgent.java, CodeInterpreterRequest.java. File structure shows CodeInterpreterRequest/Response and ExecutorAgent components. These suggest dynamic code execution capabilities. Without visible sanitization or sandboxing, this presents risks for arbitrary code execution if agent inputs are not properly validated. Fix: Implement strict input validation, use sandboxed execution environments (e.g., containerized runners), apply allowlist-based execution policies, and log all code execution attempts.
• High · SQL Injection Risk in DataAgent — genie-backend/src/main/java/com/jd/genie/agent/dto/DataAnalysisRequest.java, DataAnalysisResponse.java. DataAnalysisRequest/Response and database-related agent components suggest SQL query generation. The README mentions 'DataAgent' for structured table knowledge and 'intelligent data analysis'. Without visible parameterized queries, dynamic SQL construction poses SQLi risks. Fix: Use parameterized queries/prepared statements exclusively. Never concatenate user input into SQL. Implement ORM frameworks (Hibernate, MyBatis) with parameter binding.
• High · Insecure Docker Multi-stage Build - Registry Configuration — Dockerfile. Dockerfile uses Alibaba mirror registry (mirrors.aliyun.com) without signature verification. Uses http:// for package manager repos. No integrity checks on base images from daocloud.io registry. Fix: Pin specific base image versions with digests. Use official registries with signature verification. Replace http with https. Implement image scanning in CI/CD pipeline. Use private registries for production.
• High · Missing Spring Security Configuration — genie-backend/src/main/java/com/jd/genie/GenieApplication.java (and missing SecurityConfig). Spring Boot 3.2.2 application lacks visible security configuration. No evidence of authentication, authorization, CSRF protection, or security headers in the codebase structure. Fix: Implement WebSecurityConfigurerAdapter or SecurityFilterChain. Enable CSRF, CORS validation, authentication/authorization. Add security headers (Content-Security-Policy, X-Frame-Options, etc.).
• Medium · Potential XSS in Frontend - No Visible CSP — ui/ directory, Dockerfile frontend-builder stage. Frontend application (ui/ directory) build process visible but no Content-Security-Policy or XSS protection headers mentioned in Docker configuration or README. Fix: Implement Content-Security-Policy headers. Sanitize all user inputs in React/frontend code. Use DOMPurify for HTML content. Enable X-XSS-Protection headers.
• Medium · Unrestricted File Upload/Access in FileRequest/FileResponse — genie-backend/src/main/java/com/jd/genie/agent/dto/File.java, FileRequest.java, FileResponse.java. File.java, FileRequest.java, and FileResponse.java suggest file handling capabilities. No visible path traversal protection or file type validation in the DTO structure. Fix: Implement whitelist-based file type validation. Use absolute path validation to prevent directory traversal. Store files outside web root. Implement access controls based on user permissions.
• Medium · Missing API Rate Limiting and DDoS Protection — genie-backend/src/main/java/com/jd/genie/agent/agent/ (all agent classes). Multi-agent system accepting user queries without visible rate limiting, throttling, or DDoS protection mechanisms in configuration. Fix: Implement rate limiting (Spring Cloud Gateway, resilience4j). Add

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.