Generative Agents
Run, inspect, replay, and demo multi-character human-behavior simulations in the Smallville game environment.
Per-dimension scores and reasoning
Evidence: README instructs users to manually create utils.py with hardcoded OpenAI API key, no least privilege or key management guidance; no user confirmation mechanism; data flow not transparent; sensitive data handling relies on user discretion; dependency security not mentioned; external effects (API costs) noted but no control; rollback only via saving simulations, no versioning; source attribution has author list but publisher unverified. Deductions: lack of security practices and transparency.
Evidence: README steps are clear, but no error handling or recovery guidance; dependency list exists but versions not pinned; failure messages (e.g., API hangs) mentioned but no detailed error handling. Deductions: dependency availability unverified, failure handling insufficient.
Evidence: Targets researchers and developers, provides multiple scenarios (simulation, replay, demo); capability boundaries not explicit; trigger commands (run, call) documented but precision moderate; environment fit only mentions Python 3.9.12 and browser suggestions. Deductions: capability boundaries and trigger precision insufficient.
Evidence: README well-structured, installation steps detailed; naming stable (e.g., base_the_ville...); examples and FAQ (Tips) present; known limitations (API hangs) mentioned; Apache-2.0 license clear; no version number or changelog; maintenance responsibility not explicit. Deductions: missing versioning and maintenance responsibility.
Evidence: Output (simulation results) can be saved and replayed, but format not standardized; marginal value high (research use); cost-benefit noted (API costs) but no optimization. Deductions: output usability limited, cost control insufficient.
Evidence: README cites paper, but no reproduction details; no cross-validation; facts and inferences not clearly separated. Deductions: lack of verifiability.
- Users must manage API keys themselves, posing leakage risk.
- Dependencies are not version-pinned, affecting reproducibility.
- Simulation costs can be high; monitor API expenses.
What does this agent do, and when should you use it?
This repository accompanies the paper “Generative Agents: Interactive Simulacra of Human Behavior” and contains its core simulation module and game environment. It runs as a Django environment server alongside a command-line simulation server launched from `reverie/backend_server/reverie.py`. A browser view presents the Smallville map and active characters while the simulation advances in game steps of ten seconds each. Saved simulations are stored under `environment/frontend_server/storage` and can later be replayed from a chosen time step or compressed for a demo. It is best suited to developers and researchers reproducing, customizing, debugging, or presenting this simulation environment, rather than teams seeking a ready-made chat interface.
It starts the environment with python manage.py runserver from environment/frontend_server, then starts the simulation server with python reverie.py from reverie/backend_server. The simulation server asks for a forked simulation and a new simulation name; a documented starting point is base_the_ville_isabella_maria_klaus. At the Enter option: prompt, run <step-count> advances the simulation, while /simulator_home shows the map and character movement in a browser; fin saves and exits, and exit exits without saving. It can load semicolon-separated agent memory records from CSV files through call -- load history the_ville/<history_file_name>.csv, and compress in reverie/compress_sim_storage.py prepares a saved simulation for demonstration. Saved simulations can be opened at /replay/<simulation-name>/<starting-time-step>, while compressed demos use /demo/<simulation-name>/<starting-time-step>/<simulation-speed>.
- A researcher reproducing the included setup can load
base_the_ville_n25and run the 25-character base simulation. - A developer studying the documented three-character scenario can fork
base_the_ville_isabella_maria_klausinto a named working simulation. - An experimenter who needs different initial character context can prepare a CSV matching the included history format and load it with
call -- load history. - A debugger investigating behavior after a saved point can open the replay route with the simulation name and starting time step.
- A presenter showing a completed scenario can compress the simulation first and select a demo speed from 1 through 5.
- A maintainer changing character names or map capacity can copy an existing base simulation and, when necessary, edit the map in Tiled.
What are this agent's strengths and limitations?
- Pairs a command-line simulation server with a Django environment server and browser map, so character movement is directly observable in Smallville.
- Includes both three-character and 25-character base simulations for starting from documented scenarios.
- Supports loading per-character memory records from CSV, giving initialization a concrete, editable input path.
- Separates saving, time-step replay, and compressed demo workflows for debugging and presentation.
- Core operation requires an OpenAI API key, and the documentation says API calls can hang at the hourly rate limit.
- Operation requires two local servers to run concurrently and uses terminal prompts to manage forks, runs, and saves.
- The documentation warns that simulations with many characters could be costly and recommends frequent saves to limit lost work after a restart.
- Changing agent names or increasing Smallville’s capacity may require direct map editing in Tiled.
How do you install or deploy this agent?
An OpenAI API key is required. Create reverie/backend_server/utils.py and configure at least openai_api_key and key_owner, along with the asset, storage, and environment paths shown in the repository documentation. Install every package listed in requirements.txt; the documented tested Python version is 3.9.12. Then change to environment/frontend_server and run python manage.py runserver to start the environment server.
How do you use this agent?
Keep the environment server running, then open another terminal in reverie/backend_server and run python reverie.py. Enter a base simulation such as base_the_ville_isabella_maria_klaus, followed by a new simulation name. Open http://localhost:8000/simulator_home, then enter a command such as run 100 in the simulation terminal; when finished, use fin to save or exit to discard changes. Saved output is kept in environment/frontend_server/storage and can be reopened through the replay route.
FAQ
What credentials are required?
reverie/backend_server/utils.py and set key_owner.How long is one simulation step?
run 100 executes 100 game steps.What should I do if API calls hang?
fin to reduce lost progress.How do I continue a saved simulation?
fin to save and exit. On the next simulation-server launch, enter that saved simulation name as the forked simulation.