design-persona

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Persona

设计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.

$ARGUMENTS

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

引导用户使用

coval

CLI设计并创建模拟Persona。请按以下阶段依次进行，在每个步骤中向用户提问。

如果

$ARGUMENTS

包含用例（例如"insurance_claims"、"customer_support"）或Agent名称，可利用该信息跳过或预填充相关问题。

Phase 0: Preflight + Inventory

阶段0：预检与资源盘点

Step 1: Check authentication

步骤1：检查认证状态

bash

coval whoami

If not authenticated, guide the user:

bash

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.

bash

coval whoami

若未认证，引导用户执行：

bash

coval login

此命令会提示输入API密钥。可前往https://app.coval.dev/settings（组织 > 管理 > API密钥）获取。

若用户没有Coval账号，引导其前往https://coval.dev注册。

Step 2: Inventory existing resources

步骤2：盘点现有资源

Run these in parallel:

bash

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

并行运行以下命令：

bash

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

决策矩阵：

已有Persona → 将其以编号列表形式展示："您已拥有以下Persona。是否要复用、复制修改或创建新的？"
无Persona → 进入阶段1
若
```
$ARGUMENTS
```
匹配现有Agent名称，为阶段1预选中该Agent

Phase 1: Agent Context

阶段1：Agent上下文

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:

bash

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)

提问："该Persona将测试哪个Agent？"

若存在Agent，以编号列表形式展示供选择
若不存在Agent，告知："未找到Agent。您仍可创建Persona — 只需告诉我它将测试哪种类型的Agent（voice、outbound-voice、chat、sms、websocket）。"

若用户选择某个Agent，获取其详情：

bash

coval agents get <agent_id> --format json

从响应中提取：

Agent类型（
```
model_type
```
）—— 决定语音设置是否相关以及对话发起方向
Agent名称—— 用于提示上下文
Agent提示词（若可用）—— 有助于编写更优质的Persona

关键类型映射：

```
MODEL_TYPE_VOICE
```
/
```
MODEL_TYPE_OUTBOUND_VOICE
```
→ 语音设置至关重要，对话发起者取决于方向

MODEL_TYPE_CHAT

MODEL_TYPE_WEBSOCKET

MODEL_TYPE_API

MODEL_TYPE_ENDPOINT

→ 语音设置仅为默认值（不会影响模拟）

Phase 2: Use Case Detection

阶段2：用例识别

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)"

提问："您的Agent用于什么场景？"

提供以下选项：

customer_support — 客户支持
scheduling_booking — 日程安排与预订
sales — 销售
insurance_claims — 保险理赔
healthcare_intake — 医疗问诊录入
restaurant_orders — 餐厅订单
debt_collection — 债务催收
it_helpdesk — IT服务台
other — 其他（请描述）

加载

references/persona-templates.md

并选择与所选用例匹配的模板。

将模板作为起点展示：

这是针对<use case>的初始Persona模板：

  名称:       <template name>
  语音:      <voice>
  语言:   en-US
  背景: <background>
  等待时长:       <wait seconds>s
  提示词:     "<template description>"

提问："是否以此为起点？（是 / 自定义名称 / 从头开始）"

Phase 3: Voice + Language

阶段3：语音与语言

Load

references/voice-options.md

for available options.

Ask these questions:

"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
"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."

加载

references/voice-options.md

获取可用选项。

提出以下问题：

"该Persona应使用哪种语言？"
- en-US — 英语（美国）
- es-ES — 西班牙语（西班牙）
- fr-FR — 法语（法国）
- de-DE — 德语
- pt-BR — 葡萄牙语（巴西）
- ja-JP — 日语
"语音偏好？"
- 女性：aria（清晰、专业）
- 男性：callum（清晰、专业）

对于非语音类Agent（chat、websocket、API），说明："由于您的Agent是文本型，语音与语言仅作为默认值存储，不会影响模拟。"

Phase 4: Environment + Behavior

阶段4：环境与行为

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?"

根据用例提供推荐选项：

值	描述	推荐场景
quiet	无背景噪音	医疗、法律、金融类通话
office	办公室环境噪音	企业、商务、IT支持
cafe	餐厅/咖啡馆噪音	休闲、餐厅场景
airport	机场/出行噪音	出行相关Agent

告知："基于您的<use case>用例，我推荐**<recommended>**。是否使用该选项或选择其他？"

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?"

连接后Persona开始说话前的等待时长：

值	风格	适用场景
0.3	快速响应	餐厅订单、快节奏交互
0.5	标准	大多数呼入通话场景
1.0	缓慢 / 从容	外呼通话、债务催收、老年来电者

告知："模板使用**<template wait>s**。是否保持该设置或调整？"

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"}
.

Persona在Agent说话中途打断的频率：

频率	行为	适用场景
NONE	从不打断	合规测试、脚本化流程
LOW	极少打断	标准测试、礼貌来电者
MEDIUM	偶尔打断	真实对话模拟
HIGH	频繁打断	压力测试、急躁来电者

说明："NONE最适合验证脚本化合规流程。LOW对大多数来电者来说较为真实。MEDIUM模拟自然对话。HIGH用于压力测试Agent处理打断的能力。"

提问："选择哪种打断频率？（NONE / LOW / MEDIUM / HIGH）"

注意： 打断频率目前尚未作为CLI flag提供。如需在创建后设置，请使用Coval API：
PATCH /v1/personas/{persona_id}
，请求体为
{"interruption_rate": "LOW"}
。

Phase 5: Prompt Crafting

阶段5：提示词编写

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:

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

Present the final prompt for confirmation before proceeding.

以模板描述为基础开始编写提示词。

说明关键区别："Persona提示词定义来电者是谁以及其行为方式——包括性格、说话风格和情绪状态。它不定义来电者的咨询内容——这由测试用例处理。"

提问："该Persona应表现出哪些特定行为？例如："

"说话语速快，若被搁置会感到沮丧"
"老年来电者，需要重复说明内容"
"非母语使用者，偶尔用词错误"
"情绪激动的来电者，威胁要取消服务"

通过以下方式帮助用户完善

simulated_user_prompt

：

以模板描述为基础
将用户选择的语言应用于
```
{language}
```
占位符
整合用户描述的任何自定义行为

在继续之前，展示最终提示词供用户确认。

Phase 6: Create + Confirm

阶段6：创建与确认

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:

bash

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>

在创建前展示完整摘要：

准备创建该Persona：

  名称:              <name>
  语音:             <voice>
  语言:          <language>
  背景音效:        <background>
  等待秒数:      <wait>
  打断频率: <rate>
  提示词:            "<final prompt>"

提问："是否创建该Persona？（是 / 编辑）"

创建Persona：

bash

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

从JSON响应中捕获

persona_id

。

确认创建成功：

Persona创建完成！

  ID:   <persona_id>
  名称: <name>

  查看地址：https://app.coval.dev/personas/<persona_id>

Phase 7: Next Steps

阶段7：后续步骤

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"

建议用户接下来可执行的操作：

下一步做什么？

  为该Persona构建测试用例：     /build-test-suite
  配置评估指标：          /configure-metrics
  启动快速评估：             /quick-eval

  或后续管理该Persona：
  coval personas get <persona_id>
  coval personas update <persona_id> --prompt "new prompt"