Skip to contents

Create Focus Group Agents

Source: R/convenience_wrappers.R
create_agents.Rd

Creates participant agents from supplied records, direct personas, or the bundled ANES 2024 records, and adds a moderator.

Usage

create_agents(
  n_participants,
  config,
  demographics = NULL,
  survey_responses = NULL,
  direct_persona_descriptions = NULL,
  na_strings = fg_default_na_strings(),
  .runner = NULL
)

Arguments

n_participants

Integer number of participants to create

config

An explicit LLMR::llm_config for all agents.

demographics

Optional data frame, one row per participant. When it, survey_responses, and direct_persona_descriptions are all NULL, participants are drawn from the bundled ANES 2024 records. Columns with value labels (class haven_labelled) are an error unless the personas are supplied: create_agents_from_data() renders them, where this function would show their codes.

survey_responses

Optional data frame of survey answers, one row per participant, with value labels treated as for demographics.

direct_persona_descriptions

Optional character vector of pre-rendered participant personas. When supplied, these descriptions are used directly and are recycled in order if necessary. Demographics and survey responses remain attached as raw reporting fields.

na_strings

Character vector of regular expressions, matched ignoring case, that mark a text or factor value of demographics or survey_responses as a missing-data label, which the persona leaves out, by the rule described under Rendering answers in create_agents_from_survey(): a value that matches and starts with a negative code or one of 90 and above ("-9. Refused", "[-8] Don't know", "97. Refused"), or one that says nothing but the matched wording ("Refused to answer", "Don't know (VOL)"). Answers that use such words ("I keep missing the bus", "2. Refused to take sides") are kept, and numbers are never read this way. Each value left out is recorded in the rendering report, with a message naming the fields. The default is fg_default_na_strings(); character() turns the screening off.

.runner

Optional function used instead of live model calls and stored on every agent.

Value

A named list of FGAgent objects (participants + 1 moderator), keyed by agent ID. When the participants are drawn from the bundled ANES records, the list carries the source_rows attribute described in create_agents_from_survey(), giving the rows of anes_2024_personas that were drawn. Unless the personas are given in direct_persona_descriptions, the list also carries a rendering_report attribute recording each field supplied for each participant and whether the persona shows it; see persona_rendering_report().

Examples

cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b",
                        api_key = LLMR::llm_api_key_env("GROQ_API_KEY"))
agents <- create_agents(6, config = cfg)
names(agents)
#> [1] "P1"  "P2"  "P3"  "P4"  "P5"  "P6"  "MOD"
agents$P1$persona_description
#> [1] "You are a participant in a focus group.\nBackground: age: 45-54; sex: Male; education: High school credential; race/ethnicity: Black, non-Hispanic; marital status: Divorced; household income: Under $9,999; religion: Not religious; religion importance: Moderately important; religious attendance: Never; census region: Northeast; rural-urban self-identification: Suburban person; employment status: Working now (if also retired, disabled, homemaker or student, working 20 or more hrs/wk); home ownership: Rented for cash; children in household: Yes; union household: No; military service: Have never served on active duty; attention to politics: Some of the time.\nSpeak from this background as the conversation gives you reason to. Stay engaged without dominating; respond to the moderator and to what others say."

demo_data <- data.frame(
  age = c(22, 35, 28, 41, 19, 33),
  gender = c("Female", "Male", "Male", "Female", "Male", "Female"),
  education = c("Bachelor's", "Master's", "High School", "PhD",
                "Some College", "Bachelor's")
)
agents <- create_agents(6, config = cfg, demographics = demo_data)
agents$P2$persona_description
#> [1] "You are a participant in a focus group.\nBackground: age: 35; gender: Male; education: Master's.\nSpeak from this background as the conversation gives you reason to. Stay engaged without dominating; respond to the moderator and to what others say."