agentsociety

agentsociety

AgentSociety: Large-scale Social Simulation to Understand Human Behaviors and Society through LLM-driven Agents

Stars: 118

Visit
 screenshot

AgentSociety is an advanced framework designed for building agents in urban simulation environments. It integrates LLMs' planning, memory, and reasoning capabilities to generate realistic behaviors. The framework supports dataset-based, text-based, and rule-based environments with interactive visualization. It includes tools for interviews, surveys, interventions, and metric recording tailored for social experimentation.

README:

AgentSociety Logo

AgentSociety: LLM Agents in City

🚀 AgentSociety

LicenseOnline Documentation

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.

🌟 Features

  • 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.

📑 Table of Contents

  1. News
  2. Framework
  3. Setup
  4. QuickStart
  5. Contributing
  6. License

📰 News

  • 📢 02.07 - Initial update is now live!

Stay tuned for upcoming updates!

🛠️ Framework

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:

AgentSociety Framework Overview

Architectural Layers

  • 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.

⚙️ Setup

You can set up AgentSociety easily via pip:

Install via pip

Linux AMD64 or macOs

Python >= 3.9

pip install agentsociety

🚀 QuickStart

Get started with AgentSociety in just a few minutes!

Example Usage

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.

🤝 Contributing

We welcome contributions from the community!.

📄 License

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.


For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for agentsociety

Similar Open Source Tools

For similar tasks

For similar jobs