AgentSociety is a framework for large-scale urban simulations driven by LLM-powered agents, designed to model and understand human behaviors and societal dynamics. It targets researchers and developers interested in complex social and economic simulations, offering a structured approach to agent creation, interaction, and environmental modeling.

How It Works

AgentSociety employs a layered architecture to manage agent complexity. The core Model Layer handles agent configuration and execution, while the Agent Layer implements multi-head workflows for planning, memory, and action execution using LLMs. Communication is facilitated by the Message Layer (P2P, P2G, group chat), and agent-environment interactions are managed by the Environment Layer. The LLM Layer integrates various LLMs (OpenAI, Qwen, Deepseek) for decision-making, and the Tool Layer provides utilities for data processing and analysis. This modular design allows for flexible integration of LLM capabilities and diverse simulation environments.

Quick Start & Requirements

• Install via pip: pip install agentsociety
• Requirements: Python >= 3.11 (Linux AMD64 or macOS)
• Documentation: AgentSociety Document
• Examples: Available in the repository's examples folder.

Highlighted Details

• Mind-Behavior Coupling: Integrates LLMs for realistic behavior generation or uses established psychological theories (Maslow's Hierarchy, Theory of Planned Behavior).
• Environment Design: Supports dataset-based, text-based, and rule-based environments with varying realism.
• Interactive Visualization: Real-time interfaces for monitoring and interacting with agents.
• Extensive Tooling: Includes utilities for interviews, surveys, interventions, and metric recording for social experimentation.

Maintenance & Community

• Initial update released on July 2, 2025.
• Contributions are welcomed.

Licensing & Compatibility

• MIT License.
• Permissive for commercial use and closed-source linking.

Limitations & Caveats

The project is newly released with an initial update, suggesting potential for ongoing development and potential for undiscovered issues or missing features.