joonspk-research/generative_agents

Generative Agents is the research code that accompanies the academic paper "Generative Agents: Interactive Simulacra of Human Behavior." It is a working simulation in which a small group of AI-driven characters live in a tiny pixel-art town and behave in a believable, human-like way: they remember what happened earlier, plan their days, talk with each other, and react to events in the world around them. The repository's purpose is to let other researchers and curious developers run this simulation themselves and watch or replay what the agents do. The system is split into two cooperating servers that you start side by side. The first is the environment server, which is implemented as a Django web project and runs the game world; you open it in a browser at a local address and see the map of "Smallville" with the agents on it. The second is the simulation server, a Python program called reverie.py, which is the brain of the system: it decides what each agent thinks and does on every step, calling out to OpenAI's API to generate language-model responses for memory, reflection, planning, and dialogue. One game step represents ten seconds of in-world time. You drive the simulation by typing commands such as "run 100" into a prompt, and after it finishes you can save with "fin", exit without saving, or keep going. Setup is hands-on but straightforward. You create a small utils.py file in the backend folder containing your OpenAI API key and a few file paths, install the listed Python requirements (the README notes the environment was tested on Python 3.9.12), and start both servers. There are starter simulations included, such as a three-character setup with Isabella Rodriguez, Maria Lopez, and Klaus Mueller, and you can fork those to begin your own. Saved simulations can be reopened and continued later, replayed in the browser as a debug animation, or compressed and shown as a polished demo at adjustable speed. You would clone this repository if you want to reproduce the paper's experiments, study how language models can drive believable agents in a shared world, or build research projects on top of the same scaffolding. The README warns that running the simulation can be costly because of OpenAI API usage and that the API can hang at the hourly rate limit, recommending that you save often. The full README is longer than what was provided.