Skip to main content

Contents

The sections below include:
  1. Creating an AI agent: Basic steps to construct an AI agent.
  2. Administering questions: How to create questions and prompt agents to answer them.
  3. Selecting language models: Specify language models that you want to use to generate responses.
  4. Analyzing results: Examples of built-in methods for analyzing responses as datasets.
  5. Designing agent traits: How to construct agents with complex personas and traits.
  6. Converting surveys into EDSL: Import other surveys into EDSL to analyze and extend them with agents.
  7. 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.
Companion notebooks:

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:

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:
Here we create a simple 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:
We can access the traits directly:

Designing agent panels

We can also create panels of agents in an AgentList 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.)
Here we create a method to generate a list of agents with randomly selected combinations of traits:
Example usage:

Agent instructions

If we want to give all the agents a special instruction, we can optionally pass an instruction to the agents (this can also be done when the agents are created):
We can inspect the agents that have been created:
AgentList agents: 3;

Creating questions

An Agent 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):
We combine the questions into a Survey to administer them together:

Administering a survey

We administer a survey by calling the run method, after (optionally) adding agents with the by method:
We can show a list of all the components of the 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 a comment 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):
To select models for a survey, pass the model names to Model objects:
We add a 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:
Here we add a memory of 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 to inputstate 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 method add_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 of region 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 using Scenario 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:
Next we create a Scenario for each text that we want to insert in the question: