---

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

The paper is available at arXiv:

@article{piao2025agentsociety,
  title={AgentSociety: Large-Scale Simulation of LLM-Driven Generative Agents Advances Understanding of Human Behaviors and Society},
  author={Piao, Jinghua and Yan, Yuwei and Zhang, Jun and Li, Nian and Yan, Junbo and Lan, Xiaochong and Lu, Zhihong and Zheng, Zhiheng and Wang, Jing Yi and Zhou, Di and others},
  journal={arXiv preprint arXiv:2502.08691},
  year={2025}
}

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: ReAct, Plan-Execute, Code Generation, Two-Tier routers
• Research Skills: Literature search, hypothesis generation, experiment design, paper writing
• Experiment Replay: Full SQLite-based replay system
• 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
├── docs_v1/                # v1 Sphinx documentation
└── examples/               # Example experiments

Quick Start

AgentSociety 2

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

async def main():
    agent = PersonAgent(id=1, profile={"name": "Alice"})
    env = CodeGenRouter(env_modules=[SimpleSocialSpace(agent_id_name_pairs=[(1, "Alice")])])
    society = AgentSociety(agents=[agent], env_router=env, start_t=datetime.now())
    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)

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:

@article{piao2025agentsociety,
  title={AgentSociety: Large-Scale Simulation of LLM-Driven Generative Agents Advances Understanding of Human Behaviors and Society},
  author={Piao, Jinghua and Yan, Yuwei and Zhang, Jun and Li, Nian and Yan, Junbo and Lan, Xiaochong and Lu, Zhihong and Zheng, Zhiheng and Wang, Jing Yi and Zhou, Di and others},
  journal={arXiv preprint arXiv:2502.08691},
  year={2025}
}

Contact

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