Contents
The sections below include:- Creating an AI agent: Basic steps to construct an AI agent.
- Administering questions: How to create questions and prompt agents to answer them.
- Selecting language models: Specify language models that you want to use to generate responses.
- Analyzing results: Examples of built-in methods for analyzing responses as datasets.
- Designing agent traits: How to construct agents with complex personas and traits.
- Converting surveys into EDSL: Import other surveys into EDSL to analyze and extend them with agents.
- Constructing agents from survey data: Use survey responses to construct agents representing respondents.
Sample data: Cooperative Election Study Common Content, 2022
For purposes of demonstration, we use data from the Cooperative Election Study Common Content, 2022 in several ways:- In this notebook we use lists of respondent attributes from the Breakdown of National Vote for U.S. House (CES validated voters) (CES Guide 2022 pp.24-25) to design agents with combinations of the attributes, and then administer questions to them.
- In Working with CES data in EDSL we reconstruct the 2022 CES Pre-Election Questionnaire in EDSL. The formatted questions can be modified and administered to agents in new surveys as desired. The notebook also contains dictionaries of the CES questions and answer codebook for convenience in working with the data.
- In Creating agents for survey respondents we use the dataset of responses to the 2022 CES Pre-Election Questionnaire to create agents representing the respondents, and administer follow-on questions with them.
Reference & contact
Documentation for the EDSL package is available at https://docs/expectedparrot.com. You can also find example code, tutorials and notebooks for a variety of use cases. Please let us know if you have any questions or encounter issues working with this data:- Discord: https://discord.com/invite/mxAYkjfy9m
- Email: [email protected]
Technical setup
EDSL is compatible with Python 3.9-3.12. See instructions on installing the EDSL library and storing API keys for the language models that you want to use. In examples below where no model is specified, EDSL will use GPT 4 by default (an API key for OpenAI is required). We also show how to use different models.Creating an AI agent
In this section we show how to create an AI agent and give it desired attributes. For more details on constructing and using AI agents please see our documentation page on agents. We start by importing the tools for creating agents:Agent and pass it a dictionary of traits. We optionally include a narrative persona and also specify traits individually for use in segmenting and analyzing survey responses:
Designing agent panels
We can also create panels of agents in anAgentList and administer surveys to all of the agents at once. Here we construct combinations of traits from lists of respondent attributes in the CES Guide (see source details above). (Information can be imported from a variety of data source types; see documentation for details.)
Agent instructions
If we want to give all the agents a special instruction, we can optionally pass aninstruction to the agents (this can also be done when the agents are created):
Creating questions
AnAgent is designed to be assigned questions to answer. In this section we construct questions in the form of Question objects, combine them into a Survey, administer it to some sample agents (from above), and inspect the responses in the dataset of Results that is generated.
EDSL comes with many question types that we can select from based on the form of the response that we want to get back from the language model (free text, linear scale, checkbox, etc.). See examples of all question types.
Here we create a multiple choice question from the CES Pre-Election Questionnaire (the response will be a selection from the list of options that we include) and compose a follow-up free text question (the response will be unstructured text):
Survey to administer them together:
Administering a survey
We administer a survey by calling therun method, after (optionally) adding agents with the by method:
Results that have been generated, and see that the results include information about the agents, questions, models, prompts and responses:
We can select and print components of the
Results in a table (see examples of all methods for analyzing results):
Answer commentary
Question types other than free text automatically include acomment field for the agent to provide any unstructured commentary on its response to a question. This is useful in ensuring that responses are formatted as specified, providing an outlet for model verbosity. For example, in results.columns we can see that there is a field comment.pid3_comment. We can inspect this field as we do any other component of results. Here we also apply some pretty_labels to our table for readability:
Selecting language models
As mentioned above, if we do not specify a language model GPT 4 is used by default. We can also specify other language models to use in generating results, and compare responses for them. To see a list of all available models (uncomment the code):Model objects:
Model or list of models to a survey with the by method, the same as we do agents:
Learn more about specifying language models.
Question context & memory
Survey questions are administered asynchronously by default, for efficiency. If we want an agent to have the context of one or more prior questions when presented a new question we can apply a rule specifying the questions and answers to add to the new question prompt:q_CC22_309e when administering q_CC22_309f and show the prompts that were administered:
See examples of all methods for applying question context and memories (e.g., full memory of all prior questions, or a subset of questions).
Piping questions
We can also pipe individual components of questions into other questions. Here we use the answer toinputstate in the question text for CC22_320d:
Survey rules & conditions
We can apply survey rules and conditions to administer relevant follow-up questions based on responses to questions. For example, here we add skip rules to a set of questions by calling the methodadd_skip_rule() and passing the target question and the condition to evaluate (questions not administered will show a None response):
Here we use
add_stop_rule() to end the survey based on the response to an initial question (an option selection that makes the second question unnecessary):
Combining survey methods
Here we apply multiple methods at once: we add a memory ofregion to the prompt for inputzip, then pipe the answer to inputzip into the question text of votereg_f, and a stop rule if the answer to votereg is not “Yes” (i.e., do not administer votereg_f):
See more details on all survey methods.
Parameterizing questions
We can create variations of questions usingScenario objects for content that we want to add to questions. This allows us to efficiently administer multiple versions of questions at once. We start by using a {{ parameter }} in a question:
Scenario for each text that we want to insert in the question:
