English · 中文

---

AgentSociety is a framework for building LLM-based agent simulations in urban environments and research workflows.

Papers:

• AgentSociety 2 (recommended): arXiv:2607.11895
• AgentSociety (v1): arXiv:2502.08691

Machine-readable citations: CITATION.cff · citations.bib

Star History

Packages

This repository contains two main packages:

AgentSociety 2 (Recommended)

AgentSociety 2 is a modern, LLM-native agent simulation platform designed for social science research and experimentation.

pip install agentsociety2

Features:

• LLM-Native Design: Built from the ground up for LLM-driven agents
• Flexible Environment System: Modular environment components with hot-pluggable tools
• Multiple Reasoning Patterns: CodeGen (default), ReAct, Plan-Execute, Two-Tier, and Search routers
• Scalable Execution: Agents are workspace-bound stateless records driven by Ray Tasks, with env / LLM clients / trace / replay handles behind a single ServiceProxy
• Research Skills: Literature search, hypothesis generation, experiment design, paper writing
• Experiment Replay: Catalog-driven JSONL replay with DuckDB-powered reads and distributed tracing
• MCP Support: Model Context Protocol integration for tool extensibility

Documentation: agentsociety2.readthedocs.io

Source: packages/agentsociety2/

AgentSociety 1.x (Legacy)

AgentSociety 1.x is the original city simulation framework with gRPC-based environment integration.

pip install agentsociety

Features:

• City-scale simulation with Ray distributed computing
• Urban environment modules (mobility, economy, social)
• Multi-agent coordination and communication

Documentation: agentsociety.readthedocs.io

Source: packages/agentsociety/

Other Packages

• agentsociety-community: Community contributions for custom agents and blocks
• agentsociety-benchmark: Benchmarking utilities for agent evaluation

Project Structure

AgentSociety/
├── packages/
│   ├── agentsociety2/      # v2.x - Modern LLM-native platform (recommended)
│   ├── agentsociety/       # v1.x - Legacy city simulation
│   ├── agentsociety-community/
│   └── agentsociety-benchmark/
├── frontend/               # React web frontend
├── extension/              # VSCode extension
├── packages/agentsociety/docs/   # v1 Sphinx documentation (legacy)
└── packages/agentsociety2/examples/  # AS2 onboarding examples (basics / games / advanced)

Quick Start

AgentSociety 2

Before running the example, configure the LLM environment variables:

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"

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():
    # Agents are declared as metadata (specs); AgentSociety creates their workspaces in init().
    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())

AgentSociety 1.x

from agentsociety import AgentSociety

# See packages/agentsociety/README.md for usage

Requirements

• Python >= 3.11
• An LLM API key (OpenAI, Anthropic, or any litellm-supported provider)

Contributors

Thank you to everyone who has contributed to this project:

License

AgentSociety is licensed under the Apache License Version 2.0 except for the packages/agentsociety/commercial folder. See the LICENSE file for details.

Citation

If you use AgentSociety in your research, please cite the relevant paper(s). Prefer AgentSociety 2 when using the current platform (agentsociety2); cite AgentSociety (v1) when referring to the original large-scale city simulator.

See also CITATION.cff and citations.bib.

AgentSociety 2 (arXiv:2607.11895):

@misc{piao2026agentsociety2,
  title        = {{AgentSociety} 2: An Integrated Research Environment for Executable Social Science},
  author       = {Jinghua Piao and Jun Zhang and Haoyu Huang and Keming Zhang and Jing Yi Wang and Xinran Zhao and Songwei Li and Boyuan Sun and Jiayi Chang and Fengli Xu and Chunyan Wang and Fang Zhang and Ke Rong and Jun Su and Tianguang Meng and Yi Liu and Qingguo Meng and Yu Wang and Yong Li},
  year         = {2026},
  eprint       = {2607.11895},
  archiveprefix= {arXiv},
  primaryclass = {cs.CY},
  doi          = {10.48550/arXiv.2607.11895},
  url          = {https://arxiv.org/abs/2607.11895},
}

AgentSociety (v1) (arXiv:2502.08691):

@misc{piao2025agentsociety,
  title        = {{AgentSociety}: Large-Scale Simulation of {LLM}-Driven Generative Agents Advances Understanding of Human Behaviors and Society},
  author       = {Jinghua Piao and Yuwei Yan and Jun Zhang and Nian Li and Junbo Yan and Xiaochong Lan and Zhihong Lu and Zhiheng Zheng and Jing Yi Wang and Di Zhou and Chen Gao and Fengli Xu and Fang Zhang and Ke Rong and Jun Su and Yong Li},
  year         = {2025},
  eprint       = {2502.08691},
  archiveprefix= {arXiv},
  primaryclass = {cs.SI},
  doi          = {10.48550/arXiv.2502.08691},
  url          = {https://arxiv.org/abs/2502.08691},
}

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: agentsociety.fiblab2025@gmail.com