AgentSociety 2: a Python framework for LLM agent simulations in social science

What AgentSociety 2 replaces, and who it is aimed at

Social scientists who want to run experiments on LLM agents have two bad options. They can wire an agent loop by hand, which means owning the scheduling, the environment state, the logging and the replay, or they can use a simulation framework built before LLM agents existed and bolt a model call into it. AgentSociety 2 is the Tsinghua FIB Lab's answer to the second problem. The README describes it as "a modern, LLM-native agent simulation platform designed for social science research and experimentation", and the repository ships a paper at arXiv:2607.11895 alongside the older v1 paper at arXiv:2502.08691.

The audience is narrow and stated. The topics list includes ai-social-scientist and ai-for-science, and the feature list names literature search, hypothesis generation, experiment design and paper writing as built-in research skills. This is not a general multi-agent orchestration library. It is a harness for running a study: declare agents, give them an environment, run, then replay the trace. The examples directory backs that up. The sample experiments are UBI, hurricane impact, inflammatory message, polarization, prospect theory and rumor spreader, which are recognizable social science scenarios rather than software demos.

One thing to settle before anything else: the repository hosts two packages. agentsociety2 is the recommended line and agentsociety is the legacy 1.x city simulation. They install from different PyPI names and are documented on separate Read the Docs sites. If you find a tutorial that imports from agentsociety, you are reading v1 documentation.

Workspace-bound agents, a ServiceProxy, and what Ray is doing here

The architectural claim in the README is compact: "Agents are workspace-bound stateless records driven by Ray Tasks, with env / LLM clients / trace / replay handles behind a single ServiceProxy". Read that against the quick start code and the design becomes concrete. You do not construct agent objects. You pass agent_specs, a list of dictionaries with an id, a profile and a config, and you pass agent_class_name as a string. The society creates the workspaces during init().

That is a real constraint, not a stylistic one. Because an agent is a record rather than a live object, the framework can schedule it as a Ray task and keep the process boundary clean. State that would otherwise live on the instance has to live in the workspace or behind the ServiceProxy. The payoff is that scaling out is a Ray concern rather than something you re-architect, and the cost is that anything you would normally do with an agent object between steps has to go through the workspace.

The environment side is modular in the same spirit. The README example builds a CodeGenRouter wrapping a SimpleSocialSpace, where the social space is constructed with agent_id_name_pairs mapping ids to names. Environment components are described as hot-pluggable. Reasoning is likewise pluggable, with CodeGen as the default and ReAct, Plan-Execute, Two-Tier and Search routers listed as alternatives. The router choice is the most consequential knob in the framework, because a CodeGen router generates code to interact with the environment while a ReAct router reasons in text steps. The README lists them without saying which are production-stable, which is a gap worth noting before you build a study on one.

Installing agentsociety2 and running the README example

The package is on PyPI under the name agentsociety2 and requires Python 3.11 or newer. The README gives the install as a single pip command:

pip install agentsociety2

Before the example will run you need an LLM endpoint. The README exports three variables, and the repository's .env.example adds coder and embedding variables plus a backend port and a workspace path. The three below are the ones the quick start names:

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 README states that any litellm-supported provider works, so the base URL and model are yours to change. Now the example itself. It declares one agent, wraps a social space in a CodeGenRouter, initialises the society, asks a single question and closes:

import asyncio
from datetime import datetime
from pathlib import Path
from agentsociety2.env import CodeGenRouter
from agentsociety2.contrib.env import SimpleSocialSpace
from agentsociety2.society import AgentSociety

async def main():
    agent_specs = [{"id": 1, "profile": {"name": "Alice"}, "config": {}}]
    env = CodeGenRouter(env_modules=[SimpleSocialSpace(agent_id_name_pairs=[(1, "Alice")])])
    society = AgentSociety(
        agent_specs=agent_specs,
        agent_class_name="PersonAgent",
        env_router=env,
        start_t=datetime.now(),
        run_dir=Path("run"),
    )
    await society.init()
    response = await society.ask("What's your name?")
    print(response)
    await society.close()

asyncio.run(main())

What you should see is the printed response from the single agent, and a run directory written under run_dir. The README does not document what that directory contains beyond the general mention of trace and replay handles, so treat the first run as a way to confirm credentials and routing rather than as a template for an experiment. If you prefer a container, the repository has a Dockerfile that builds the VSCode extension as a vsix and installs agentsociety2 in editable mode, but the README does not present it as the supported install path, so the pip route is the one with documentation behind it.

