Agent-Kernel is a Multi-Agent System (MAS) framework featuring a novel society-centric modular microkernel architecture, designed to support agent-based social simulation in both distributed and standalone environments.
- ✨ Core Advantages: Why Choose Agent-Kernel?
- 🎬 Showcase
- 🏛️ Architecture and Design
- 🚀 Quick Start
- 📂 Project Structure
- 🎓 Citation
- 🤝 Contributors
- 📜 License
Agent-Kernel offers four core advantages for social simulation, making it stand out in the study of multi-agent systems:
Agent-Kernel supports adding/removing agents, changing environments, and modifying behaviors at runtime. This enables simulations to naturally reflect population flow, environmental shifts, and evolving behavioral patterns.
With the Controller module, Agent-Kernel allows real-time adjustments to parameters or events during simulation. This makes it easy to test and validate complex sociological hypotheses.
Agent-Kernel employs a strict system-level verification mechanism, validating every agent action. This ensures that simulation behaviors follow physical and social rules, maintaining scientific rigor.
Agent-Kernel uses a standardized, plugin-based modular design. Codes can be reused across scenarios, significantly accelerating research iteration.
Agent-Kernel has been successfully applied to several complex social simulation scenarios:
Simulating the famous "Universe 25" sociological experiment to explore the relationships between population density, social structure, and behavioral anomalies.
Constructing a high-fidelity simulation of the campus environment to study pedestrian flow dynamics, resource allocation, and social interaction patterns.
The Agent-Kernel framework adopts a modular microkernel architecture, with a core system—composed of the Agent, Environment, Action, Controller, and System modules—and multiple plugins. The core manages plugin registration, behavior verification, asynchronous communication, and other core responsibilities, while plugins provide the specialized functions for social simulation, as shown in the diagram below:
To realize the core design goals of the Agent-Kernel framework, we made a series of deliberate software design decisions, as illustrated in the diagram below:
Python ≥ 3.11uv
Install uv:
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# or via pip
pip install uvgit clone https://github.com/ZJU-LLMs/Agent-Kernel.git
cd Agent-Kernel
uv venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1You can work with either distributed or standalone package.
Both support optional extras:
web→aiohttp,fastapi,uvicornstorages→asyncpg,pymilvus,redisall→ includes bothwebandstorages
You can add extras with
.[web],.[storages], or.[all]after the package path.
cd packages/agentkernel-distributed
# base install
uv pip install -e .
# with optional features:
# uv pip install -e ".[web]"
# uv pip install -e ".[storages]"
# uv pip install -e ".[all]"- The distributed package depends on Ray and will install it automatically.
- No manual Ray cluster startup is required for local usage.
Run the distributed example:
uv run python -m examples.distributed_test.run_simulationcd packages/agentkernel-standalone
# base install
uv pip install -e .
# with optional features:
# uv pip install -e ".[web]"
# uv pip install -e ".[storages]"
# uv pip install -e ".[all]"Run the standalone example:
uv run python -m examples.standalone_test.run_simulationSociety-Panel is a web-based control panel to help you configure, deploy, and monitor your simulations visually.
-
Launch the panel: Use the provided startup scripts to launch the entire application stack (backend + UI). These scripts will automatically check for and install all required dependencies, so no manual environment setup is needed.
-
On Linux/macOS:
# Grant execution permission (first time only) chmod +x scripts/start_society_panel.sh ./scripts/start_society_panel.sh -
On Windows:
scripts\start_society_panel.bat
-
-
Access the UI: Once the script confirms that the services are running, open your browser and navigate to:
http://localhost:5174
From the panel, you can upload custom code packages, edit configuration files through a graphical interface, and control the simulation lifecycle. To shut down the panel and all related services, simply press Ctrl+C in the terminal where you ran the script.
MAS/
├── packages/
│ ├── agentkernel-distributed/ # Distributed version (installs Ray automatically)
│ └── agentkernel-standalone/ # Local single-machine version
│
├── examples/
│ ├── distributed_test/ # Example for the distributed version (Ray)
│ └── standalone_test/ # Example for the local standalone version
│
├── society-panel/
│ ├── backend/ # FastAPI backend service
│ └── frontend/ # Vue 3 + Vite frontend
│
└── README.md
If you use Agent-Kernel in your research, please consider citing our paper:
@misc{mao2025agentkernelmicrokernelmultiagentframework,
title={Agent-Kernel: A MicroKernel Multi-Agent System Framework for Adaptive Social Simulation Powered by LLMs},
author={Yuren Mao and Peigen Liu and Xinjian Wang and Rui Ding and Jing Miao and Hui Zou and Mingjie Qi and Wanxiang Luo and Longbin Lai and Kai Wang and Zhengping Qian and Peilun Yang and Yunjun Gao and Ying Zhang},
year={2025},
eprint={2512.01610},
archivePrefix={arXiv},
primaryClass={cs.MA},
url={https://arxiv.org/abs/2512.01610},
}
Thanks to all the developers who have contributed to Agent-Kernel:
We also welcome you to become one of our contributors via Pull Requests!
This project is licensed under the Apache 2.0.