tsinghua-fib-lab/AgentSociety — Gitpedia

<div style="text-align: center; background-color: white; padding: 20px; border-radius: 30px;"> <img src="./static/agentsociety_logo.png" alt="AgentSociety Logo" width="200" style="display: block; margin: 0 auto;"> <h1 style="color: black; margin: 0; font-size: 3em;">AgentSociety: LLM Agents in Society</h1> </div> <p align="center"> <a href="./README.md">English</a> · <a href="./README_zh.md">中文</a> </p> <p align="center"> <a href="https://github.com/tsinghua-fib-lab/AgentSociety/stargazers"> <img src="https://img.shields.io/github/stars/tsinghua-fib-lab/AgentSociety?style=social" alt="GitHub Stars"> </a> <a href="https://github.com/tsinghua-fib-lab/AgentSociety/blob/main/LICENSE"> <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"> </a> <a href="https://pypi.org/project/agentsociety2/"> <img src="https://img.shields.io/pypi/v/agentsociety2.svg" alt="PyPI (v2)"> </a> <a href="https://pypi.org/project/agentsociety/"> <img src="https://img.shields.io/pypi/v/agentsociety.svg?label=pypi%20(v1)" alt="PyPI (v1)"> </a> </p> <p align="center"> <a href="https://agentsociety2.readthedocs.io/"> <img src="https://img.shields.io/badge/docs-v2%20(recommended)-brightgreen" alt="Documentation v2"> </a> <a href="https://agentsociety.readthedocs.io/"> <img src="https://img.shields.io/badge/docs-v1%20(legacy)-lightgrey" alt="Documentation v1"> </a> </p>

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

The paper is available at arXiv:

bibtex
@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.

bash
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, analysis, and paper workflows (via external paper-toolkit plugin)
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.

bash
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

Legacy packages remain in this monorepo for reference but are not part of active development, CI, or security scanning:

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

Active work focuses on AgentSociety 2 (packages/agentsociety2), the VS Code extension (extension/), and the web frontend (frontend/). See .github/agentsociety2-scope.yml.

Releases

AgentSociety 2 uses semantic versioning with Git tags:

text
agentsociety2-v{major}.{minor}.{patch}

Example: agentsociety2-v2.5.2 publishes:

PyPI: agentsociety2==2.5.2
VS Code extension: ai-social-scientist (version in extension/package.json)
GitHub Release: wheel, sdist, and .vsix attachments

Changelog: CHANGELOG.md

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

Set LLM environment variables before running examples (agentsociety2 validates them at import time):

bash
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"

python
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", "personality": "friendly and curious"},
    )
    env = CodeGenRouter(
        env_modules=[SimpleSocialSpace(agent_id_name_pairs=[(agent.id, agent.name)])]
    )
    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

python
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:

bibtex
@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}
}