AIOS is the AI Agent Operating System, which embeds large language model (LLM) into the operating system and facilitates the development and deployment of LLM-based AI Agents. AIOS is designed to address problems (e.g., scheduling, context switch, memory management, storage management, tool management, Agent SDK management, etc.) during the development and deployment of LLM-based agents, towards a better AIOS-Agent ecosystem for agent developers and agent users. AIOS includes the AIOS Kernel (the AIOS repository) and the AIOS SDK (this Cerebrum repository). AIOS supports both Web UI and Terminal UI.
The AIOS-Agent SDK is designed for agent users and developers, enabling them to build and run agent applications by interacting with the AIOS kernel.
- [2025-05-24] 🔥 The computer-use agent: LiteCUA has been integrated into Cerebrum!
- [2024-11-26] 🔥 Cerebrum is available for public release on PyPI!
-
Clone Repo
git clone https://github.com/agiresearch/Cerebrum.git cd Cerebrum -
Create Virtual Environment
conda create -n cerebrum-env python=3.10
or
conda create -n cerebrum-env python=3.11
or
# Windows (cmd) python -m venv cerebrum-env # Linux/MacOS python3 -m venv cerebrum-env
-
Activate the environment
conda activate myenv
or
# Windows (cmd) cd cerebrum-env cd Scripts activate.bat cd .. cd .. # Linux/MacOS source cerebrum-env/bin/activate
-
Install the package
Using uv (Recommended)pip install uv uv pip install -e .or using pip
pip install -e . -
Verify installation
python -c "import cerebrum; from cerebrum.client import Cerebrum; print(Cerebrum)"
Tip
Please see our documentation for more information.
📝 See here.
Below are some useful commands to use
-
list-available-llms
-
list-agenthub-agents
-
list-local-agents -
download-agent \ --agent_author <agent_author> \ --agent_name <agent_name> \ --agent_version <agent_version> \ --agenthub_url <agenthub_url> -
upload-agents \ --agent_path <agent_path> \ --agenthub_url <agenthub_url> -
list-toolhub-tools
-
list-local-tools
-
download-tool \ --tool_author <tool_author> \ --tool_name <tool_name> \ --tool_version <tool_version> \ --toolhub_url <toolhub_url> -
upload-tool \ --tool_path <tool_path> \ --toolhub_url <toolhub_url>
Either run agents that already exist in the local by passing the path to the agent directory
run-agent \
--mode local \
--agent_path <agent_name_or_path> \ # path to the agent directory
--task <task_input> \
--agenthub_url <agenthub_url>
For example, to run the test_agent in the local directory, you can run:
run-agent \
--mode local \
--agent_path cerebrum/example/agents/test_agent \
--task "What is the capital of United States?"
Or run agents that are uploaded to agenthub by passing the author and agent name
run-agent \
--mode remote \
--agent_author <author> \
--agent_name <agent_name> \
--agent_version <agent_version> \
--task <task_input> \
--agenthub_url <agenthub_url>
For example, to run the test_agent in the agenthub, you can run:
run-agent \
--mode remote \
--agent_author example \
--agent_name test_agent \
--agent_version 0.0.3 \
--task "What is the capital of United States?" \
--agenthub_url https://app.aios.foundation
Make sure you have followed AIOS to install virtualized environment, then you can use the following command to run:
run-computer-use-agent <YOUR TASK>
or run
python cerebrum/run_cua.py <YOUR TASK>
This guide will walk you through creating and publishing your own agents for AIOS.
First, let's look at how to organize your agent's files. Every agent needs three essential components:
author_name/
└── agent_name/
│── entry.py # Your agent's main logic
│── config.json # Configuration and metadata
└── meta_requirements.txt # Additional dependencies
For example, if your name is 'demo_author' and you're building a demo_agent that searches and summarizes articles, your folder structure would look like this:
demo_author/
└── demo_agent/
│── entry.py
│── config.json
└── meta_requirements.txt
Note: If your agent needs any libraries beyond AIOS's built-in ones, make sure to list them in meta_requirements.txt. Apart from the above three files, you can have any other files in your folder.
Your agent needs a config.json file that describes its functionality. Here's what it should include:
{
"name": "demo_agent",
"description": [
"Demo agent that can help search AIOS-related papers"
],
"tools": [
"demo_author/arxiv"
],
"meta": {
"author": "demo_author",
"version": "0.0.1",
"license": "CC0"
},
"build": {
"entry": "agent.py",
"module": "DemoAgent"
}
}There are two ways to use tools in your agents:
You can list all available tools in the ToolHub using the following command:
list-toolhub-toolsThis will display all tools available in the remote ToolHub.
To load a tool from ToolHub in your code:
from cerebrum.interface import AutoTool
tool = AutoTool.from_preloaded("example/arxiv", local=False)You can also list tools available in your local environment using the following command:
list-local-toolsTo load a local tool in your code:
from cerebrum.tool import AutoTool
tool = AutoTool.from_preloaded("google/google_search", local=True)If you would like to create your new tools, refer to How to develop new tools
Run the following command to upload your agents to the agenthub:
python cerebrum/upload_agent.py \
--agent_path <agent_path> \ # agent path to the agent directory
--agenthub_url <agenthub_url> # the url of the agenthub, default is https://app.aios.foundationSimilar as developing new agents, developing tools also need to follow a simple directory structure:
demo_author/
└── demo_tool/
│── entry.py # Contains your tool's main logic
└── config.json # Tool configuration and metadata
Important
To use the agents in your local device, you need to put the tool folder under the cerebrum/tool/core folder and register your tool in the cerebrum/tool/core/registry.py
In entry.py, you'll need to implement a tool class which is identified in the config.json with two essential methods:
get_tool_call_format: Defines how LLMs should interact with your toolrun: Contains your tool's main functionality
Here's an example:
class Wikipedia:
def __init__(self):
super().__init__()
self.WIKIPEDIA_MAX_QUERY_LENGTH = 300
self.top_k_results = 3
self.lang = "en"
self.load_all_available_meta: bool = False
self.doc_content_chars_max: int = 4000
self.wiki_client = self.build_client()
def build_client(self):
try:
import wikipedia
wikipedia.set_lang(self.lang)
except ImportError:
raise ImportError(
"Could not import wikipedia python package. "
"Please install it with `pip install wikipedia`."
)
return wikipedia
def run(self, params) -> str:
"""Run Wikipedia search and get page summaries."""
query = params["query"]
page_titles = self.wiki_client.search(query, results=self.top_k_results)
summaries = []
for page_title in page_titles[: self.top_k_results]:
if wiki_page := self._fetch_page(page_title):
if summary := self._formatted_page_summary(page_title, wiki_page):
summaries.append(summary)
if not summaries:
return "No good Wikipedia Search Result was found"
return "\n\n".join(summaries)[: self.doc_content_chars_max]
@staticmethod
def _formatted_page_summary(page_title: str, wiki_page: Any) -> Optional[str]:
return f"Page: {page_title}\nSummary: {wiki_page.summary}"
def get_tool_call_format(self):
tool_call_format = {
"type": "function",
"function": {
"name": "wikipedia",
"description": "Provides relevant information about the destination",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query for Wikipedia"
}
},
"required": [
"query"
]
}
}
}
return tool_call_formatBefore publishing tools, you need to set up the configurations as the following:
{
"name": "wikipedia",
"description": [
"Search information in the wikipedia"
],
"meta": {
"author": "example",
"version": "0.0.1",
"license": "CC0"
},
"build": {
"entry": "tool.py",
"module": "Wikipedia"
}
}then you can use the following command to upload tool
python cerebrum/commands/upload_tool.py \
--tool_path <tool_path> \ # tool path to the tool directory
--toolhub_url <toolhub_url> # the url of the toolhub, default is https://app.aios.foundation| Provider 🏢 | Model Name 🤖 | Open Source 🔓 | Model String ⌨️ | Backend ⚙️ | Required API Key |
|---|---|---|---|---|---|
| Anthropic | All Models | ❌ | model-name | anthropic | ANTHROPIC_API_KEY |
| OpenAI | All Models | ✅ | model-name | openai | OPENAI_API_KEY |
| Deepseek | All Models | ✅ | model-name | deepseek | DEEPSEEK_API_KEY |
| All Models | ❌ | model-name | gemini | GEMINI_API_KEY | |
| Groq | All Models | ✅ | model-name | groq | GROQ_API_KEY |
| HuggingFace | All Models | ✅ | model-name | huggingface | HF_HOME |
| ollama | All Models | ✅ | model-name | ollama | - |
| vLLM | All Models | ✅ | model-name | vllm | - |
| Novita | All Models | ✅ | model-name | novita | NOVITA_API_KEY |
@article{mei2025litecua,
title={LiteCUA: Computer as MCP Server for Computer-Use Agent on AIOS},
author={Mei, Kai and Zhu, Xi and Gao, Hang and Lin, Shuhang and Zhang, Yongfeng},
journal={arXiv preprint arXiv:2505.18829},
year={2025}
}
@article{xu2025mem,
title={A-Mem: Agentic Memory for LLM Agents},
author={Xu, Wujiang and Liang, Zujie and Mei, Kai and Gao, Hang and Tan, Juntao and Zhang, Yongfeng},
journal={arXiv:2502.12110},
year={2025}
}
@inproceedings{rama2025cerebrum,
title={Cerebrum (AIOS SDK): A Platform for Agent Development, Deployment, Distribution, and Discovery},
author={Balaji Rama and Kai Mei and Yongfeng Zhang},
booktitle={2025 Annual Conference of the Nations of the Americas Chapter of the Association for Computational Linguistics},
year={2025}
}
@inproceedings{shi2025from,
title={From Commands to Prompts: {LLM}-based Semantic File System for AIOS},
author={Zeru Shi and Kai Mei and Mingyu Jin and Yongye Su and Chaoji Zuo and Wenyue Hua and Wujiang Xu and Yujie Ren and Zirui Liu and Mengnan Du and Dong Deng and Yongfeng Zhang},
booktitle={The Thirteenth International Conference on Learning Representations},
year={2025},
url={https://openreview.net/forum?id=2G021ZqUEZ}
}
@article{mei2024aios,
title={AIOS: LLM Agent Operating System},
author={Mei, Kai and Li, Zelong and Xu, Shuyuan and Ye, Ruosong and Ge, Yingqiang and Zhang, Yongfeng}
journal={arXiv:2403.16971},
year={2024}
}
@article{ge2023llm,
title={LLM as OS, Agents as Apps: Envisioning AIOS, Agents and the AIOS-Agent Ecosystem},
author={Ge, Yingqiang and Ren, Yujie and Hua, Wenyue and Xu, Shuyuan and Tan, Juntao and Zhang, Yongfeng},
journal={arXiv:2312.03815},
year={2023}
}
For how to contribute, see CONTRIBUTE. If you would like to contribute to the codebase, issues or pull requests are always welcome!
If you would like to join the community, ask questions, chat with fellows, learn about or propose new features, and participate in future developments, join our Discord Community!
For issues related to Cerebrum development, we encourage submitting issues, pull requests, or initiating discussions in AIOS Discord Channel. For other issues please feel free to contact the AIOS Foundation (contact@aios.foundation).