Where AgentSociety 2 is the wrong tool

The clearest limitation is the one the repository states by keeping v1 alive. AgentSociety 1.x is described as "the original city simulation framework with gRPC-based environment integration", with urban environment modules for mobility, economy and social, and city-scale simulation on Ray. AgentSociety 2 is LLM-native and modular, but the README does not claim it carries the same urban environment modules. If your study needs a populated city with a mobility model, the v2 feature list does not promise that, and you should be looking at the legacy package and its documentation instead.

The second limitation is the dependency on a hosted LLM. Every agent step in a CodeGen or ReAct router is a model call. The README's requirements section names an API key as a requirement, not an option. There is no described offline or local-model path in the README, so cost and rate limits are part of your experimental design whether you want them to be or not, and a run that fails halfway through is a run whose trace you now have to reconcile.

Third, the repository is much larger than the package. The top-level layout includes frontend, extension, examples, scripts and static directories, and the Makefile is dominated by extension and frontend targets such as build-webview and watch-extension. A reader who installs agentsociety2 from PyPI gets the Python framework, not the React frontend or the VSCode extension. That is fine, but it means the repository's activity is not a proxy for the package's surface area. The README is also silent on rollback and on version pinning between agentsociety2 releases, so if you need reproducible runs across a version bump, the README does not tell you how.

AgentSociety 2 against OASIS and the broader agent-society line

The obvious comparison point, and one people search for by name, is OASIS, described in those searches as open agent social interaction simulations with one million agents. The difference in approach is scale versus mechanism. OASIS-style work is organized around pushing agent counts into the millions on social platforms, which makes the platform dynamics the object of study. AgentSociety 2 is organized around a pluggable environment and a choice of reasoning routers, with the reasoning pattern itself as a variable you can set. If your question is how a population behaves at platform scale, the first framing fits better. If your question is whether a Plan-Execute router produces different outcomes than a ReAct router under the same social space, AgentSociety 2 is built for exactly that.

Socioverse is the other name that comes up in the same searches. The README does not describe it, so the honest comparison is limited to what AgentSociety 2 itself offers: a router abstraction, a modular environment, and a replay mechanism built on catalog-driven JSONL with DuckDB reads and distributed tracing. That replay layer is the part that distinguishes it from a general agent framework. Being able to read back a run as structured records is what makes the output usable as an experiment rather than as a transcript, and it is the feature most worth checking against your own requirements before you commit.

Releases, the commercial folder, and what to check before adopting

The release cadence is visible in the tags. agentsociety2-v2.8.7 and v2.8.6 both landed on 2026-09-09, and v2.8.4 landed on 2026-07-27. Two releases on one day suggests either a hotfix or a batch publish, and the release notes do not say which. The last push to the default branch was on 2026-09-09. The repository is not archived. Anyone planning to build on a specific version should read CHANGELOG.md, which is present at the top level, rather than inferring stability from the tag list.

The licence is Apache License Version 2.0, with one stated carve-out: the README says the licence applies "except for the packages/agentsociety/commercial folder". That is a v1 path, not a v2 path, but it means a blanket assumption that everything in the repository is Apache-2.0 is wrong. If you plan to redistribute or vendor any part of the tree, read LICENSE and the contents of that folder. This is not legal advice; it is a pointer to the file that matters.

Upgrade cost is the open question. The README documents the environment variables and the society constructor, but it does not document a migration path between agentsociety2 minor versions, and it does not describe how a run directory from one version behaves under another. The replay layer reads JSONL through DuckDB, which suggests the trace format is the compatibility surface to watch, but the README does not confirm that. Check CHANGELOG.md for the versions between your target and the current tag before you pin.

Editorial conclusion

Adopt AgentSociety 2 if your experiment is a study of how LLM agents behave under a controlled social mechanism and you can supply an API key and a Python 3.11 environment. Do not adopt it if you need a city-scale urban simulation with the v1 environment modules, or if you expect the pip package to carry the frontend and VSCode extension, which live in the repository rather than the wheel. Verify first that the reasoning router you intend to use is the one you want: CodeGenRouter is the default in the README example, but the README does not state which routers are stable. Then check the commercial folder exclusion before you plan any redistribution.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. tsinghua-fib-lab/AgentSociety on GitHub