Personas

Overview

The Confident AI SDK exposes every Persona method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Personas

Lists the personas in your Confident AI project one page at a time, newest first. Each persona is returned with just its id and name — enough to pick one for a multi-turn golden; retrieve it by id to read the characteristics the simulator plays it with.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.personas.list(page=1, page_size=25)

For async mode, call a_list and await it as shown below:

result = await client.personas.a_list(...)

Parameters

Parameter	Type	Description
`page`	`Optional[int]`	The page to return. Defaults to 1.
`page_size`	`Optional[int]`	The number of results per page, at most 100. Defaults to 25.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.personas.list({ page: 1, pageSize: 25 });

Parameters

Parameter	Type	Description
`page`	`number`	The page to return. Defaults to 1.
`pageSize`	`number`	The number of results per page, at most 100. Defaults to 25.

Returns

This method returns an object of type PersonaList.

Create Persona

Creates a persona in your Confident AI project and returns its id. A persona is the character the simulated user plays in a multi-turn conversation, so defining one here is what lets many goldens share the same user instead of restating the same description on every row. Names are unique within a project; reusing one returns a 409.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.personas.create(
    name="Frustrated support caller",
    characteristics="An impatient customer who has already been transferred twice. Types in lowercase, asks short direct questions, and pushes back when given a generic answer.",
    metadata={"accountId": "acc_123", "plan": "pro"},
)

For async mode, call a_create and await it as shown below:

