This project introduces a novel agent architecture that simulates the attitudes and behaviors of real individuals by applying large language models (LLMs) to qualitative interviews about their lives. These agents replicate participants' responses on various social science measures, providing a foundation for new tools to investigate individual and collective behavior.
In the coming months, the authors at Stanford University plan to make available generative agents of 1,000 people—based on 2,000 hours of interviews—via a restricted API for research purposes. To support research while protecting participant privacy, this restricted access will offer a two-pronged system:
- Open Access to Aggregated Responses on Fixed Tasks: Researchers can access aggregated data to analyze general trends and patterns.
- Restricted Access to Individual Responses on Open Tasks: Researchers can request access to individual agents' responses for more detailed studies, subject to a review process ensuring ethical considerations are met.
This codebase offers two main components:
- Codebase for Creating and Interacting with Generative Agents: Tools to build new agents based on your own data and interact with them. Query agents with surveys, experiments, and other stimuli to study their responses.
- Demographic Agent Banks: A bank of over 3,000 agents created using demographic information from the General Social Survey (GSS) as a starting point to explore the codebase. Note: The names and addresses are fictional.
Additionally, to provide users with a sense of the interview-based agents, we offer an example generative agent of one of the authors, created using the same interview protocol used in our paper.
- Installation
- Repository Structure
- Usage
- Sample Agent
- Agent Bank Access
- Contributing
- License
- References
- Contact
- Python 3.7 or higher
- An OpenAI API key with access to GPT-4 or GPT-3.5-turbo models
Install the required Python packages using pip:
pip install -r requirements.txtCreate a settings.py file in the simulation_engine folder (where example-settings.py is located). Place the following content in settings.py:
from pathlib import Path
OPENAI_API_KEY = "YOUR_API_KEY"
KEY_OWNER = "YOUR_NAME"
DEBUG = False
MAX_CHUNK_SIZE = 4
LLM_VERS = "gpt-4o-mini"
BASE_DIR = f"{Path(__file__).resolve().parent.parent}"
POPULATIONS_DIR = f"{BASE_DIR}/agent_bank/populations"
LLM_PROMPT_DIR = f"{BASE_DIR}/simulation_engine/prompt_template"Replace "YOUR_API_KEY" with your actual OpenAI API key and "YOUR_NAME" with your name.
genagents/: Core module for creating and interacting with generative agentsgenagents.py: Main class for the generative agentmodules/: Submodules for interaction and memory managementinteraction.py: Handles agent interactions and responsesmemory_stream.py: Manages the agent's memory and reflections
simulation_engine/: Contains settings and global methodsprompt_template/: All LLM prompts used in this projectsettings.py: Configuration settings for the simulation engineglobal_methods.py: Helper functions used across modulesgpt_structure.py: Functions for interacting with the GPT modelsllm_json_parser.py: Parses JSON outputs from language models
agent_bank/: Directory for storing agent datapopulations/: Contains pre-generated agentsgss_agents/: Demographic agent data based on the GSSsingle_agent/: Example agent data (see Sample Agent)
README.md: This readme filerequirements.txt: List of Python dependencies
To create a new generative agent, use the GenerativeAgent class from the genagents module:
from genagents.genagents import GenerativeAgent
# Initialize a new agent
agent = GenerativeAgent()
# Update the agent's scratchpad with personal information
agent.update_scratch({
"first_name": "John",
"last_name": "Doe",
"age": 30,
"occupation": "Software Engineer",
"interests": ["reading", "hiking", "coding"]
})The update_scratch method allows you to add personal attributes to the agent, which are used in interactions.
You can ask the agent to respond to categorical survey questions:
questions = {
"Do you enjoy outdoor activities?": ["Yes", "No", "Sometimes"]
}
response = agent.categorical_resp(questions)
print(response["responses"])For numerical questions:
questions = {
"On a scale of 1 to 10, how much do you enjoy coding?": [1, 10]
}
response = agent.numerical_resp(questions, float_resp=False)
print(response["responses"])Have the agent generate open-ended responses:
dialogue = [
("Interviewer", "Tell me about your favorite hobby."),
]
response = agent.utterance(dialogue)
print(response)Agents have a memory stream that allows them to remember and reflect on experiences.
agent.remember("Went for a hike in the mountains.", time_step=1)Agents can reflect on their memories to form new insights:
agent.reflect(anchor="outdoor activities", time_step=2)You can save the agent's state to a directory for later use:
agent.save("path/to/save_directory")To load an existing agent:
agent = GenerativeAgent(agent_folder="path/to/save_directory")A sample agent is provided in the agent_bank/populations/single_agent/ directory. This agent includes a pre-populated memory stream and scratchpad information for demonstration purposes.
You can load and interact with the sample agent as follows:
agent = GenerativeAgent(agent_folder="agent_bank/populations/single_agent")
# Interact with the agent
questions = {
"Do you enjoy outdoor activities?": ["Yes", "No", "Sometimes"]
}
response = agent.categorical_resp(questions)
print(response["responses"])Due to participant privacy concerns, the full agent bank containing over 1,000 generative agents based on real interviews is not publicly available at the moment. However, we plan to make aggregated responses on fixed tasks accessible for general research use in the coming months. Researchers interested in accessing individual responses on open tasks can request restricted access by contacting the authors and following a review process that ensures ethical considerations are met.
We welcome contributions to enhance the functionality and usability of this project. If you are interested in contributing, please follow these steps:
- Fork the Repository: Click on the "Fork" button at the top right corner of this page to create a copy of the repository on your GitHub account.
- Clone the Forked Repository: Use
git cloneto clone the repository to your local machine. - Create a New Branch: Create a new branch for your feature or bug fix.
git checkout -b feature/your-feature-name
- Make Changes: Implement your feature or fix the bug.
- Commit Changes: Commit your changes with a descriptive commit message.
git commit -am "Add new feature: your feature name" - Push to GitHub: Push your changes to your forked repository.
git push origin feature/your-feature-name
- Submit a Pull Request: Go to the original repository and create a pull request from your forked repository.
Please ensure that your code follows the project's coding conventions and includes relevant tests and documentation.
This project is licensed under the MIT License.
Please refer to the original paper for detailed information on the methodology and findings:
- Park, J. S., Zou, C. Q., Shaw, A., Hill, B. M., Cai, C., Morris, M. R., Willer, R., Liang, P., & Bernstein, M. S. (2024). Generative Agent Simulations of 1,000 People.
We thank Akaash Kolluri (Github: akaashkolluri) for the help setting up this open source repository.
In addition, we thank Douglas Guilbeault, Amir Goldberg, Diyi Yang, Jeff Hancock, Serina Chang for their insights and discussions.
For questions or inquiries, please contact the corresponding author:
- Joon Sung Park: [email protected]
