AgentSociety is an advanced framework specifically designed for building agents in urban simulation environments. With AgentSociety, you can easily create and manage agents, enabling complex urban scenarios to be modeled and simulated efficiently.
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}
}
- Mind-Behavior Coupling: Integrates LLMs' planning, memory, and reasoning capabilities to generate realistic behaviors or uses established theories like Maslow’s Hierarchy of Needs and Theory of Planned Behavior for explicit modeling.
- Environment Design: Supports dataset-based, text-based, and rule-based environments with varying degrees of realism and interactivity.
- Interactive Visualization: Real-time interfaces for monitoring and interacting with agents during experiments.
- Extensive Tooling: Includes utilities for interviews, surveys, interventions, and metric recording tailored for social experimentation.
- 📢 02.07 - Initial update is now live!
Stay tuned for upcoming updates!
AgentSociety presents a robust framework for simulating social behaviors and economic activities in a controlled, virtual environment. Utilizing advanced LLMs, AgentSociety emulates human-like decision-making and interactions. Our framework is divided into several key layers, each responsible for different functionalities as depicted in the diagram below:
- Model Layer: At the core, this layer manages agent configuration, task definitions, logging setup, and result aggregation. It provides a unified execution entry point for all agent processes, ensuring centralized control over agent behaviors and objectives through task configuration.
- Agent Layer: This layer implements multi-head workflows to manage various aspects of agent actions. The Memory component stores agent-related information such as location and motion, with static profiles maintaining unchanging attributes and a custom data pool acting as working memory. The Multi-Head Workflow supports both normal and event-driven modes, utilizing Reason Blocks (for decision-making based on context and tools via LLMs), Route Blocks (for selecting optimal paths using LLMs or rules), and Action Blocks (for executing defined actions).
- Message Layer: Facilitating communication among agents, this layer supports peer-to-peer (P2P), peer-to-group (P2G), and group chat interactions, enabling rich, dynamic exchanges within the simulation.
- Environment Layer: Managing the interaction between agents and their urban environment, this layer includes Environment Sensing for reading environmental data, Interaction Handling for modifying environmental states, and Message Management for processing incoming and outgoing messages from agents.
- LLM Layer: Providing essential configuration and integration services for incorporating Large Language Models (LLMs) into the agents' workflow, this layer supports model invocation and monitoring through Prompting & Execution. It is compatible with various LLMs, including but not limited to OpenAI, Qwen, and Deepseek models, offering flexibility in model choice.
- Tool Layer: Complementing the framework's capabilities, this layer offers utilities like string processing for parsing and formatting, result analysis for interpreting responses in formats like JSON or dictionaries, and data storage and retrieval mechanisms that include ranking and search functionalities.
You can set up AgentSociety easily via pip:
Linux AMD64 or macOs
Python >= 3.9
pip install agentsocietyGet started with AgentSociety in just a few minutes!
To get started quickly, please refer to the examples folder in the repository. It contains sample scripts and configurations to help you understand how to create and use agents in an urban simulation environment.
Check our online document for detailed usage tutorial: AgentSociety Document.
We welcome contributions from the community!.
AgentSociety is licensed under the MIT License. See the LICENSE file for more details.
Feel free to reach out if you have any questions, suggestions, or want to collaborate!
Follow us: Stay updated with the latest news and features by watching the repository.
