Skip to content

docs(simulation): Personas concept #747

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
YashMohan23 wants to merge 1 commit into
base: docs/sim-replay
Choose a base branch
from
Open

docs(simulation): Personas concept #747

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 32 additions & 101 deletions src/pages/docs/simulation/concepts/personas.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,120 +1,51 @@
---
title: "Personas: Simulated Customer Profiles in Future AGI"
description: "Personas in Future AGI represent the customers or users your AI agent interacts with in simulation. Define them to create realistic test conversations."
title: "Personas"
description: "Give your test customer a personality, a voice, and a way of talking"
---

## About

A **persona** defines who the simulated customer is during a test — their demographics, personality, and communication style. The simulator uses these traits to play the "customer" side of the conversation, making interactions feel realistic rather than scripted. You can use one of **18 pre-built personas** or create your own. Personas are typed as **voice** or **chat**, each with settings specific to that channel.
## What a persona is

![Persona 1](/screenshot/product/simulation/personas/1.png)
A **persona** is the simulated user in a simulation: its demographics, personality, and communication style. The simulator plays the persona as the customer side of the conversation, so a run feels like a real interaction instead of a fixed script. You reach for one of the built-in personas or define your own. A "Price-sensitive caller", for example, is a voice persona with an Indian accent, fast speech, and a high tendency to interrupt, plus a custom `objection_pattern` your [scenario](/docs/simulation/concepts/scenarios) can read.

## Voice vs Chat
<Mermaid chart={`
%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
BI["Basic info<br/>name, age, location"] --> P["Persona"]
BH["Behaviour<br/>personality, style"] --> P
CH["Channel traits<br/>voice or chat"] --> P
P --> SA["Simulator agent<br/>plays the persona"]
style P fill:#2f2f2f,stroke:#ffffff,stroke-width:2px
`} />

When creating a custom persona, you select whether it is for **voice** or **chat** simulations.
- **Voice**: Used in phone or voice-channel tests. You can set speech-related options: **accent**, **conversation speed**, **background noise**, and **interrupt sensitivity** (how easily the persona can be interrupted or can interrupt). Behavioural and basic-information settings apply to both.
- **Chat**: Used in text-based tests. You can set text-related options: **tone**, **verbosity**, **punctuation style**, **emoji usage**, **slang**, **typos frequency**, and **regional mix**. Basic information and behavioural settings apply to both.
## What you can customize

The same persona is not shared across voice and chat; create separate personas if you need both for the same “type” of customer.
A persona is typed as **voice** or **chat**, and it's customizable across a wide surface, from who the customer is to exactly how they sound. Set as much or as little as you need, and every field falls back to a sensible default:

## Creating a custom persona
- **Basic info**: name, description, and demographics, meaning gender, age range, and location
- **Behaviour**: personality traits and communication style
- **Voice traits**, on a voice persona: accent, conversation speed, background noise, and turn-taking, split into interrupt sensitivity and finished-speaking sensitivity
- **Chat traits**, on a chat persona: tone, verbosity, punctuation style, emoji usage, slang, typo frequency, and regional mix
- **Custom properties**: any attribute your scenario reads per row, like `objection_pattern` or `insurance_type`
- **Instructions**: free-form guidance the simulator always follows, like "ask for a supervisor after the first objection"

From the Personas page, click **Create your own persona**. Choose **Voice** or **Chat** depending on whether the persona will be used in voice or chat simulations; the form then shows the relevant settings for that type. Follow the steps in the tab that matches your choice.
![Persona 2](/screenshot/product/simulation/personas/2.png)
That is a deep surface, so most fields have sensible defaults and you only set the ones that matter for the test. Every field and its allowed values lives in the Persona settings reference.

<Tabs sync={false}>
<Tab title="Voice type" icon="play">
Use this flow when creating a persona for **voice** (phone or voice-channel) simulations.
## Built-in and custom personas

<Steps>
<Step title="Basic information">
Enter the core details the simulator uses to identify this persona. Same fields as chat; all optional except name and description if required by the UI.
Future AGI ships 18 built-in personas you can drop into a run as-is. When none fit, you create a custom persona in your workspace, shape it across the layers above, and reuse it across every run.

![Create Custom Personas](/screenshot/product/simulation/personas/3.png)
## The simulator agent

