Skip to content
Back to search

OxyGent

[ACL 2026] OxyGent: Making Multi-Agent Systems Modular, Observable, and Evolvable via Oxy Abstraction https://arxiv.org/abs/2604.25602

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jd-opensource--oxygent/badge.svg)](/listings/jd-opensource--oxygent)

HTML

<a href="/listings/jd-opensource--oxygent"><img src="/api/listings/jd-opensource--oxygent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Step 1: Create and activate a python environment

- Method 1: conda

   conda create -n oxy_env python==3.10
   conda activate oxy_env

- Method 2: uv

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv python install 3.10 
   uv venv .venv --python 3.10
   source .venv/bin/activate

Step 2: Install the required python package

- Method 1: conda

   pip install oxygent

- Method 2: uv

   uv pip install oxygent

- Method 3: set develop environment

   git clone https://github.com/jd-opensource/OxyGent.git
   cd OxyGent
   pip install -r requirements.txt # or in uv
   brew install coreutils # maybe essential

Step 3: Node.js Environment (if using MCP)

- Download and install **[Node.js](https://nodejs.org)**

Step 4: Write a sample python script

- demo.py

   import os
   from oxygent import MAS, Config, oxy, preset_tools

   Config.set_agent_llm_model("default_llm")

   oxy_space = [
      oxy.HttpLLM(
         name="default_llm",
         api_key=os.getenv("DEFAULT_LLM_API_KEY"),
         base_url=os.getenv("DEFAULT_LLM_BASE_URL"),
         model_name=os.getenv("DEFAULT_LLM_MODEL_NAME"),
      ),
      preset_tools.time_tools,
      oxy.ReActAgent(
         name="time_agent",
         desc="A tool that can query the time",
         tools=["time_tools"],
      ),
      preset_tools.file_tools,
      oxy.ReActAgent(
         name="file_agent",
         desc="A tool that can operate the file system",
         tools=["file_tools"],
      ),
      preset_tools.math_tools,
      oxy.ReActAgent(
         name="math_agent",
         desc="A tool that can perform mathematical calculations.",
         tools=["math_tools"],
      ),
      oxy.ReActAgent(
         is_master=True,
         name="master_agent",
         sub_agents=["time_agent", "file_agent", "math_agent"],
      ),
   ]

   async def main():
      async with MAS(oxy_space=oxy_space) as mas:
         await mas.start_web_service(
            first_query="What time is it now? Please save it into time.txt."
         )

   if __name__ == "__main__":
      import asyncio
      asyncio.run(main())

Step 5: Set Environment Variables

- Method 1: Declare in terminal

   export DEFAULT_LLM_API_KEY="your_api_key"
   export DEFAULT_LLM_BASE_URL="your_base_url"
   export DEFAULT_LLM_MODEL_NAME="your_model_name"  

- Method 2: Create a .env file

   DEFAULT_LLM_API_KEY="your_api_key"
   DEFAULT_LLM_BASE_URL="your_base_url"
   DEFAULT_LLM_MODEL_NAME="your_model_name"

Step 6: Run the example

- Start the multi-agent system

   python demo.py

Step 7: View the output

- ![](https://storage.jd.com/ai-gateway-routing/prod_data/oxygent_github_images/vision.png)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- Copyright 2022 JD Co.
  2. Licensed under the Apache License, Version 2.0 (the "License");
  3. you may not use this project except in compliance with the License.
  4. You may obtain a copy of the License at
  5. http://www.apache.org/licenses/LICENSE-2.0
  6. Unless required by applicable law or agreed to in writing, software
  7. distributed under the License is distributed on an "AS IS" BASIS,
  8. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  9. See the License for the specific language governing permissions and
  10. limitations under the License. -->
  11. [English](./README.md) | [中文](./README_zh.md)
  12. <p align="center">
  13. <a href="https://github.com/jd-opensource/OxyGent/pulls">
  14. <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome">
  15. </a>
  16. <a href="https://github.com/jd-opensource/OxyGent/blob/v4/LICENSE">
  17. <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="license"/>
  18. </a>
  19. <a href="https://pypi.org/project/oxygent/">
  20. <img src="https://img.shields.io/pypi/v/oxygent.svg?logo=pypi&logoColor=white" alt="pip"/>
  21. </a>
  22. <a href="https://arxiv.org/abs/2604.25602">
  23. <img src="https://img.shields.io/badge/Paper-ACL%202026-orange" alt="paper"/>
  24. </a>
  25. <html>
  26. <h2 align="center">
  27. <img src="https://storage.jd.com/ai-gateway-routing/prod_data/oxygent_github_images/banner.jpg" width="1256"/>
  28. </h2>
  29. <h3 align="center">
  30. An advanced Python framework that empowers developers to quickly build production-ready intelligent systems.
  31. </h3>
  32. <h3 align="center">
  33. Visit our website:
  34. <a href="http://oxygent.jd.com">OxyGent</a>
  35. |Open Source:
  36. <a href="https://github.com/jd-opensource/OxyGent">Python</a>
  37. or
  38. <a href="https://github.com/jd-opensource/JDOxyGent4J">Java</a>
  39. </h3>
  40. </html>
  41. ## 1. Project Overview
  42. **OxyGent** is an open-source framework that unifies tools, models, and agents into modular Oxy. Empowering developers with transparent, end-to-end pipelines, OxyGent makes building, running, and evolving multi-agent systems seamless and infinitely extensible.
  43. ## 2. Core Features
  44. 🏎️ **Efficient Development**
  45. - OxyGent is a modular multi-agent framework that lets you build, deploy, and evolve AI teams with unprecedented efficiency. Its standardized Oxy components snap together like LEGO bricks, enabling rapid assembly of agents while supporting hot-swapping and cross-scenario reuse - all through clean Python interfaces without messy configs.
  46. 🤝 **Intelligent Collaboration**
  47. - The framework supercharges collaboration with dynamic planning paradigms, where agents intelligently decompose tasks, negotiate solutions, and adapt to changes in real-time. Unlike rigid workflow systems, OxyGent's agents handle emergent challenges naturally while maintaining full auditability of every decision.
  48. 🕸️ **Elastic Architecture**
  49. - Under the hood, an elastic architecture supports any agent topology- from simple ReAct to complex hybrid planning patterns. Automated dependency mapping and visual debugging tools make it easy to optimize performance across distributed systems.
  50. 🔁 **Continuous Evolution**
  51. - Every interaction becomes a learning opportunity - thanks to built-in evaluation engines that auto-generate training data. Your agents continuously improve through knowledge feedback loops while maintaining full transparency.
  52. 📈 **Scalability**
  53. - Scaling follows Metcalfe's Law- OxyGent's distributed scheduler enables linear cost growth while delivering exponential gains in collaborative intelligence. The system effortlessly handles domain-wide optimization and real-time decision making at any scale.
  54. The latest version of OxyGent (July 15, 2025) in the [GAIA](https://huggingface.co/spaces/gaia-benchmark/leaderboard) get 59.14 points, and current top opensource system OWL gets 60.8 points.
  55. ![](https://storage.jd.com/ai-gateway-routing/prod_data/oxygent_github_images/points.png)
  56. ## 3. Framework Core Classes
  57. ![](docs/images/structure.png)
  58. ## 4. Feature Highlight
  59. **For Developers**: Focus on business logic without reinventing the wheel.
  60. **For Enterprises**: Replace siloed AI systems with a unified framework, reducing communication overhead.
  61. **For Users**: Experience seamless teamwork from an intelligent agent ecosystem.
  62. ## 5. Quick Start
  63. ### Step 1: Create and activate a python environment
  64. - Method 1: conda
  65. ```bash
  66. conda create -n oxy_env python==3.10
  67. conda activate oxy_env
  68. ```
  69. - Method 2: uv
  70. ```bash
  71. curl -LsSf https://astral.sh/uv/install.sh | sh
  72. uv python install 3.10
  73. uv venv .venv --python 3.10
  74. source .venv/bin/activate
  75. ```
  76. ### Step 2: Install the required python package
  77. - Method 1: conda
  78. ```bash
  79. pip install oxygent
  80. ```
  81. - Method 2: uv
  82. ```bash
  83. uv pip install oxygent
  84. ```
  85. - Method 3: set develop environment
  86. ```bash
  87. git clone https://github.com/jd-opensource/OxyGent.git
  88. cd OxyGent
  89. pip install -r requirements.txt # or in uv
  90. brew install coreutils # maybe essential
  91. ```
  92. ### Step 3: Node.js Environment (if using MCP)
  93. - Download and install **[Node.js](https://nodejs.org)**
  94. ### Step 4: Write a sample python script
  95. - demo.py
  96. ```python
  97. import os
  98. from oxygent import MAS, Config, oxy, preset_tools
  99. Config.set_agent_llm_model("default_llm")
  100. oxy_space = [
  101. oxy.HttpLLM(
  102. name="default_llm",
  103. api_key=os.getenv("DEFAULT_LLM_API_KEY"),
  104. base_url=os.getenv("DEFAULT_LLM_BASE_URL"),
  105. model_name=os.getenv("DEFAULT_LLM_MODEL_NAME"),
  106. ),
  107. preset_tools.time_tools,
  108. oxy.ReActAgent(
  109. name="time_agent",
  110. desc="A tool that can query the time",
  111. tools=["time_tools"],
  112. ),
  113. preset_tools.file_tools,
  114. oxy.ReActAgent(
  115. name="file_agent",
  116. desc="A tool that can operate the file system",
  117. tools=["file_tools"],
  118. ),
  119. preset_tools.math_tools,
  120. oxy.ReActAgent(
  121. name="math_agent",
  122. desc="A tool that can perform mathematical calculations.",
  123. tools=["math_tools"],
  124. ),
  125. oxy.ReActAgent(
  126. is_master=True,
  127. name="master_agent",
  128. sub_agents=["time_agent", "file_agent", "math_agent"],
  129. ),
  130. ]
  131. async def main():
  132. async with MAS(oxy_space=oxy_space) as mas:
  133. await mas.start_web_service(
  134. first_query="What time is it now? Please save it into time.txt."
  135. )
  136. if __name__ == "__main__":
  137. import asyncio
  138. asyncio.run(main())
  139. ```
  140. ### Step 5: Set Environment Variables
  141. - Method 1: Declare in terminal
  142. ```bash
  143. export DEFAULT_LLM_API_KEY="your_api_key"
  144. export DEFAULT_LLM_BASE_URL="your_base_url"
  145. export DEFAULT_LLM_MODEL_NAME="your_model_name"
  146. ```
  147. - Method 2: Create a .env file
  148. ```bash
  149. DEFAULT_LLM_API_KEY="your_api_key"
  150. DEFAULT_LLM_BASE_URL="your_base_url"
  151. DEFAULT_LLM_MODEL_NAME="your_model_name"
  152. ```
  153. ### Step 6: Run the example
  154. - Start the multi-agent system
  155. ```bash
  156. python demo.py
  157. ```
  158. ### Step 7: View the output
  159. - ![](https://storage.jd.com/ai-gateway-routing/prod_data/oxygent_github_images/vision.png)
  160. ## 6. Contributing
  161. There are several ways you can contribute to OxyGent:
  162. 1. Reporting Issues (Bugs & Errors)
  163. 2. Suggesting Enhancements
  164. 3. Improving Documentation
  165. - Fork the repository
  166. - Add your view in document
  167. - Send your pull request
  168. 4. Writing Code
  169. - Fork the repository
  170. - Create a new branch
  171. - Add your feature or improvement
  172. - Send your pull request
  173. We appreciate all kinds of contributions! 🎉🎉🎉
  174. If you have problems about development, please check our document: **[Document](http://oxygent.jd.com/docs/)**
  175. ## 7. Community & Support
  176. If you encounter any issues along the way, you are welcomed to submit reproducible steps and log snippets in the project's Issues area, or contact the OxyGent Core team directly via your internal Slack.
  177. Welcome to contact us:
  178. <div align="center">
  179. <img src="https://pfst.cf2.poecdn.net/base/image/b1e96084336a823af7835f4fe418ff49da6379570f0c32898de1ffe50304d564?w=1760&h=2085&pmaid=425510216" alt="contact" width="50%" height="50%">
  180. </div>
  181. ## 8. About the Contributors
  182. Thanks to all the following [developers](https://github.com/jd-opensource/OxyGent/graphs/contributors) who have contributed to OxyGent.
  183. <a href="https://github.com/jd-opensource/OxyGent/graphs/contributors">
  184. <img src="https://contrib.rocks/image?repo=jd-opensource/OxyGent" />
  185. </a>
  186. ## FAQ
  187. ### General Questions
  188. **What is OxyGent?**
  189. OxyGent is an open-source framework that unifies tools, models, and agents into modular Oxy components. It empowers developers to build, run, and evolve multi-agent systems with transparent, end-to-end pipelines.
  190. **How is OxyGent different from other multi-agent frameworks?**
  191. OxyGent uses a unique "Oxy" abstraction that standardizes agent components, enabling hot-swapping and cross-scenario reuse. Unlike rigid workflow systems, OxyGent supports dynamic planning paradigms where agents intelligently decompose tasks and adapt to changes in real-time.
  192. **What is the Oxy abstraction?**
  193. Oxy is a standardized component model that snaps together like LEGO bricks. Each Oxy encapsulates a specific capability (tool, model, or agent) with clean Python interfaces, enabling rapid assembly and evolution of AI teams.
  194. ### Setup & Configuration
  195. **What are the system requirements?**
  196. - Python 3.10+
  197. - pip package manager
  198. - API key from an LLM provider (OpenAI, Anthropic, etc.)
  199. **How do I install OxyGent?**
  200. ```bash
  201. pip install oxygent
  202. ```
  203. **Can I use OxyGent with local models?**
  204. Yes! OxyGent supports any LLM provider that exposes a compatible API. Configure your local model via environment variables (`DEFAULT_LLM_BASE_URL`, `DEFAULT_LLM_MODEL_NAME`).
  205. ### Agent Development
  206. **How do I create a custom Oxy?**
  207. Create a new class that inherits from the base Oxy class and implement the required methods. See the [documentation](http://oxygent.jd.com/docs/) for detailed guides.
  208. **What planning paradigms does OxyGent support?**
  209. OxyGent supports multiple planning paradigms:
  210. - **ReAct**: Reasoning + Acting pattern for simple tasks
  211. - **Dynamic Planning**: Agents intelligently decompose tasks and negotiate solutions
  212. - **Hybrid Planning**: Combines multiple paradigms for complex scenarios
  213. **How does OxyGent handle agent collaboration?**
  214. OxyGent's elastic architecture supports any agent topology. Agents communicate through standardized interfaces, with automated dependency mapping and visual debugging tools for optimization.
  215. ### Deployment
  216. **How do I deploy OxyGent applications?**
  217. OxyGent applications can be deployed as standard Python applications:
  218. - **Local Development**: Run `python demo.py` for local testing
  219. - **Production**: Use the distributed scheduler for scaling across multiple nodes
  220. - **Docker**: Containerize your OxyGent application for consistent deployment
  221. **Is OxyGent suitable for enterprise use?**
  222. Yes! OxyGent is designed for enterprise scenarios with features like:
  223. - Distributed scheduling for horizontal scaling
  224. - Full auditability of every decision
  225. - Built-in evaluation engines for continuous improvement
  226. - Support for domain-wide optimization and real-time decision making
  227. ### Troubleshooting
  228. **Common Issues:**
  229. - **Import Errors**: Ensure Python 3.10+ is installed and dependencies are up to date
  230. - **API Key Errors**: Verify your LLM provider API key is correctly configured
  231. - **Agent Communication Issues**: Check that all Oxy components are properly registered
  232. **Where can I get help?**
  233. - [Official Documentation](http://oxygent.jd.com/docs/)
  234. - [GitHub Issues](https://github.com/jd-opensource/OxyGent/issues)
  235. - Internal Slack (for JD.com employees)
  236. ## 9. License
  237. [Apache License]( ./LICENSE.md)
  238. #### OxyGent is provided by Oxygen JD.com
  239. #### Thanks for your Contributions!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.