Create persona

Your Future AGI API key used to authenticate requests. You can find and manage your API keys in the Dashboard under Settings.

Your Future AGI secret key, used alongside the API key for request authentication. This is generated when you create an API key in the Dashboard.

A human-readable name for the persona. Must be unique within your workspace and must not conflict with any system-level persona names. The comparison is case-insensitive, so "Friendly Agent" and "friendly agent" are treated as duplicates. Maximum 255 characters.

A non-empty description that explains the persona’s role, behavior, and characteristics. This description helps team members understand the persona’s purpose and is displayed in the dashboard when browsing personas.

The type of simulation this persona is designed for. Accepted values: voice or text. Defaults to voice. This determines whether the persona will be used in voice-based call simulations or text-based simulations, and influences which attributes (such as accent and conversationSpeed) are relevant.

An array specifying the gender characteristics of the persona. Accepted values: male, female. You can include one or both values to create a persona that can operate with either gender in simulations.

An array of age range brackets that define the persona’s demographic. Accepted values: 18-25, 25-32, 32-40, 40-50, 50-60, 60+. Multiple values can be provided to represent a persona that spans multiple age groups.

An array of geographic locations associated with the persona. Accepted values: United States, Canada, United Kingdom, Australia, India. These influence the persona’s cultural context and regional speech patterns during simulation.

An array of professional roles that define the persona’s occupational background. Accepted values: Student, Teacher, Engineer, Doctor, Nurse, Business Owner, Manager, Sales Representative, Customer Service, Technician, Consultant, Accountant, Marketing Professional, Retired, Homemaker, Freelancer, Other. The profession influences the persona’s vocabulary, expectations, and communication patterns.

An array of personality traits that shape how the persona behaves during conversations. Accepted values: Friendly and cooperative, Professional and formal, Cautious and skeptical, Impatient and direct, Detail-oriented, Easy-going, Anxious, Confident, Analytical, Emotional, Reserved, Talkative. Multiple traits can be combined to create nuanced persona behaviors.

An array of communication style descriptors that control how the persona expresses itself. Accepted values: Direct and concise, Detailed and elaborate, Casual and friendly, Formal and polite, Technical, Simple and clear, Questioning, Assertive, Passive, Collaborative. These styles affect sentence structure, word choice, and conversational flow.

An array of accent options for voice simulations. Accepted values: American, Australian, Indian, Canadian, Neutral. This field is primarily relevant when simulationType is voice and controls the speech accent used during call simulations.

Enables multi-language support for the persona. When set to true, the language field becomes required and the persona can switch between the specified languages during simulation. Defaults to false.

An array of languages the persona can communicate in. Accepted values: English, Hindi. This field is required when multilingual is set to true. If multilingual is false or omitted, this field is ignored.

An array of conversation speed multipliers that control the pace of the persona’s speech. Accepted values: 0.5, 0.75, 1.0, 1.25, 1.5. A value of 1.0 represents normal speed, values below 1.0 are slower, and values above 1.0 are faster. Primarily relevant for voice simulations.

Controls whether background sounds are included during voice simulations with this persona. When enabled, ambient noise is added to create a more realistic simulation environment.

An array of integer values from 1 to 10 that control how sensitive the system is to detecting when the persona has finished speaking. Higher values make the system more responsive to pauses, while lower values require longer silence before the agent responds. Relevant for voice simulations.

An array of integer values from 1 to 10 that control how easily the persona can be interrupted during speech. Higher values make the persona easier to interrupt, simulating more natural conversational dynamics. Relevant for voice simulations.

An array of keywords or tags associated with the persona. These keywords are searchable and help categorize and discover personas when browsing or filtering in the dashboard.

A key-value object for attaching arbitrary metadata to the persona. Both keys and values must be non-empty strings. Use this to store custom attributes that are not covered by the standard fields, such as internal identifiers or domain-specific labels.

Free-form text providing extra behavioral instructions for the persona. Use this field to specify nuanced behaviors, edge cases, or specific conversational patterns that are not captured by the predefined attribute fields. These instructions are passed directly to the simulation engine.

The overall tone of the persona’s communication. Accepted values: formal, casual, neutral. Defaults to casual. This influences word choice, sentence structure, and the general register of the persona’s language.

The punctuation style used in the persona’s text output. Accepted values: clean (standard punctuation), minimal (reduced punctuation), expressive (heavy use of exclamation marks, ellipses, etc.), erratic (inconsistent punctuation). Defaults to clean. Primarily relevant for chat simulations.

Controls the degree of slang and informal language the persona uses. Accepted values: none, moderate, heavy, light. Defaults to light. Higher levels of slang create a more casual, colloquial persona.

Controls how often the persona introduces typographical errors into text output. Accepted values: none, rare, occasional, frequent. Defaults to rare. This creates more realistic user-like behavior in chat simulations.

Controls the degree of regional language variation in the persona’s output. Accepted values: none, moderate, heavy, light. Defaults to light. Higher values introduce more region-specific vocabulary, idioms, and phrasing.

Controls how frequently the persona uses emojis in text output. Accepted values: never, light, regular, heavy. Defaults to light. Primarily relevant for chat simulations where emoji usage affects the perceived personality.

Controls the length and detail level of the persona’s responses. Accepted values: brief (short, concise responses), balanced (moderate detail), detailed (longer, more elaborate responses). Defaults to balanced.

The request payload is invalid. This can occur when required fields (name, description) are missing or empty, when the persona name already exists in your workspace or conflicts with a system persona name (case-insensitive), when multilingual is set to true but no language array is provided, or when any field contains a value outside the allowed choices. Review the response body for specific field-level validation errors.

Authentication credentials were not provided or are invalid. Ensure that both X-Api-Key and X-Secret-Key headers are included in your request and contain valid, non-expired keys. Verify your API keys in the Dashboard under Settings.

An unexpected error occurred on the server while processing the request. This is not caused by your input. If this error persists, contact Future AGI support with the request details and timestamp for investigation.