Designing the agent

The agent is the interviewer. Designing it well is the highest-leverage configuration choice you make, because the agent's persona, tone, technique selection, and probing depth shape every node in every blueprint that uses it. Reuse one agent across many blueprints - don't create a new one per study. A good churn agent will run a dozen churn blueprints over a year. This chapter walks through every field of create_agent, with patterns, anti-patterns, and three worked personas you can copy.

system_prompt

The single most important field. It's the persona description the agent reads at the start of every interview, and everything downstream flows from it. Three patterns that work:

• Lead with role and posture, not job description. "You are a curious, patient interviewer probing for the real reason behind a churn decision" is a posture. "You will conduct interviews to gather feedback about the product" is a job description, and the agent will read it as instructions to be polite and generic.
• Name what the agent is for the respondent. "Your job is to make the respondent feel heard, then to push gently past their first answer." That sentence frames the relationship - the respondent is the source, the agent is the listener, and probing is part of the contract.
• State one or two operating principles the agent should hold under pressure. "Never argue with the respondent. Never offer your own opinion. If they ask what you think, redirect to what they think." Operating principles are what stop the agent from drifting when a respondent pushes back.

Anti-patterns to avoid:

• Long lists of question types or topics. Those belong in graph nodes, not the agent persona - the agent should not know your question list.
• Tone instructions that fight the tone field. Pick one place to set tone.
• Instructions that contradict the selected techniques - e.g., "challenge their assumptions" on an agent configured with active_listening and mirroring.

A good system prompt:

You are a curious, patient interviewer probing for the real reason behind a
cancellation. Make the respondent feel heard before you push. Never argue.
Never offer your own opinion. If they ask what you think, redirect to what
they think.

A bad one:

You are an AI assistant that conducts customer interviews. You will ask
questions about pricing, support, onboarding, features, and competitors.
Be friendly, professional, formal, and conversational. Try to challenge
their assumptions and validate their feelings.

The bad one duplicates what belongs in graph nodes, fights itself on tone, and stacks contradictory postures.

tone

Three values - conversational, formal, neutral.

conversational is the default for discovery, churn, sales debrief, and most product research. Short sentences, contractions, mirrors how the respondent talks. Highest disclosure of the three, because the agent reads as a peer.

formal is right when the respondent expects gravity: legal, compliance, executive interviews, public consultation. Disclosure is lower than conversational, but trust is higher on consequential decisions - the formality signals the conversation is being taken seriously.

neutral minimises the agent's social presence. Right for sensitive topics, large-N quant-feel research, and automated pulse checks where the agent is closer to a survey than a conversation. Pairs well with light probing depth.

One rule: don't override tone in the system_prompt. Pick one and set it once. An agent with tone: conversational and a system prompt that says "be formal and concise" will produce something that reads as neither.

techniques

Brief here - the depth lives in the techniques chapter. The field is an array; you can list several, and you should. The agent picks among them based on what the respondent just said and where the interview is in the graph.

A reasonable starter set for most interviews is active_listening and tell_me_more. Those two alone give a competent interviewer. Add specific techniques to that base depending on the objective: five_whys for root-cause work, calibrated_questions for negotiating-style probing, labelling for emotional content, funnel to reinforce broad-to-narrow node ordering. Browse the four groups - Opening and rapport, Going deeper, Surfacing the unsaid, Stress-testing claims - and pick from across them rather than stacking four from one group.

probing_depth

Three values. light uses techniques sparingly - at most one follow-up, only on visibly thin answers. moderate is the default - the agent probes when it detects a surface answer or a thread worth pulling. deep uses techniques hard - multiple follow-ups to reach a root cause or a concrete example. The full treatment lives in the probing chapter. If you are unsure, start at moderate and adjust after five real interviews - you will be wrong about depth more often than about technique selection.

model_preset vs model_config

The cost/quality tradeoff. Three preset values:

• economy - high-volume pulse checks, automated daily/weekly running interviews, anonymous or pseudonymous respondents. Cheaper, shorter context, more conservative probing.
• standard - the default. Most discovery, churn, research, and debrief work belongs here.
• premium - exec-level interviews, complex multi-thread probing, multilingual, low-N high-stakes work where a single transcript matters.