| Property | Description |
| -------- | ----------- |
| Persona name | Name you give this persona (e.g. "Price-sensitive caller"). |
| Description | Short description, e.g. "An angry customer who is not happy with the service." |
| Gender (optional) | One or more: Male, Female. |
| Age (optional) | One or more ranges: 18–25, 25–32, 32–40, 40–50, 50–60, 60+. |
| Location (optional) | One or more: United States, Canada, United Kingdom, Australia, India. |
</Step>
<Step title="Behavioural settings">
Set **personality traits** and **communication style**. For voice, also set **accent** (e.g. American, Australian, Indian, Neutral). This controls how the persona responds and speaks during the call.
The persona describes who the user is; the **simulator agent** is the actor that plays it. It is the model that generates the persona's side of the conversation, along with the voice it speaks in and the pacing it keeps, like how fast it talks and how long a call can run. Choosing a capable simulator agent is what makes the persona hold its character across a long conversation.

![Create Custom Personas](/screenshot/product/simulation/personas/4.png)
</Step>
<Step title="Conversation settings (voice)">
Control how the voice conversation runs: **conversation speed** (e.g. very slow, slow, moderate, fast, very fast), how the simulator responds, and **background noise** (on/off) for realism. You can also set **interrupt sensitivity** and **finished-speaking sensitivity** so the persona behaves naturally with turn-taking and interruptions.

![Create Custom Personas](/screenshot/product/simulation/personas/5.png)
</Step>
<Step title="Custom properties">
Add any extra attributes not covered by the predefined fields (e.g. "insurance_type", "objection_pattern") so scenarios can reference them.

![Create Custom Personas](/screenshot/product/simulation/personas/6.png)
![Create Custom Personas](/screenshot/product/simulation/personas/7.png)
</Step>
<Step title="Additional information">
Add free-form instructions (e.g. "Always ask for a supervisor after the first objection.").

![Create Custom Personas](/screenshot/product/simulation/personas/8.png)
</Step>
<Step title="Add persona">
Click **Add** (or **Save**). The persona appears in your list and can be used in voice scenarios and run tests.
</Step>
</Steps>
</Tab>
<Tab title="Chat type" icon="eye">
Use this flow when creating a persona for **chat** simulations.

<Steps>
<Step title="Basic information">
Enter the core details the simulator uses to identify this persona. Same fields as voice; all optional except name and description if required by the UI.

![Create Custom Personas](/screenshot/product/simulation/personas/3.png)

| Property | Description |
| -------- | ----------- |
| Persona name | Name you give this persona (e.g. "Price-sensitive buyer"). |
| Description | Short description, e.g. "An angry customer who is not happy with the service." |
| Gender (optional) | One or more: Male, Female. |
| Age (optional) | One or more ranges: 18–25, 25–32, 32–40, 40–50, 50–60, 60+. |
| Location (optional) | One or more: United States, Canada, United Kingdom, Australia, India. |
</Step>
<Step title="Behavioural settings">
Set **personality traits** and **communication style**. These define how the persona types and responds in chat.

![Create Custom Personas](/screenshot/product/simulation/personas/10.png)
</Step>
<Step title="Conversation settings (chat)">
Control how the chat persona writes: **tone** (formal, casual, neutral), **verbosity** (brief, balanced, detailed), **punctuation style** (clean, minimal, expressive, erratic), **emoji usage** (never, light, regular, heavy), **slang usage**, **typos frequency**, and **regional mix**. These make the text feel realistic for the persona.

![Create Custom Personas](/screenshot/product/simulation/personas/9.png)
</Step>
<Step title="Custom properties">
Add any extra attributes not covered by the predefined fields (e.g. "insurance_type", "objection_pattern") so scenarios can reference them.

![Create Custom Personas](/screenshot/product/simulation/personas/6.png)
![Create Custom Personas](/screenshot/product/simulation/personas/7.png)
</Step>
<Step title="Additional information">
Add free-form instructions (e.g. "Always ask for a supervisor after the first objection.").

![Create Custom Personas](/screenshot/product/simulation/personas/8.png)
</Step>
<Step title="Add persona">
Click **Add** (or **Save**). The persona appears in your list and can be used in chat scenarios and run tests.
</Step>
</Steps>
</Tab>
</Tabs>

## Next Steps
## Keep exploring

<CardGroup cols={2}>
<Card title="Run Simulation" icon="play" href="/docs/simulation">
Tie your agent and scenario to a run test, attach evals, and run the simulation.
<Card title="Agent definitions & versions" icon="robot" href="/docs/simulation/concepts/agent-definitions">
The agent your persona talks to
</Card>
<Card title="Replay" icon="arrows-rotate" href="/docs/simulation/concepts/replay">
Turn a real call into a persona-driven test
</Card>
</CardGroup>