The Problem
You want to simulate a world where AI agents think, talk, fight, betray, and form alliances -- all on their own. But building one from scratch means wiring up LLM calls, memory systems, event loops, WebSocket renderers, and React dashboards. Every new scenario starts from zero.
AgentWorld fixes this. Define your agents, pick your plugins, write a config -- and you have a living, breathing simulation with real-time visualization. Want to switch from a Spring & Autumn Period war to a stock market? Change the config. The engine, memory, communication, and rendering all come for free.
What Makes It Different
|
Building from scratch |
With AgentWorld |
| Agent cognition |
Hand-roll LLM prompts, parse outputs manually |
Brain Plugin with structured thinking + memory recall |
| Agent memory |
Dump everything into context window |
Tiered memory with importance scoring and decay |
| Agent communication |
Custom message passing, hope it works |
Two-phase conversation system, channels, broadcasting |
| Visualization |
Build a React dashboard from scratch |
Pre-built UI components, plug in with one import |
| New scenario |
Rewrite everything |
New config + scenario-specific plugins |
| Deterministic testing |
Can't test without paying LLM API costs |
Swap to IdleBrain or RuleBrain, run for free |
Core Philosophy
Everything as Plugin Swap any component without touching others
EventBus as Nervous System Zero coupling between plugins
Convention over Configuration Sensible defaults, minimal boilerplate
Scenarios > Features A new scenario is worth more than a new API
Dual Brain LLM brain for intelligence, Idle brain for free testing
How It Works
graph TB
subgraph Engine["Engine (Tick Loop)"]
EB["EventBus"]
PM["PluginManager"]
AM["AgentManager"]
end
subgraph Plugins["Plugins (Everything is a Plugin)"]
B["Brain Plugin<br/>LLM / Rule / Idle"]
M["Memory Plugin<br/>Simple / Tiered"]
W["World Plugin<br/>Grid / Abstract"]
I["Interaction Plugin<br/>Combat / Diplomacy"]
R["Renderer Plugin<br/>WebSocket"]
C["Custom Plugins<br/>Emotion / Narrative / ..."]
end
subgraph Frontend["Frontend (React + Next.js)"]
UI["@agent-world/ui<br/>Dashboard, Chat, Controls"]
WS["WebSocket Client"]
end
Engine --> Plugins
EB -.->|typed events| B & M & W & I & R & C
R -->|real-time state| WS
WS --> UI
Each tick, agents go through a Perceive → Think → Act cycle. Plugins communicate exclusively through typed events on the EventBus. The renderer streams state to the browser via WebSocket for real-time visualization.
Features
Plugin System
Every piece of functionality is a plugin. Brain, memory, world rules, agent interactions, rendering -- all plugins.
| Plugin Type |
Purpose |
Built-in Options |
| Brain |
How agents think |
LLM, Rule, Idle, Multi, Hybrid |
| Memory |
How agents remember |
Simple (array), Tiered (importance) |
| World |
World rules and terrain |
Grid, Abstract |
| Interaction |
Agent-to-agent interactions |
Combat, Diplomacy, Trade (per scenario) |
| Renderer |
Visualization output |
WebSocket (real-time) |
| Custom |
Everything else |
Emotion, Narrative, Metrics, Goals, ... |
Pre-built UI Components
Ship a complete simulation frontend in minutes, not weeks. Every component accepts a labels prop for i18n.
| Component |
What It Does |
| Dashboard |
Slot-based layout with controls, sidebar, and main content |
| Controls |
Play / pause / step / speed / stop with live tick counter |
| AgentSidebar |
Sortable agent list with custom cards and settings tab |
| AgentChat |
Two-panel chat with channels, emoji picker, thought bubbles |
| AgentDetail |
Tabbed agent view with custom headers and content |
| EventBusViewer |
Filterable world events timeline |
| GodModePanel |
Inject events, modify stats, force speech, alter memories |
| SettingsPanel |
LLM provider selection, API key management, start/stop |
React Hooks
import { useSimulation, useAgent, useSpeeches, useNarratives } from '@agent-world/ui'
const { state, client, connected } = useSimulation('ws://localhost:3000/_ws')
const agent = useAgent(client, agentId)
const speeches = useSpeeches(client)
const narratives = useNarratives(client)
Define a Scenario in One File
import { defineScenario } from '@agent-world/core'
export default defineScenario({
name: 'spring-autumn',
description: 'Seven kingdoms wage war, form alliances, and betray',
agents: [
{ id: 'qin', name: 'Qin', traits: { kingdom: '秦', personality: 'aggressive' } },
{ id: 'qi', name: 'Qi', traits: { kingdom: '齐', personality: 'diplomatic' } },
// ...5 more kingdoms
],
plugins: [brainPlugin, memoryPlugin, worldPlugin, combatPlugin, diplomacyPlugin, rendererPlugin],
endCondition: (agents) => agents.filter(a => a.status === 'active').length <= 1,
})
Scenario Ideas
AgentWorld is designed so that each new scenario is just a new config + plugins. Here are some ideas we're exploring:
| Scenario |
Description |
Status |
| AI Spring & Autumn Period |
Seven kingdoms wage war, form alliances, betray. Every run tells a different story. |
Included |
| AI Battle Royale |
100 agents in a shrinking map. Solo, team up, or backstab. |
Planned |
| AI Stock Market |
Agents with different investment philosophies. Watch bubbles form and crash. |
Planned |
| AI Dark Forest |
Three civilizations under uncertainty. Will cooperation or destruction emerge? |
Planned |
| AI Prison Experiment |
Power dynamics between guards and prisoners. Does power corrupt AI? |
Planned |
| AI Civilization Collapse |
A thriving civilization loses a critical resource. Orderly decline or chaos? |
Planned |
| AI Lie Evolution |
Start with 100% honest agents. Allow lying. Watch deception spread. |
Planned |
| AI Currency Origin |
Barter-only agents. Will money, credit, and banking emerge? |
Planned |
Want to create your own? Fork the examples/template directory, define your agents and plugins, and run.
Quick Start
Prerequisites
Run the Spring & Autumn Example
# Clone the repo
git clone https://github.com/nicepkg/agent-world.git
cd agent-world
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Start the Spring & Autumn simulation
pnpm --filter=@agent-world/example-spring-autumn dev
Open http://localhost:3000 in your browser. Configure your LLM provider in the settings panel, hit Start, and watch seven kingdoms fight for supremacy.
Create Your Own Scenario
# Copy the template
cp -r examples/template examples/my-scenario
# Edit the scenario config
# Then run it
pnpm --filter=@agent-world/example-my-scenario dev
Architecture
agent-world/
packages/
core/ # Engine, EventBus, Plugin system, built-in plugins
brain-llm/ # LLM brain via Vercel AI SDK (OpenAI, Anthropic, DeepSeek, etc.)
memory/ # Memory plugins (Simple array, Tiered with importance scoring)
world/ # World plugins (Grid with coordinates, Abstract)
renderer-server/ # WebSocket renderer (server-side, integrates with Next.js)
renderer-client/ # WebSocket client (browser, zero dependencies)
ui/ # React hooks + UI components + primitives + server utils
examples/
spring-autumn/ # AI Spring & Autumn Period — 7 kingdoms (full scenario)
hello-world/ # Minimal 5-agent grid demo
template/ # Copy-this-to-start scaffold
Built as a monorepo with pnpm workspaces and Turborepo. Each package is independently publishable. Packages are built with tsup (ESM + CJS + DTS).
Key Design Decisions
- EventBus is the only communication channel between plugins. No direct plugin-to-plugin calls.
- TrackedBus wraps EventBus per-plugin for automatic cleanup on uninstall.
- Seeded RNG --
uid(), pickOne(), shuffle() auto-use seeded random inside engine scope for deterministic replay.
- Dual Brain -- swap LLM brain for IdleBrain or RuleBrain to run tests without API costs.
Roadmap
- Core engine with EventBus and Plugin system
- LLM Brain plugin (OpenAI, Anthropic, DeepSeek, Zhipu)
- Tiered memory with importance scoring
- WebSocket real-time renderer
- Full React UI component library
- Spring & Autumn Period scenario
- npm publish (all packages)
- Battle Royale scenario
- Stock Market scenario
- Dark Forest scenario
- 2D game engine visualization (Phaser/PixiJS)
- Replay system (rewind and scrub through past ticks)
- Plugin marketplace
Contributing
Contributions are welcome! Whether it's a new scenario, a plugin, a bug fix, or a feature request.
# Fork and clone
git clone https://github.com/YOUR_USERNAME/agent-world.git
# Install dependencies
pnpm install
# Build packages
pnpm build
# Run tests
pnpm test
# Start development
pnpm dev
Contributors
License
MIT -- Use it however you want.
If AgentWorld inspires you, consider giving it a star.
Every star helps others discover this project.