https://github.com/joonspk-research/generative_agents Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Resources + Customer Stories + White papers, Ebooks, Webinars + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. {{ message }} joonspk-research / generative_agents Public * Notifications * Fork 314 * Star 3.6k Generative Agents: Interactive Simulacra of Human Behavior License Apache-2.0 license 3.6k stars 314 forks Activity Star Notifications * Code * Issues 12 * Pull requests 6 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights joonspk-research/generative_agents This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 1 branch 0 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/j] Use Git or checkout with SVN using the web URL. [gh repo clone joonsp] Work fast with our official CLI. Learn more about the CLI. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @joonspk-research joonspk-research Merge pull request #10 from guili618/my_dev ... 7373f4e Aug 10, 2023 Merge pull request #10 from guili618/my_dev To make the error display more detailed using traceback.print_exc() 7373f4e Git stats * 29 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time environment/frontend_server Readme udpated August 5, 2023 02:03 reverie Merge pull request #10 from guili618/my_dev August 10, 2023 04:55 .gitattributes Initial commit July 23, 2023 01:26 .gitignore Initial commit July 23, 2023 01:26 LICENSE License -- Apache July 29, 2023 16:59 README.md readme updated August 7, 2023 14:12 cover.png Cover added July 29, 2023 17:03 requirements.txt bump pip requirments to work on M1 Macs August 10, 2023 15:12 View code [ ] Generative Agents: Interactive Simulacra of Human Behavior Setting Up the Environment Step 1. Generate Utils File Step 2. Install requirements.txt Running a Simulation Step 1. Starting the Environment Server Step 2. Starting the Simulation Server Step 3. Running and Saving the Simulation Step 4. Replaying a Simulation Step 5. Demoing a Simulation Tips Simulation Storage Location Customization Author and Load Agent History Step 1. Starting Up a Base Simulation Step 2. Loading a History File Step 3. Further Customization Create New Base Simulations Authors and Citation Acknowledgements README.md Generative Agents: Interactive Simulacra of Human Behavior Smallville This repository accompanies our research paper titled "Generative Agents: Interactive Simulacra of Human Behavior." It contains our core simulation module for generative agents--computational agents that simulate believable human behaviors--and their game environment. Below, we document the steps for setting up the simulation environment on your local machine and for replaying the simulation as a demo animation. Generative Isabella Setting Up the Environment To set up your environment, you will need to generate a utils.py file that contains your OpenAI API key and download the necessary packages. Step 1. Generate Utils File In the reverie/backend_server folder (where reverie.py is located), create a new file titled utils.py and copy and paste the content below into the file: # Copy and paste your OpenAI API Key openai_api_key = "" # Put your name key_owner = "" 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 Replace with your OpenAI API key, and with your name. Step 2. Install requirements.txt Install everything listed in the requirements.txt file (I strongly recommend first setting up a virtualenv as usual). A note on Python version: we tested our environment on Python 3.9.12. Generative Klaus Running a Simulation To run a new simulation, you will need to concurrently start two servers: the environment server and the agent simulation server. Step 1. Starting the Environment Server Again, the environment is implemented as a Django project, and as such, you will need to start the Django server. To do this, first navigate to environment/frontend_server (this is where manage.py is located) in your command line. Then run the following command: python manage.py runserver Then, on your favorite browser, go to http://localhost:8000/. If you see a message that says, "Your environment server is up and running," your server is running properly. Ensure that the environment server continues to run while you are running the simulation, so keep this command-line tab open! (Note: I recommend using either Chrome or Safari. Firefox might produce some frontend glitches, although it should not interfere with the actual simulation.) Step 2. Starting the Simulation Server Open up another command line (the one you used in Step 1 should still be running the environment server, so leave that as it is). Navigate to reverie/backend_server and run reverie.py. python reverie.py This will start the simulation server. A command-line prompt will appear, asking the following: "Enter the name of the forked simulation: ". To start a 3-agent simulation with Isabella Rodriguez, Maria Lopez, and Klaus Mueller, type the following: base_the_ville_isabella_maria_klaus The prompt will then ask, "Enter the name of the new simulation: ". Type any name to denote your current simulation (e.g., just "test-simulation" will do for now). test-simulation Keep the simulator server running. At this stage, it will display the following prompt: "Enter option: " Step 3. Running and Saving the Simulation On your browser, navigate to http://localhost:8000/simulator_home. You should see the map of Smallville, along with a list of active agents on the map. You can move around the map using your keyboard arrows. Please keep this tab open. To run the simulation, type the following command in your simulation server in response to the prompt, "Enter option": run Note that you will want to replace above with an integer indicating the number of game steps you want to simulate. For instance, if you want to simulate 100 game steps, you should input run 100. One game step represents 10 seconds in the game. Your simulation should be running, and you will see the agents moving on the map in your browser. Once the simulation finishes running, the "Enter option" prompt will re-appear. At this point, you can simulate more steps by re-entering the run command with your desired game steps, exit the simulation without saving by typing exit, or save and exit by typing fin. The saved simulation can be accessed the next time you run the simulation server by providing the name of your simulation as the forked simulation. This will allow you to restart your simulation from the point where you left off. Step 4. Replaying a Simulation You can replay a simulation that you have already run simply by having your environment server running and navigating to the following address in your browser: http://localhost:8000/replay/ /. Please make sure to replace with the name of the simulation you want to replay, and with the integer time-step from which you wish to start the replay. For instance, by visiting the following link, you will initiate a pre-simulated example, starting at time-step 1: http://localhost:8000/replay/ July1_the_ville_isabella_maria_klaus-step-3-20/1/ Step 5. Demoing a Simulation You may have noticed that all character sprites in the replay look identical. We would like to clarify that the replay function is primarily intended for debugging purposes and does not prioritize optimizing the size of the simulation folder or the visuals. To properly demonstrate a simulation with appropriate character sprites, you will need to compress the simulation first. To do this, open the compress_sim_storage.py file located in the reverie directory using a text editor. Then, execute the compress function with the name of the target simulation as its input. By doing so, the simulation file will be compressed, making it ready for demonstration. To start the demo, go to the following address on your browser: http: //localhost:8000/demo/// . Note that and denote the same things as mentioned above. can be set to control the demo speed, where 1 is the slowest, and 5 is the fastest. For instance, visiting the following link will start a pre-simulated example, beginning at time-step 1, with a medium demo speed: http://localhost:8000/demo/ July1_the_ville_isabella_maria_klaus-step-3-20/1/3/ Tips We've noticed that OpenAI's API can hang when it reaches the hourly rate limit. When this happens, you may need to restart your simulation. For now, we recommend saving your simulation often as you progress to ensure that you lose as little of the simulation as possible when you do need to stop and rerun it. Running these simulations, at least as of early 2023, could be somewhat costly, especially when there are many agents in the environment. Generative Maria Simulation Storage Location All simulations that you save will be located in environment/ frontend_server/storage, and all compressed demos will be located in environment/frontend_server/compressed_storage. Generative Sam Customization There are two ways to optionally customize your simulations. Author and Load Agent History First is to initialize agents with unique history at the start of the simulation. To do this, you would want to 1) start your simulation using one of the base simulations, and 2) author and load agent history. More specifically, here are the steps: Step 1. Starting Up a Base Simulation There are two base simulations included in the repository: base_the_ville_n25 with 25 agents, and base_the_ville_isabella_maria_klaus with 3 agents. Load one of the base simulations by following the steps until step 2 above. Step 2. Loading a History File Then, when prompted with "Enter option: ", you should load the agent history by responding with the following command: call -- load history the_ville/.csv Note that you will need to replace with the name of an existing history file. There are two history files included in the repo as examples: agent_history_init_n25.csv for base_the_ville_n25 and agent_history_init_n3.csv for base_the_ville_isabella_maria_klaus. These files include semicolon-separated lists of memory records for each of the agents--loading them will insert the memory records into the agents' memory stream. Step 3. Further Customization To customize the initialization by authoring your own history file, place your file in the following folder: environment/frontend_server/ static_dirs/assets/the_ville. The column format for your custom history file will have to match the example history files included. Therefore, we recommend starting the process by copying and pasting the ones that are already in the repository. Create New Base Simulations For a more involved customization, you will need to author your own base simulation files. The most straightforward approach would be to copy and paste an existing base simulation folder, renaming and editing it according to your requirements. This process will be simpler if you decide to keep the agent names unchanged. However, if you wish to change their names or increase the number of agents that the Smallville map can accommodate, you might need to directly edit the map using the Tiled map editor. Generative Eddy Authors and Citation Authors: Joon Sung Park, Joseph C. O'Brien, Carrie J. Cai, Meredith Ringel Morris, Percy Liang, Michael S. Bernstein Please cite our paper if you use the code or data in this repository. @inproceedings{Park2023GenerativeAgents, author = {Park, Joon Sung and O'Brien, Joseph C. and Cai, Carrie J. and Morris, Meredith Ringel and Liang, Percy and Bernstein, Michael S.}, title = {Generative Agents: Interactive Simulacra of Human Behavior}, year = {2023}, publisher = {Association for Computing Machinery}, address = {New York, NY, USA}, booktitle = {In the 36th Annual ACM Symposium on User Interface Software and Technology (UIST '23)}, keywords = {Human-AI interaction, agents, generative AI, large language models}, location = {San Francisco, CA, USA}, series = {UIST '23} } Generative Wolfgang Acknowledgements We encourage you to support the following three amazing artists who have designed the game assets for this project, especially if you are planning to use the assets included here for your own project: * Background art: PixyMoon (@_PixyMoon _) * Furniture/interior design: LimeZu (@lime_px) * Character design: pipo (@pipohi) In addition, we thank Lindsay Popowski, Philip Guo, Michael Terry, and the Center for Advanced Study in the Behavioral Sciences (CASBS) community for their insights, discussions, and support. Lastly, all locations featured in Smallville are inspired by real-world locations that Joon has frequented as an undergraduate and graduate student---he thanks everyone there for feeding and supporting him all these years. About Generative Agents: Interactive Simulacra of Human Behavior Resources Readme License Apache-2.0 license Activity Stars 3.6k stars Watchers 36 watching Forks 314 forks Report repository Releases No releases published Packages 0 No packages published Contributors 4 * * * * Footer (c) 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time.