CityAgent is an advanced framework specifically designed for building intelligent agents in urban simulation environments. With CityAgent, 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!
CityAgent 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 CityAgent in two different ways:
Follow these steps to set up CityAgent 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 pycityagent - 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 CityAgent in just a few minutes!
CityAgent 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:
text_request:
request_type: openai
api_key: <YOUR_API_KEY>
model: gpt-4o
img_understand_request:
request_type: none
api_key: none
model: none
img_generate_request:
request_type: none
api_key: none
model: none
simulator_request:
simulator:
server: https://api-opencity-2x.fiblab.net:58081
map_request:
mongo_uri: <MONGO_URI>
mongo_db: llmsim
mongo_coll: map_beijing5ring_withpoi_0424
cache_dir: ./cache
route_request:
server: http://api-opencity-2x.fiblab.net:58082
streetview_request:
engine: baidumap / googlemap
mapAK: baidumap api-key (if you use baidumap engine)
proxy: googlemap proxy (if you use googlemap engine)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.
We welcome contributions from the community!.
CityAgent 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.