AgentSociety 2: An LLM Agent Simulator With Replay Built In
AgentSociety 2 is a modern, LLM-native agent simulation platform designed for social science research and experimental design. It provides a flexible framework for creating and managing intelligent agents in simulated environments.
At a glance
- What is it?
- AgentSociety 2 is a Python framework for running LLM-driven social simulations, with workspace-bound stateless agents on Ray and a catalog-driven JSONL replay path. It is a research instrument, not a library you drop into a product.
- Who is it for?
- Adopt AgentSociety 2 if you are running a social science experiment where you need to re-read a past run, and you already have an LLM API key and a Ray-capable machine. Do not adopt it if you want a deterministic simulation with no per-step model calls, or if your agents must be long-lived objects that mutate themselves between turns.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem AgentSociety 2 Solves: Reproducible Social Simulation With Model Calls Inside the Loop
Most agent frameworks are built to complete a task. AgentSociety 2 is built to produce a record of a population behaving over time, which is a different engineering problem. The README describes it as a framework for building LLM-based agent simulations in urban environments and research workflows, and the package metadata says it is designed for social science research and experimental design. That framing matters because it dictates what the project spends its complexity budget on. The hard part is not getting one agent to answer a question. The hard part is running many agents across many simulated steps, calling a paid model at each step, and then being able to explain afterwards what happened and re-read it without rerunning the whole thing. The audience is researchers and research engineers, not product teams. If you are building a customer support bot, nothing here is aimed at you.
Workspace-Bound Stateless Agents on Ray, Behind a Single ServiceProxy
The architecture claim in the README is specific: agents are workspace-bound stateless records driven by Ray Tasks, with environment, LLM clients, trace and replay handles behind a single ServiceProxy. Read that as a deliberate split. The agent object you write does not hold its own conversation history, tool handles, or client connections. It reads from a workspace and writes back to it, and the run is executed as Ray tasks, which is how the framework gets distribution across cores or nodes. Everything the agent touches at runtime, including the model client and the trace recorder, is reached through one proxy object rather than being imported directly. The practical consequence is that an agent step becomes a function of workspace state plus inputs, which is what makes replay possible at all. The cost is that any state you want to survive a step has to go through the workspace, and that is a constraint you will feel the first time you try to cache something expensive on the agent.
The environment side is modular. The README lists a flexible environment system with hot-pluggable tools, and the quick start imports CodeGenRouter and SimpleSocialSpace from agentsociety2.env and agentsociety2.contrib.env respectively. A router holds environment modules, and SimpleSocialSpace is constructed with a list of agent_id_name_pairs, which is the mapping between numeric agent ids and display names. Reasoning is also pluggable: the README names CodeGen as the default, plus ReAct, Plan-Execute, Two-Tier and Search routers. That is five reasoning strategies in the same package, which is more than most research code ships, and it implies the router interface is stable enough to hold them all.
Getting a Run Started: Environment Variables, agent_specs, and the init/close Lifecycle
Installation is a single command: pip install agentsociety2. Python 3.11 or newer is required, and you need an API key for OpenAI, Anthropic, or any litellm-supported provider according to the README. Three environment variables carry the model configuration, and the README's example sets them in the shell:
export AGENTSOCIETY_LLM_API_KEY="your-api-key" export AGENTSOCIETY_LLM_API_BASE="https://api.openai.com/v1" export AGENTSOCIETY_LLM_MODEL="gpt-5.5"
The Python side is an asyncio program. You declare agents as metadata rather than objects. In the README example, agent_specs is a list of dictionaries with id, profile and config keys, and the comment states that AgentSociety creates their workspaces in init(). The society is constructed with agent_specs, an agent_class_name string such as "PersonAgent", an env_router, a start_t datetime and a run_dir Path. Then you call await society.init(), interact through await society.ask(...), and finish with await society.close().
Two details in that sequence are worth flagging. First, agent_class_name is a string, so the agent implementation is resolved by name rather than passed in as a class. That keeps the spec serializable and lets Ray workers construct the agent on their own side, but it also means a typo in the class name surfaces at init time, not at import time. Second, run_dir is passed at construction, which is where the trace and replay artifacts land. The README does not show the layout of that directory, so you will be reading it yourself before you can write analysis code against it.
Replay Is the Feature to Scrutinize: Catalog-Driven JSONL, DuckDB Reads, Distributed Tracing
The README describes experiment replay as catalog-driven JSONL replay with DuckDB-powered reads and distributed tracing. This is the most interesting part of the project and also the part with the least documentation in the supplied material. What can be said is that the run artifacts are JSONL, that a catalog indexes them, and that DuckDB is the query layer, which suggests the intended workflow is to point SQL at a completed run rather than to load it into Python objects. That is a sensible choice for simulation output, where you typically want to slice by agent id and time step and count events rather than iterate every record.
What cannot be confirmed from the material is the record schema, how the catalog is generated, or whether a replay can be resumed mid-run or only read. Those are the questions to answer before you design an experiment around this feature. The README also mentions MCP support for tool extensibility, which means tools can be supplied through the Model Context Protocol rather than only as in-repo environment modules. The reasoning routers and the environment modules are separate extension points, so a tool added through MCP and a tool added as an environment module are not the same kind of thing, even though both end up callable by an agent.
Where AgentSociety 2 Is the Wrong Tool
The stateless, workspace-bound design that makes replay tractable also removes a capability some simulations need. If your agents are supposed to accumulate private state that is not written to the workspace, or to hold open connections across steps, this model fights you. You will end up persisting everything, which is more code and more I/O per step than an object-oriented simulator would need.
Cost and determinism are the second constraint. Every reasoning step that goes through a router is a model call, and the framework offers no local-model path in the README beyond the litellm-supported provider list. A run with hundreds of agents over hundreds of steps is a large number of calls, and the README gives no guidance on budgeting, caching, or batching. If your research question can be answered by a rule-based model, AgentSociety 2 is the wrong instrument and you will pay for tokens to learn nothing new.
The third constraint is version sprawl. This repository ships two full frameworks under one roof. AgentSociety 1.x is described as the original city simulation framework with gRPC-based environment integration and is labelled legacy in the README, while AgentSociety 2 is labelled recommended. The quick start for v1 is a two-line stub that points at packages/agentsociety/README.md. If you find a tutorial or a paper that uses the v1 API, its imports do not carry over: v1 is `from agentsociety import AgentSociety`, v2 is `from agentsociety2.society import AgentSociety`. Check which one a piece of documentation is written against before following it.
How It Differs From Mesa, and From Plain Agent Frameworks
Mesa is the obvious comparison point for anyone coming from agent-based modeling. Mesa gives you a scheduler and a model class, and agents are ordinary Python objects that mutate in place across steps. It is deterministic by default and has no model dependency at all. AgentSociety 2 inverts both of those: agents are stateless records reconstructed from a workspace, and the interesting behavior comes from a language model rather than from hand-written transition rules. If you want to reproduce a published ABM result exactly, Mesa is the right tool and AgentSociety 2 is not, because an LLM call is not a deterministic transition function.
The other comparison is against general agent frameworks. Those typically optimize for one agent completing a task with tools, and their persistence story is a conversation log. AgentSociety 2 optimizes for many agents over simulated time, and its persistence story is a replayable run directory queried with DuckDB. The difference shows up in what each makes easy. In a task-oriented framework, asking an agent a question is the whole program. Here, the README's quick start uses society.ask() as a smoke test after init(), and the real work is the environment modules and the run artifacts. The research skills listed in the package description (literature search, hypothesis generation, experiment design, paper writing) push further in that direction, though the README does not document them, so treat that list as a claim to verify in the docs rather than a description of the quick start.
Maintenance Cost, Release Cadence, and the Apache-2.0 Boundary
The release history shows agentsociety2-v2.8.7 on 2026-09-09, v2.8.6 the same day, and v2.8.4 on 2026-07-27. Two releases in one day suggests active patching rather than a slow, scheduled cadence, and it means pinning a version is worth doing if you are mid-experiment. A patch landing while a long run is in flight is a real hazard for reproducibility, so record the exact version alongside your run directory.
The licence is Apache-2.0, with one carve-out stated in the README: the licence covers the project except for the packages/agentsociety/commercial folder, and the LICENSE file has the details. That folder sits inside the legacy v1 package, so if you are using agentsociety2 you are unlikely to touch it, but the boundary exists and you should read the licence file rather than assume the whole tree is uniformly Apache-2.0. This is a description of what the README states, not legal advice; if the commercial folder matters to your use, get your own reading of it.
The maintenance picture is otherwise ordinary for a research group's platform. There is a web frontend, a VSCode extension, a community package for custom agents and blocks, and a benchmark package for agent evaluation, all in the same repository. That breadth is useful if you want to contribute an environment module, and it is a lot of surface area to keep working. The two packages that matter for a first run are agentsociety2 and, if you need evaluation tooling, agentsociety-benchmark.
Editorial conclusion
Adopt AgentSociety 2 if you are running a social science experiment where you need to re-read a past run, and you already have an LLM API key and a Ray-capable machine. Do not adopt it if you want a deterministic simulation with no per-step model calls, or if your agents must be long-lived objects that mutate themselves between turns. Verify three things before committing: that your provider works through the litellm path the README implies, that the reasoning router you intend to use is present in your installed version, and that the run directory format produced by your run is the one your analysis code expects.
Community notes