# Agent-Kernel puts the simulation in a plugin and the rules in the core

> ZJU-LLMs' framework ships as two pip packages, one of which pulls in Ray, and builds on a microkernel with five core modules. Behaviour verification sits in the core rather than the extensions, which is the decision that makes a simulation framework worth trusting.

**ZJU-LLMs/Agent-Kernel** — A MicroKernel Multi-Agents System Framework for Adaptive Social Simulation Powered by LLMs

- Repository: https://github.com/ZJU-LLMs/Agent-Kernel
- Website: https://www.agent-kernel.tech
- Stars: 537 · Forks: 52
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/zju-llms-agent-kernel

## Two pip packages, and one of them installs Ray for you

Installation is a choice between two distributions rather than one. The standalone package is:

```bash
pip install agentkernel-standalone
```

The distributed package is installed under a different name:

```bash
pip install agentkernel-distributed
```

The note attached to the second one is the part that matters: it depends on Ray and will install it automatically. So the real question at install time is not which package is better but whether your simulation needs to span machines. If it does not, pulling in a distributed execution framework is cost you pay up front for nothing. Both packages then offer the same extras, and each has its own README under examples with usage walkthroughs for the standalone and distributed cases respectively.

## Extras are split by what they enable, not by how big they are

Both packages support two optional dependency groups and a combination. The web extra installs aiohttp, fastapi and uvicorn. The storages extra installs asyncpg, pymilvus and redis. The all extra installs both sets. They are selected with the usual square bracket syntax on the package name, for example agentkernel-standalone[web] or agentkernel-distributed[all].

The grouping is a reasonable read of the dependencies. The web group is an HTTP surface with a server; the storages group is three different persistence backends at once, a PostgreSQL client, a vector database client and an in-memory or cache store. Installing all three storage clients because you need one of them is the cost of a coarse extra, so it is worth checking which backend your scenario actually uses before reaching for it.

## Five core modules, and the scenario lives outside them

The architecture is described as modular microkernel, and the core system is composed of five named modules: Agent, Environment, Action, Controller and System. Alongside those, the core handles plugin registration, behaviour verification and asynchronous communication, and the plugins supply the specialised functions needed for a particular social simulation.

That division is the whole design argument. Everything a scenario needs to vary lives in a plugin, and everything that must behave identically across experiments lives in the core. The Controller module in particular is listed among the core five rather than among the extensions, which is consistent with the claim that simulations can be adjusted while they run.

## Validating every agent action is core work, not an extension's job

The reliability claim is specific: a strict system-level verification mechanism validates every agent action, so that simulated behaviour follows physical and social rules and the work maintains scientific rigor. The placement matters more than the wording. If verification were a plugin responsibility, a scenario that forgot to register it would silently produce unvalidated runs, and the results would be indistinguishable from validated ones.

Read the claim carefully, though. The framework can check an action against rules it has been given. Whether those rules capture the phenomena you care about is a modelling decision you make, so validation constrains internal consistency rather than establishing that a simulation is realistic.

## Agents and parameters can change while the simulation is running

Two of the stated capabilities are about mutability rather than scale. Agents can be added and removed at runtime, environments can be changed and behaviours modified, which the project frames as letting a simulation reflect population flow and environmental shifts rather than being frozen between runs. The Controller module is the mechanism for adjusting parameters or events during a run, described as making it easier to test and validate complex sociological hypotheses.

That is a real difference from the usual batch experiment framework, where a configuration change means restarting and re-running everything. It also creates the conditions for a different kind of mistake: a run that was interrupted mid-flight by a controller action is no longer a clean sample, so anything you measure afterwards needs a record of what was changed and when.

## Three demos, and the videos live outside the repository

The demonstration scenarios are a population simulation, a campus simulation and a hospital arena. The first recreates what the README calls the famous Universe 25 sociological experiment, exploring relationships between population density, social structure and behavioural anomalies. The second builds a campus environment to study pedestrian flow dynamics, resource allocation and social interaction patterns. The third, OpenHospital, is an interactive hospital simulation arena for evolving and benchmarking LLM-based collective intelligence in realistic clinical workflows.

Two practical notes. OpenHospital is the one with code checked into the tree, under demo/OpenHospital, so it is the scenario you can actually read. And all three are demonstrated by video hosted on Bilibili rather than by anything in the repository, which means reviewing them means watching rather than reading.

## The web control panel ships in the same repository

Society-Panel is described as a web-based control panel for configuring and deploying a simulation, and it has its own directory at the top level of the repository rather than being a separate project. That means the panel, the framework packages and the example scenarios are versioned together, which is convenient when you are running experiments and inconvenient when you only want the library.

The repository also carries an English and a Simplified Chinese README, a .python-version file pinning the interpreter alongside the stated requirement of Python 3.11 or newer, and a LICENSE under Apache-2.0. The work is published outside the repository as well: a project site at agent-kernel.tech and a paper on arXiv at 2512.01610. The last tagged release was v1.1.0 on 2025-12-18, after v1.0.0 on 2025-12-04, and the last push was on 2026-06-03.

## Conclusion

Agent-Kernel is worth a look if your research question needs agents added and removed while a simulation is running, because that is the capability most multi-agent frameworks leave as a manual restart. The architecture supports the claim: the five core modules stay fixed, the scenario lives in a plugin, and validation of every agent action is core behaviour rather than something an extension can forget to do. Two things to check first. Pick the package by whether you actually need multi-machine execution, because the distributed variant installs Ray whether you want it or not. And read the reliability claim critically: verifying that actions follow physical and social rules is only meaningful against rules you supply, so the framework cannot validate the realism of your model, only its internal consistency.

## FAQ

### What is Agent-Kernel?

An Apache-2.0 licensed Python framework for large-scale social simulation with LLM-based agents, built on a microkernel architecture of five core modules plus plugins. Its project site is agent-kernel.tech and the work is also on arXiv.

### Which Python version does Agent-Kernel require?

Python 3.11 or newer. The repository also carries a .python-version file at the top level alongside that stated requirement.

### Do I need Ray to run Agent-Kernel?

Only for the distributed package. The standalone package installs on its own, while agentkernel-distributed depends on Ray and installs it automatically as part of the install.

### What optional dependencies can I install with Agent-Kernel?

A web extra pulling aiohttp, fastapi and uvicorn; a storages extra pulling asyncpg, pymilvus and redis; and an all extra that installs both. They are selected with square brackets on the package name.

### Which modules make up the Agent-Kernel core?

Agent, Environment, Action, Controller and System. The core also manages plugin registration, behaviour verification and asynchronous communication, while plugins hold the scenario-specific functions.

### What scenarios are shipped with Agent-Kernel?

Three: a Universe 25 population simulation covering density, social structure and behavioural anomalies; a campus life simulation for pedestrian flow and resource allocation; and OpenHospital, a hospital arena for benchmarking collective intelligence in clinical workflows.

## Sources

- [License: Apache-2.0](https://github.com/ZJU-LLMs/Agent-Kernel/blob/main/LICENSE)
- [Project website](https://www.agent-kernel.tech)
- [README](https://github.com/ZJU-LLMs/Agent-Kernel/blob/main/README.md)
- [Releases](https://github.com/ZJU-LLMs/Agent-Kernel/releases)
- [ZJU-LLMs/Agent-Kernel on GitHub](https://github.com/ZJU-LLMs/Agent-Kernel)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zju-llms-agent-kernel