English · 中文

---

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: 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)
└── examples/               # Example experiments

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:

@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