Design Persona

Guide the user through designing and creating a simulation persona using the coval CLI. Follow the phases below in order, asking questions at each step.

If $ARGUMENTS contains a use case (e.g. "insurance_claims", "customer_support") or agent name, use it to skip or pre-fill relevant questions.

Phase 0: Preflight + Inventory

Step 1: Check authentication

coval whoami

If not authenticated, guide the user:

coval login

This prompts for an API key. Get one at https://app.coval.dev/settings (Organization > Manage > API Keys).

If the user doesn't have a Coval account, direct them to https://coval.dev to sign up.

Step 2: Inventory existing resources

Run these in parallel:

coval personas list --format json
coval agents list --format json

Decision matrix:

• Has personas → present them as a numbered list: "You already have these personas. Want to reuse one, duplicate and modify, or create new?"
• No personas → proceed to Phase 1
• If $ARGUMENTS matches an existing agent name, pre-select that agent for Phase 1

Phase 1: Agent Context

Ask: "Which agent will this persona test?"

• If agents exist, present them as a numbered list to pick from
• If no agents exist, say: "No agents found. You can still create a persona — just tell me what type of agent it will test (voice, outbound-voice, chat, sms, websocket)."

If the user selects an agent, fetch its details:

coval agents get <agent_id> --format json

Extract from the response:

• Agent type (model_type) — determines whether voice settings are relevant and conversation initiator direction
• Agent name — for context in prompts
• Agent prompt (if available) — helps craft a better persona

Key type mappings:

• MODEL_TYPE_VOICE / MODEL_TYPE_OUTBOUND_VOICE → voice settings matter, conversation initiator depends on direction
• MODEL_TYPE_CHAT / MODEL_TYPE_WEBSOCKET / MODEL_TYPE_API / MODEL_TYPE_ENDPOINT → voice settings are defaults only (won't affect simulation)

Phase 2: Use Case Detection

Ask: "What does your agent do?"

Present the options:

• customer_support — Customer Support
• scheduling_booking — Scheduling & Booking
• sales — Sales
• insurance_claims — Insurance Claims
• healthcare_intake — Healthcare Intake
• restaurant_orders — Restaurant Orders
• debt_collection — Debt Collection
• it_helpdesk — IT Helpdesk
• other — Other (describe it)

Load references/persona-templates.md and select the template matching the chosen use case.

Present the template as a starting point:

Here's a starting persona for <use case>:

  Name:       <template name>
  Voice:      <voice>
  Language:   en-US
  Background: <background>
  Wait:       <wait seconds>s
  Prompt:     "<template description>"

Ask: "Use this as a starting point? (yes / customize name / start from scratch)"

Phase 3: Voice + Language

Load references/voice-options.md for available options.

Ask these questions:

1. "What language should the persona speak?"

   • en-US — English (US)
   • es-ES — Spanish (Spain)
   • fr-FR — French (France)
   • de-DE — German
   • pt-BR — Portuguese (Brazil)
   • ja-JP — Japanese

2. "Voice preference?"

   • Female: aria (clear, professional)
   • Male: callum (clear, professional)

For non-voice agents (chat, websocket, API), explain: "Since your agent is text-based, voice and language are stored as defaults but won't affect the simulation."

Phase 4: Environment + Behavior

Background Sound

Present options with recommendations based on the use case:

Value	Description	Recommended For
quiet	No background noise	Medical, legal, financial calls
office	Office ambient noise	Corporate, business, IT support
cafe	Restaurant/cafe noise	Casual, restaurant scenarios
airport	Airport/travel noise	Travel-related agents

Say: "Based on your <use case> use case, I'd recommend <recommended>. Use that or pick another?"

Wait Seconds

How long the persona waits before speaking after connection:

Value	Style	Best For
0.3	Fast responder	Restaurant orders, fast-paced interactions
0.5	Standard	Most inbound call scenarios
1.0	Slow / deliberate	Outbound calls, debt collection, elderly callers

Say: "The template uses <template wait>s. Keep that or adjust?"

Interruption Rate

How often the persona interrupts the agent mid-sentence:

Rate	Behavior	Best For
NONE	Never interrupts	Compliance testing, scripted flows
LOW	Rare interruptions	Standard testing, polite callers
MEDIUM	Occasional interruptions	Realistic conversation simulation
HIGH	Frequent interruptions	Stress testing, impatient callers

Explain: "NONE is best for validating scripted compliance flows. LOW is realistic for most callers. MEDIUM simulates natural conversation. HIGH stress-tests your agent's ability to handle interruptions."

Ask: "What interruption rate? (NONE / LOW / MEDIUM / HIGH)"

Note: Interruption rate is not yet available as a CLI flag. To set it after creation, use the Coval API: PATCH /v1/personas/{persona_id} with {"interruption_rate": "LOW"}.

Phase 5: Prompt Crafting

Start from the template's description as a base prompt.

Explain the key distinction: "The persona prompt defines WHO the caller is and HOW they behave — their personality, speaking style, and emotional state. It does NOT define what they ask about — that's handled by test cases."

Ask: "What specific behavior should this persona exhibit? For example:"

• "Speaks quickly and gets frustrated if put on hold"
• "Elderly caller who needs things repeated"
• "Non-native speaker who sometimes uses wrong words"
• "Aggressive caller who threatens to cancel"

Help the user refine the simulated_user_prompt by combining:

1. The template description as a foundation
2. The user's language choice applied to {language} placeholders
3. Any custom behavior the user describes

Present the final prompt for confirmation before proceeding.

Phase 6: Create + Confirm

Present a full summary before creating:

Ready to create this persona:

  Name:              <name>
  Voice:             <voice>
  Language:          <language>
  Background:        <background>
  Wait Seconds:      <wait>
  Interruption Rate: <rate>
  Prompt:            "<final prompt>"

Ask: "Create this persona? (yes / edit)"

Create the persona:

coval personas create \
  --name "<name>" \
  --voice "<voice>" \
  --language "<language>" \
  --prompt "<final prompt>" \
  --background "<background>" \
  --wait-seconds <wait> \
  --format json

Capture persona_id from the JSON response.

Confirm success:

Persona created!

  ID:   <persona_id>
  Name: <name>

  View: https://app.coval.dev/personas/<persona_id>

Phase 7: Next Steps

Suggest what the user can do next:

What's next?

  Build test cases for this persona:     /build-test-suite
  Configure evaluation metrics:          /configure-metrics
  Launch a quick evaluation:             /quick-eval

  Or manage this persona later:
  coval personas get <persona_id>
  coval personas update <persona_id> --prompt "new prompt"