> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas

> The callers your simulations run as

<Info>
  **Prefer to keep this in your repo?** Personas can be defined as [config as code](/documentation/config-as-code/personas) (YAML in git, applied with the [CLI](/documentation/sdks/cli)) instead of built in the dashboard.
</Info>

## Quickstart

Reuse a built-in persona, or create your own:

<Tabs>
  <Tab title="Node">
    ```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    // Reuse a built-in persona (list includes Roark's starter set)
    const personas = await client.simulationPersona.list({ limit: 50 })

    // Or create a custom one
    const persona = await client.simulationPersona.create({
      name: 'Busy Parent',
      language: 'EN',
      accent: 'US',
      gender: 'FEMALE',
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    personas = client.simulation_persona.list(limit=50)

    persona = client.simulation_persona.create(
        name="Busy Parent", language="EN", accent="US", gender="FEMALE",
    )
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    roark simulation persona list --limit 50
    roark simulation persona create --name "Busy Parent" --language EN --accent US --gender FEMALE
    ```
  </Tab>
</Tabs>

## Overview

A persona is the caller a simulation runs as. It bundles who the customer is (language, accent, gender, base emotion, and how they speak) into a reusable caller that you pin to a [customer flow](/documentation/simulation-testing/customer-flows) variant. Roark ships a starter set of **Built-in** personas; add your own **Custom** personas for the callers you care about.

Open **Personas** in the sidebar to see every persona in your project. From the hub you can search, create new personas, and edit or delete the custom ones.

## Persona fields

Click **New persona** to open the persona dialog. Every field except Name is optional or has a sensible default.

| Field               | Options                                                                | Default  | Notes                                                                |
| :------------------ | :--------------------------------------------------------------------- | :------- | :------------------------------------------------------------------- |
| **Name**            | Free text                                                              | N/A      | Required. Use something descriptive, e.g. "Returning client: Sarah"  |
| **Display name**    | Free text                                                              | Name     | Shown in pickers and variant chips. Defaults to the name             |
| **Description**     | Free text                                                              | N/A      | One or two sentences on who this caller is (hub dialog only)         |
| **Language**        | 18 languages                                                           | English  | See the full list below                                              |
| **Accent**          | 23 accents                                                             | American | Includes American (Southern) as a distinct option                    |
| **Gender**          | Female, Male, Neutral                                                  | Female   | Affects the synthesized voice                                        |
| **Base emotion**    | Neutral, Cheerful, Frustrated, Skeptical, Rushed, Distracted, Confused | Neutral  | The caller's underlying emotional tone                               |
| **Speech pace**     | Very slow, Slow, Normal, Fast, Very fast                               | Normal   | How quickly the persona speaks                                       |
| **Clarity**         | Clear, Vague, Rambling                                                 | Clear    | How directly they express themselves                                 |
| **Response timing** | Quick, Normal, Relaxed                                                 | Normal   | How quickly the persona responds to pauses in conversation           |
| **Disfluencies**    | On / Off                                                               | Off      | Natural ums, ahs, false starts. Off means the persona speaks cleanly |

<AccordionGroup>
  <Accordion title="Language options">
    English, Spanish, French, German, Italian, Portuguese, Dutch, Arabic, Greek,
    Hebrew, Hindi, Indonesian, Malay, Tagalog, Thai, Japanese, Chinese, Turkish
  </Accordion>

  <Accordion title="Accent options">
    American, American (Southern), British, Australian, New Zealand, Indian,
    Spanish, French, German, Italian, Portuguese, Dutch, Greek, Arabic, Hebrew,
    Indonesian, Malaysian, Filipino, Singaporean, Hong Kong, Thai, Japanese,
    Turkish
  </Accordion>
</AccordionGroup>

<Note>
  Background noise is not a persona setting. It's configured per flow variant
  via the **Environment** chip (Silent, Office, Coffee shop, City street,
  Driving, Airport, Children playing, Thunderstorm). See [Customer
  flows](/documentation/simulation-testing/customer-flows).
</Note>

## Built-in vs Custom

Every persona has a source badge:

* **Built-in**: the starter set Roark ships with each project. Built-in personas are read-only in the hub: they have no edit or delete actions.
* **Custom**: personas you create. Fully editable and deletable.

You can still start from a Built-in persona: load it in the inline persona editor inside a flow, tweak it, and save. Roark shows the note "System persona: saving creates an editable copy." and creates a Custom copy with your changes, leaving the original intact.

