Generative Agents

Research & Resources ⚖️ Apache-2.0 🔴 No recent commits

Generative Agents is a simulation module and game environment for creating computational agents that mimic believable human behaviors, as described in the accompanying research paper. It solves the problem of simulating interactive, human-like social behaviors in a virtual town. It is intended for researchers and developers interested in generative AI and human-AI interaction.

✨ Key features

  • Simulates believable human behaviors in a virtual town environment.
  • Includes a Django-based environment server and a Python simulation server.
  • Supports saving, replaying, and demoing simulations.
  • Allows customization via agent history files and base simulations.
  • Provides pre-built base simulations with 3 or 25 agents.
  • Uses OpenAI API for agent decision-making.

🎯 Use cases

  • Research on generative agents and human behavior simulation.
  • Creating interactive virtual worlds with believable NPCs.
  • Studying social dynamics and emergent behaviors in multi-agent systems.
  • Developing interactive storytelling or game prototypes.

📦 Installation

🧰 Requirements: Python 3.9.12, OpenAI API key, and a web browser (Chrome or Safari recommended).

To set up the environment, you need to generate a utils.py file with your OpenAI API key and install the required packages.

  1. In the reverie/backend_server folder, create a file named utils.py and paste the content below, replacing <Your OpenAI API> with your key and <Name> with your name:
# Copy and paste your OpenAI API Key
openai_api_key = "<Your OpenAI API>"
# Put your name
key_owner = "<Name>"

maze_assets_loc = "../../environment/frontend_server/static_dirs/assets"
env_matrix = f"{maze_assets_loc}/the_ville/matrix"
env_visuals = f"{maze_assets_loc}/the_ville/visuals"

fs_storage = "../../environment/frontend_server/storage"
fs_temp_storage = "../../environment/frontend_server/temp_storage"

collision_block_id = "32125"

# Verbose 
debug = True
  1. Install the dependencies from requirements.txt (preferably in a virtual environment).
pip install -r requirements.txt

🚀 Usage

To run a simulation, you need to start two servers concurrently.

  1. Start the environment server (Django):
cd environment/frontend_server
python manage.py runserver

Then open http://localhost:8000/ in your browser to verify it's running.

  1. In a new terminal, start the simulation server:
cd reverie/backend_server
python reverie.py

When prompted, enter the forked simulation name, e.g., base_the_ville_isabella_maria_klaus, then a new simulation name, e.g., test-simulation.

  1. In the browser, go to http://localhost:8000/simulator_home. In the simulation server, type run <step-count> to run the simulation (e.g., run 100).

  2. To save and exit, type fin. To replay, visit http://localhost:8000/replay/<simulation-name>/<starting-time-step>/.

⚠️ Good to know

The simulation can be costly and may hang due to OpenAI API rate limits; saving frequently is recommended. The replay function is for debugging and does not optimize visuals.

❓ FAQ

What Python version is required?

The environment was tested on Python 3.9.12.

How do I get an OpenAI API key?

You need to create a utils.py file in reverie/backend_server and paste your OpenAI API key there.

Can I customize the agents' initial memories?

Yes, you can load a history file using the call -- load history command, and you can author your own CSV history files.

How do I save and resume a simulation?

Type fin to save and exit. The next time you run the simulation server, you can provide the saved simulation name as the forked simulation to resume.

📊 Repository

Forks🍴 3,092
Open issues🐛 146
Last commit🕒 Aug 5, 2024
Created📅 Jul 2023
License⚖️ Apache-2.0

🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.