[![GitHub Stars](https://img.shields.io/github/stars/ZJU-LLMs/Agent-Kernel?label=Stars&logo=github&color=brightgreen)](https://github.com/ZJU-LLMs/Agent-Kernel/stargazers)

[![Version](https://img.shields.io/github/v/release/ZJU-LLMs/Agent-Kernel?color=blue&label=Version)](https://github.com/ZJU-LLMs/Agent-Kernel/releases)


[![Homepage](https://img.shields.io/badge/Homepage-Website-1f4b99?logo=home&logoColor=white)](https://www.agent-kernel.tech)
[![Paper](https://img.shields.io/badge/Paper-arXiv-b31b1b.svg?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2512.01610)

[![SocietyHub](https://img.shields.io/badge/SocietyHub-Community-2ea44f?logo=discourse&logoColor=white)](https://www.agent-kernel.tech/societyhub)


[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-8fce00.svg)](https://github.com/ZJU-LLMs/Agent-Kernel/pulls)

[![License](https://img.shields.io/badge/License-Apache_2.0-orange.svg)](https://github.com/ZJU-LLMs/Agent-Kernel/blob/main/LICENSE)

English • 简体中文

We appreciate your support! Help us grow and improve by giving Agent-Kernel a 🌟 star on GitHub!

Explore the Scaling Law of Collective Intelligence

Agent-Kernel is a user-friendly multi-agent system development framework, which is designed to powerfully enable large-scale social simulation. This offers the opportunity to Explore the Scaling Law of Collective Intelligence.

✨ Highlights

Agent-Kernel supports:

• dynamic addition and removal of LLMs-based agents at runtime;

• unlimited scalability of agents;

• real-time intervention during the simulation process;

• trustworthy verification of agent behaviors and large model outputs;

• code reuse across different simulation scenarios.

🎬 Showcase

Agent-Kernel has been successfully applied to several complex social simulation scenarios:

1. Universe 25 Experiment

Simulating the famous "Universe 25" sociological experiment to explore the relationships between population density, social structure, and behavioral anomalies.

2. ZJU Campus Life

Constructing a high-fidelity simulation of the campus environment to study pedestrian flow dynamics, resource allocation, and social interaction patterns.

3. OpenHospital

Building an interactive hospital simulation arena for evolving and benchmarking LLM-based collective intelligence in realistic clinical workflows.

📍 Table of Contents

• ✨ Highlights
• 🎬 Showcase
  • Universe 25 Experiment
  • ZJU Campus Life
  • OpenHospital
• 🎯 Core Advantages: Why Choose Agent-Kernel?
  • Adaptability
  • Configurability
  • Reliability
  • Reusability
• 🏛️ Architecture and Design
  • Framework Overview
  • Software Design
• 🚀 Quick Start
  • Requirements
  • Installation
  • (Optional) Start Society-Panel
• 📂 Project Structure
• 🎓 Citation
• 🤝 Contributors
• 📜 License

🎯 Core Advantages: Why Choose Agent-Kernel?

Agent-Kernel offers four core advantages for social simulation, making it stand out in the study of multi-agent systems:

1. Adaptability

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.

2. Configurability

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.

3. Reliability

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.

4. Reusability

Agent-Kernel uses a standardized, plugin-based modular design. Codes can be reused across scenarios, significantly accelerating research iteration.

🏛️ Architecture and Design

1. Framework Overview

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:

2. Software Design

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:

🚀 Quick Start

1. Requirements

• Python ≥ 3.11

2. Installation

You can choose either standalone or distributed package based on your needs.

Agent-Kernel Standalone

pip install agentkernel-standalone

👉 For detailed usage and examples, see the Standalone README.

Agent-Kernel Distributed

pip install agentkernel-distributed

Note: The distributed package depends on Ray and will install it automatically.

👉 For detailed usage and examples, see the Distributed README.

Installing with Optional Features

Both agentkernel-standalone and agentkernel-distributed support optional dependencies for web services and storage solutions. You can install them as needed.

• web → Installs aiohttp, fastapi, uvicorn
• storages → Installs asyncpg, pymilvus, redis
• all → Installs both web and storages

To install a package with these extras, use square brackets []. For example:

# Install the standalone package with web features
pip install "agentkernel-standalone[web]"

# Install the distributed package with storage features
pip install "agentkernel-distributed[storages]"

# Install the distributed package with all optional features
pip install "agentkernel-distributed[all]"

3. (Optional) Start Society-Panel

Society-Panel is a web-based control panel to help you configure, deploy, and monitor your simulations visually.

1. 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
     

2. 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.

📂 Project Structure

Agent-Kernel/
├── packages/
│   ├── agentkernel-distributed/   # Distributed version (installs Ray automatically)
│   └── agentkernel-standalone/    # Local single-machine version
│
├── demo/                          # Demo scenarios built on shared Agent-Kernel packages
│   └── OpenHospital/
│
├── 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

🎓 Citation

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},
}

🤝 Contributors

Thanks to all the developers who have contributed to Agent-Kernel:

We also welcome you to become one of our contributors via Pull Requests!

📜 License

This project is licensed under the Apache 2.0.