<Warning>
  Deleting a persona doesn't break existing flows silently, but customer-flow
  variants pinned to it will need a new persona.
</Warning>

## Pinning personas to flow variants

Personas do their work inside customer flows. Each variant in a flow carries a chip strip (**Persona · Environment · Variables**) and the Persona chip shows which caller that variant runs as.

* The flow's **default variant** (the happy path) must always have a concrete persona. New flows are pre-seeded with the Built-in **Polite First-Time Caller** persona (or your project's first persona if that one isn't available).
* **Non-default variants inherit** the default variant's persona automatically. The chip shows the name in muted italics, e.g. "Sarah (inherited)". Pin a different persona on a variant to override the inheritance for that variant only.

### The inline persona editor

Clicking a variant's Persona chip opens an inline editor with two paths:

<Steps>
  <Step title="Pick an existing persona">
    Click **Pick from existing personas** to open the "Pick a persona" dialog.
    Search by name, language, or accent; each row shows the persona's name,
    Language · Accent, and its Built-in or Custom badge. Picking one pins it to
    the variant.
  </Step>

  <Step title="Or author a caller in place">
    Fill in the same fields as the hub dialog (minus Description) directly in
    the panel (including a color-coded Base emotion pill grid) and click
    **Create & use** to create the persona and pin it in one step.
  </Step>

  <Step title="Tweak a pinned persona">
    With a persona pinned, the editor shows "Pinned: \<name>". Editing a
    Custom persona and clicking **Save changes** updates it in place. Editing a
    Built-in persona creates an editable Custom copy instead.
  </Step>
</Steps>

<Tip>
  Because Custom personas are shared across flows, "Save changes" in the inline
  editor updates that persona everywhere it's pinned. If you want a variant-only
  tweak, create a new persona instead.
</Tip>

## Personas at run time

When a [run](/documentation/simulation-testing/running-simulations) executes, each simulated call is placed as the persona pinned to its flow variant. On the resulting call records, the persona appears as `simulationPersonaName`: the display name of the persona used in the simulation that created the call.

If a persona used by a run has properties without values, Roark prompts for them in the runtime-variables step before the run starts; the values you enter are saved onto the persona itself, so future runs reuse them. See [Variables](/documentation/simulation-testing/variables).

## API

Manage personas programmatically to build them from real customer data or wire persona management into CI:

* **Create Persona**: `POST /v1/persona`
* **Update Persona**: `PUT /v1/persona/{personaId}`
* **Get Persona**: `GET /v1/persona/{personaId}`
* **List Personas**: `GET /v1/persona`

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/persona \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emma Johnson",
    "language": "EN",
    "accent": "US",
    "gender": "FEMALE",
    "baseEmotion": "NEUTRAL",
    "speechPace": "NORMAL",
    "speechClarity": "CLEAR",
    "responseTiming": "NORMAL",
    "hasDisfluencies": false,
    "properties": {
      "accountNumber": "ACC-123456",
      "zipCode": "90210"
    }
  }'
```

<Note>
  The API exposes some capabilities the platform UI doesn't surface: a
  `backstoryPrompt`, key/value `properties`, `secondaryLanguage`, idle-message
  settings, and the behavioral fields `backgroundNoise`, `intentClarity`,
  `confirmationStyle`, and `memoryReliability`. Personas created in the UI use
  system defaults for these (`NONE`, `CLEAR`, `EXPLICIT`, `HIGH`); set them via
  the API if you need finer control.
</Note>

For all parameters and response formats, see the [Persona API Reference](/api-reference/simulation-persona/create-a-new-persona).

## Best practices

* **Start with 3–5 core personas** representing your most common caller types, then add edge cases as you discover them.
* **Mirror reality**: base personas on real customer data and call recordings.
* **Test extremes**: a Frustrated, Fast, Rambling caller stresses your agent in ways a Neutral one won't.
* **Name for the test**: "Confused elder: password reset" tells your team more than "Robert".

## Next steps

<CardGroup cols={2}>
  <Card title="Customer flows" icon="git-branch" href="/documentation/simulation-testing/customer-flows">
    Pin personas to flow variants and define what should happen on the call
  </Card>

  <Card title="Running simulations" icon="play" href="/documentation/simulation-testing/running-simulations">
    Plan and launch runs that execute your flows as these callers
  </Card>
</CardGroup>