Python framework · MIT licensed

Simulate the world
with populations of AI agents

AgentSims is a Python framework for LLM-powered multi-agent simulation. Model geopolitics, markets, health crises, and elections as interacting agents that reason, remember, and act against a shared, persisted world state.

Replay a recorded simulation →
Recorded run
US-China Trade War
Ticks completed
15/15
Agent actions
60
Tokens used
20,917

Snapshot recorded September 19, 2026. These figures come from a bundled database and change only when the site is redeployed.

# With AgentSims installed from its source checkout.
# Set ANTHROPIC_API_KEY in your environment before running.
from agentsims import Simulation, Scenario, RoleCard, Tier

scenario = Scenario(
  name="US-China Trade War", domain="geopolitics", ticks=15,
  agents=[
    RoleCard(name="United States", type="country", tier=Tier.FULL),
    RoleCard(name="China", type="country", tier=Tier.FULL),
    RoleCard(name="WTO", type="institution", tier=Tier.LITE),
  ])

results = Simulation(scenario).run()
results.report()

How it works

A tick is one simulation round. Scenario events arrive, every agent gets a turn, and their actions update the world for the next round. The five steps below make up one tick.

Ticks have no fixed duration in seconds, days, or weeks. Playback only controls how quickly you view the recorded rounds.

The current trade-war examples stop after 15 rounds. That is a recording limit; convergence would require sustained stability in both world conditions and agent behavior.

01
Crawl
World events are injected each tick by a pluggable crawler. The shipped implementation is a scripted event generator; GDELT, NewsAPI and Yahoo Finance adapters are on the roadmap.
02
Think
All agents run in parallel via ThreadPoolExecutor. Each gets a context prompt built from Skynet memory + world state.
03
Act
Agents respond with structured JSON: reasoning (private), actions, and stance updates.
04
Update
The World Updater validates actions, resolves conflicts, and produces the next world state.
05
Remember
Skynet writes the full tick — world state, all agent responses, all events — to SQLite atomically.

Built for serious simulation

Three-tier execution
Assign agents to FULL, LITE, or deterministic RULE tiers. Reserve more capable models for key actors and use rules for background agents. Track actual token usage in each recorded run.
Skynet Memory System
Two layers: per-agent short-term + LLM-compressed long-term beliefs in-process; real-time SQLite persistence across all ticks, actions, and events on disk.
Crash recovery built in
Every tick is committed atomically. Interrupt at tick 47 of 100 — the DB has all 47 ticks intact. Stale runs auto-marked interrupted on next open.
Parallel execution
All agents run concurrently via ThreadPoolExecutor(max_workers=N). API latency, not framework overhead, is the bottleneck.
Pluggable everything
Swap in your own LLM backend, data crawler, or world updater by subclassing BaseLLM, BaseCrawler, or BaseWorldUpdater.
Full observability
Query any run's world state, agent reasoning, actions, or events by run ID and tick. Full replay via db.replay(run_id).

Explore a world in motion

Replay a recorded scenario and follow how agents, actions, and world metrics change over time.

Replay a run →