AgentSociety is an advanced framework specifically designed for building intelligent agents in urban simulation environments. With AgentSociety, you can easily create and manage agents, enabling complex urban scenarios to be modeled and simulated efficiently.
- Modular Design: Plug-and-play components for agent behavior.
- Urban Environment Simulation: Built to simulate diverse urban scenarios.
- LLM Integration: Connects to language models for enriched agent behavior.
- Flexible Configuration: YAML-based configuration for easy customization.
- 📢 11.10 - Initial update is now live!
- 📢 2.x version is not compatible with 1.x version*
Stay tuned for upcoming updates!
AgentSociety is built with a multi-layered architecture that allows users to create and manage intelligent agents for urban environments in a scalable and flexible manner. The framework is divided into several key layers, each responsible for different functionalities as depicted in the diagram below:
-
Model Layer: Handles agent configuration, task definitions, logging setup, and result aggregation.
- Task Configuration: Defines agent behaviors and objectives.
- Unified Execution: Centralized entry point for agent processes.
-
Agent Layer: Implements multi-head workflows to manage agent actions.
- Memory: Stores agent-related information, such as location and motion.
- Static Profiles: Maintains unchanging agent attributes.
- Custom Data Pool: Functions as a working memory.
- Multi-Head Workflow: Supports both normal and event-driven modes.
- Reason Block: Utilizes LLMs to determine decisions based on context and tools.
- Route Block: Chooses the best path based on defined criteria using LLMs or rules.
- Action Block: Executes actions as per defined contexts and tools.
- Memory: Stores agent-related information, such as location and motion.
-
Message Layer: Facilitates agent communication through peer-to-peer (P2P), peer-to-group (P2G), and group chats.
-
Environment Layer: Manages interaction with the urban environment.
- Environment Sensing: Reads data from the environment.
- Interaction Handling: Writes or modifies environmental states.
- Message Management: Handles incoming and outgoing agent messages.
-
LLM Layer: Provides configuration and integration for using LLMs in the agent's workflow.
- Prompting & Execution: Supports model invocation and monitoring.
- Model Support: Compatible with various LLMs, such as OpenAI, Qwen, Deepseek, etc.
-
Tool Layer: Provides additional utilities to the agents.
- String Processing: Handles parsing and formatting.
- Result Analysis: Parses responses in formats like JSON or dictionaries.
- Data Storage & Retrieval: Includes ranking and search tools.
You can set up AgentSociety in two different ways:
Follow these steps to set up AgentSociety from scratch by cloning the repository. The project is built using Python and managed with Poetry.
- Clone the Repository
git clone [This Repository]
- Navigate to the Project Directory
cd agentsociety - Install Poetry (if not installed)
curl -sSL https://install.python-poetry.org | python3 - - Install Dependencies
poetry install
- Activate the Virtual Environment
poetry shell
This method is not yet available. Stay tuned for future updates!
Get started with AgentSociety in just a few minutes!
AgentSociety uses a configuration file written in .yaml format to manage settings for various components. Below is a sample configuration file (config_template.yaml) that showcases the structure:
llm_request:
request_type: openai
api_key: <YOUR_API_KEY>
model: gpt-4o
simulator_request:
simulator:
server: https://api-opencity-2x.fiblab.net:58081
map_request:
file_path: ./cache/map_beijing5ring_withpoi_0424.pbTo 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.
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.