result = await client.personas.a_create(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the persona, unique within the project. It is the label the persona is picked by wherever a golden is given one, so make it recognisable on its own — 'Frustrated support caller' rather than 'Persona 2'.
`characteristics`	`str`	Required. How this persona behaves in a conversation: tone, temperament, patience, how much they volunteer, how they phrase things. The simulator reads it as the standing instruction for the user side of every turn, so describe a person rather than a task — what the conversation is about and when it is finished come from the golden's scenario and expected outcome, not from here.
`metadata`	`Optional[Dict[str, Any]]`	Structured facts the persona can draw on, such as an account, a resume or an order. The simulator reads it alongside the characteristics, and it is available to your AI connection payload as conversationalGolden.persona.metadata.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.personas.create(
  "Frustrated support caller",
  "An impatient customer who has already been transferred twice. Types in lowercase, asks short direct questions, and pushes back when given a generic answer.",
  { metadata: { accountId: "acc_123", plan: "pro" } },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the persona, unique within the project. It is the label the persona is picked by wherever a golden is given one, so make it recognisable on its own — 'Frustrated support caller' rather than 'Persona 2'.
`characteristics`	`string`	Required. How this persona behaves in a conversation: tone, temperament, patience, how much they volunteer, how they phrase things. The simulator reads it as the standing instruction for the user side of every turn, so describe a person rather than a task — what the conversation is about and when it is finished come from the golden's scenario and expected outcome, not from here.
`metadata`	`Record<string, unknown> \| null`	Structured facts the persona can draw on, such as an account, a resume or an order. The simulator reads it alongside the characteristics, and it is available to your AI connection payload as conversationalGolden.persona.metadata.

Returns

This method returns an object of type PersonaRef.

Get Persona

Retrieves a persona by id, including the characteristics the simulator plays it with. This is the text to read when a simulated conversation did not sound the way you expected: the persona supplies who is talking, while the golden it is attached to supplies what they want.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.personas.get(persona_id="<PERSONA-ID>")

For async mode, call a_get and await it as shown below:

result = await client.personas.a_get(...)

Parameters

Parameter	Type	Description
`persona_id`	`str`	Required. The id of the persona.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.personas.get("<PERSONA-ID>");

Parameters

Parameter	Type	Description
`personaId`	`string`	Required. The id of the persona.

Returns

This method returns an object of type Persona.

Update Persona

Renames a persona or rewrites its characteristics, and returns it. Every golden already pointing at this persona picks the new text up on its next simulation, so an edit changes how future conversations are played rather than conversations already simulated. Names are unique within a project; taking another persona's name returns a 409.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.personas.update(
    persona_id="<PERSONA-ID>",
    name="Frustrated support caller",
    characteristics="An impatient customer who has already been transferred twice. Types in lowercase, asks short direct questions, and pushes back when given a generic answer.",
    metadata={"accountId": "acc_123", "plan": "pro"},
)

For async mode, call a_update and await it as shown below:

result = await client.personas.a_update(...)

Parameters

Parameter	Type	Description
`persona_id`	`str`	Required. The id of the persona.
`name`	`Optional[str]`	The name of the persona, unique within the project. Omit it to keep the current name.
`characteristics`	`Optional[str]`	How this persona behaves in a conversation, as the simulator reads it on every user turn. The text replaces the stored one outright rather than being appended to, so send the whole description. Omit it to keep the current one.
`metadata`	`Optional[Dict[str, Any]]`	Structured facts the persona can draw on. The object replaces the stored one outright, so send the whole object. Send null to clear it, or omit it to keep the current one.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.personas.update(
  "<PERSONA-ID>",
  {
    name: "Frustrated support caller",
    characteristics: "An impatient customer who has already been transferred twice. Types in lowercase, asks short direct questions, and pushes back when given a generic answer.",
    metadata: { accountId: "acc_123", plan: "pro" }
  },
);

Parameters

Parameter	Type	Description
`personaId`	`string`	Required. The id of the persona.
`name`	`string`	The name of the persona, unique within the project. Omit it to keep the current name.
`characteristics`	`string`	How this persona behaves in a conversation, as the simulator reads it on every user turn. The text replaces the stored one outright rather than being appended to, so send the whole description. Omit it to keep the current one.
`metadata`	`Record<string, unknown> \| null`	Structured facts the persona can draw on. The object replaces the stored one outright, so send the whole object. Send null to clear it, or omit it to keep the current one.

Returns

This method returns an object of type Persona.

Delete Persona

Permanently deletes a persona. Goldens that used it are kept and simply lose their persona, so their next simulation runs with no character attached until you give them another one.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.personas.delete(persona_id="<PERSONA-ID>")

For async mode, call a_delete and await it as shown below:

result = await client.personas.a_delete(...)

Parameters

Parameter	Type	Description
`persona_id`	`str`	Required. The id of the persona.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.personas.delete("<PERSONA-ID>");

Parameters

Parameter	Type	Description
`personaId`	`string`	Required. The id of the persona.

Returns

This method returns an object of type PersonaRef.

Types

Persona

A reusable character for the simulated user in a multi-turn conversation. Confident AI simulates conversations against your LLM app from multi-turn goldens, and a golden that names a persona has its user side played in character: the persona supplies who is talking, while the golden supplies what they want and when the conversation is done. Defining the character once here is what keeps 'a frustrated customer who types in lowercase' from being retyped on every row, and lets you compare runs where only the user changed.

class Persona:
    id: str
    name: str
    characteristics: str
    metadata: Optional[Dict[str, Any]]
    created_at: str = Field(alias="createdAt")
    updated_at: str = Field(alias="updatedAt")

idstrRequired

The id of the persona, generated by Confident AI.

Example: "<PERSONA-ID>"

namestrRequired

The name of the persona, unique within the project.

Example: "Frustrated support caller"

characteristicsstrRequired

How this persona behaves in a conversation, as the simulator reads it on every user turn.

Example: "An impatient customer who has already been transferred twice. Types in lowercase, asks short direct questions, and pushes back when given a generic answer."

metadataOptional[Dict[str, Any]]Required

Structured facts the persona can draw on, available to the simulator and to your AI connection payload.

Example: {"accountId":"acc_123","plan":"pro"}

created_atstrRequired

The time the persona was created, as an ISO 8601 datetime.

Example: "2025-01-15T10:30:00+00:00"

updated_atstrRequired

The time the persona was last changed, as an ISO 8601 datetime.

Example: "2025-01-16T09:12:00+00:00"

interface Persona {
  id: string;
  name: string;
  characteristics: string;
  metadata: Record<string, unknown> | null;
  createdAt: string;
  updatedAt: string;
}

idstringRequired

The id of the persona, generated by Confident AI.

Example: "<PERSONA-ID>"

namestringRequired

The name of the persona, unique within the project.

Example: "Frustrated support caller"

characteristicsstringRequired

How this persona behaves in a conversation, as the simulator reads it on every user turn.

Example: "An impatient customer who has already been transferred twice. Types in lowercase, asks short direct questions, and pushes back when given a generic answer."

metadataRecord<string, unknown> | nullRequired

Structured facts the persona can draw on, available to the simulator and to your AI connection payload.

Example: {"accountId":"acc_123","plan":"pro"}

createdAtstringRequired

The time the persona was created, as an ISO 8601 datetime.

Example: "2025-01-15T10:30:00+00:00"

updatedAtstringRequired

The time the persona was last changed, as an ISO 8601 datetime.

Example: "2025-01-16T09:12:00+00:00"

PersonaList

One page of personas, with the total across all pages.

class PersonaList:
    personas: List[PersonaSummary]
    total_personas: int = Field(alias="totalPersonas")
    page: int
    page_size: int = Field(alias="pageSize")

personasList[PersonaSummary]Required

The personas for the current page, newest first.

See PersonaSummary.

total_personasintRequired

The total number of personas in this project.

Example: 4

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of personas per page.

Example: 25

interface PersonaList {
  personas: PersonaSummary[];
  totalPersonas: number;
  page: number;
  pageSize: number;
}

personasPersonaSummary[]Required

The personas for the current page, newest first.

See PersonaSummary.

totalPersonasnumberRequired

The total number of personas in this project.

Example: 4

pagenumberRequired

The page this response covers.

Example: 1

pageSizenumberRequired

The number of personas per page.

Example: 25

PersonaRef

A reference to a persona by its id.

class PersonaRef:
    id: str

idstrRequired

The id of the persona, generated by Confident AI.

Example: "<PERSONA-ID>"

interface PersonaRef {
  id: string;
}

idstringRequired

The id of the persona, generated by Confident AI.

Example: "<PERSONA-ID>"

PersonaSummary

A persona as it appears in a list: enough to recognise it and pick its id. Retrieve one by id to read the characteristics that drive the simulation.

class PersonaSummary:
    id: str
    name: str

idstrRequired

The id of the persona, generated by Confident AI.

Example: "<PERSONA-ID>"

namestrRequired

The name of the persona.

Example: "Frustrated support caller"

interface PersonaSummary {
  id: string;
  name: string;
}

idstringRequired

The id of the persona, generated by Confident AI.

Example: "<PERSONA-ID>"

namestringRequired

The name of the persona.

Example: "Frustrated support caller"

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI