Generative Agents
Run, inspect, replay, and demo multi-character human-behavior simulations in the Smallville game environment.
- Source repo
- joonspk-research/generative_agents
- Stars
- ★ 22k
- Last updated
- 3y ago
- License
- Apache-2.0
- FA score
- 29/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A researcher reproducing the included setup can load
base_the_ville_n25and run the 25-character base simulation. - Not a fit if
- Teams wanting a ready-made chat interface
- Users unwilling to run two local servers and terminal commands
- Source review
- 29/100 · Major gaps 8 safety controls not found
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.
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.
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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Generative Agents This agent | 29 · Major gaps | CLIFree + model costs | ★ 22k | 3y ago | — | OpenAI API |
| ChatArena | 32 · Major gaps | Library / SDKFree + model costs | ★ 1.6k | 1y ago | Python | OpenAI API |
| AgentVerse | 28 · Major gaps | CLIFree + model costs | ★ 5.2k | 2y ago | JavaScript | OpenAI API |
| Webwright Browser Coding Agent | 66 · Some gaps | CLIFree + model costs | ★ 6.1k | 10d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- Users must manage API keys themselves, posing leakage risk.
- Dependencies are not version-pinned, affecting reproducibility.
- Simulation costs can be high; monitor API expenses.
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.