Reach for model_config (explicit provider and model for generation and assessment) only when you have a reason the preset cannot cover - a specific model your provider offers that isn't in a preset, or a procurement constraint (e.g., must use Anthropic only). Otherwise, prefer the preset. Presets let the platform upgrade the underlying model without you changing config, which matters when the frontier moves twice a year. Note also that create_agent rejects supplying both model_config and model_preset in the same call - pick one.

boundaries

Two sub-fields. Both are optional, both have sensible defaults, and both are worth setting explicitly so the agent's behaviour is legible to whoever inherits the config.

max_follow_ups_per_question - a hard ceiling on how many follow-ups the agent can issue per node. Recommended starting points: 1 for light, 2–3 for moderate, 4–5 for deep. Lower it for chat channels; respondents tire faster typing than they do speaking, and a fifth follow-up that lands fine in voice reads as nagging in chat.

off_topic_handling - three values. gentle_redirect for most discovery work, where losing rapport over a tangent costs more than the tangent itself does. strict_redirect for time-boxed compliance interviews where the agent has minutes, not the respondent's afternoon. allow only for genuinely exploratory work where the tangent might be the finding - usually paired with deep and a small N.

Three worked personas

Three full create_agent configs you can copy and adapt. Each one is opinionated on every field - that's the point.

Churn interviewer. This is the agent for "we want to understand why customers cancelled". Deep probing because root-cause work needs the follow-up budget; conversational tone because disclosure beats gravity here; five_whys and tell_me_more to push past the rehearsed reason, with active_listening and mirroring to keep rapport while pushing. gentle_redirect because a former customer's tangent often is the finding.

{
  "name": "Churn interviewer",
  "persona": {
    "system_prompt": "You are a curious, patient interviewer probing for the real reason behind a cancellation. Make the respondent feel heard before you push. Never argue. Never offer your own opinion. If they ask what you think, redirect to what they think.",
    "tone": "conversational"
  },
  "techniques": ["active_listening", "mirroring", "tell_me_more", "five_whys"],
  "probing_depth": "deep",
  "model_preset": "standard",
  "boundaries": {
    "max_follow_ups_per_question": 4,
    "off_topic_handling": "gentle_redirect"
  }
}

Sales debrief. A rep talks for two minutes after a call; structured data flows to CRM. Moderate depth - the rep has limited budget and the interview is repeated weekly. Conversational because the rep is venting in real time. calibrated_questions to extract structured reasons without sounding like a form, funnel to walk from the call shape to specific moments, active_listening as the base. strict_redirect because the interview is genuinely time-boxed.

{
  "name": "Sales debrief",
  "persona": {
    "system_prompt": "You are a sharp, time-respectful interviewer debriefing a sales rep right after a customer call. Get to the moments that mattered fast. Mirror the rep's language, do not editorialise. Keep the conversation moving - two minutes is the budget.",
    "tone": "conversational"
  },
  "techniques": ["active_listening", "calibrated_questions", "funnel"],
  "probing_depth": "moderate",
  "model_preset": "standard",
  "boundaries": {
    "max_follow_ups_per_question": 2,
    "off_topic_handling": "strict_redirect"
  }
}

Compliance check. Regulated training attestation, low-N per respondent but high volume across the org. Light depth because the interview's job is to confirm understanding, not to surface insight. Neutral tone to minimise the agent's social presence - this is closer to a structured form than a conversation. funnel to walk from broad context to specific attestation, socratic to surface whether the respondent actually understands the rule rather than just remembers the wording. Economy preset - volume justifies it. strict_redirect and a single follow-up.

{
  "name": "Compliance check",
  "persona": {
    "system_prompt": "You are a precise, neutral interviewer confirming a respondent's understanding of a compliance rule. Stay on topic. Ask for definitions and conditions in the respondent's own words. Do not coach, hint, or rephrase the rule for them.",
    "tone": "neutral"
  },
  "techniques": ["funnel", "socratic"],
  "probing_depth": "light",
  "model_preset": "economy",
  "boundaries": {
    "max_follow_ups_per_question": 1,
    "off_topic_handling": "strict_redirect"
  }
}

What to read next