Best practices for writing AI roleplays

Introduction

The quality of an AI roleplay depends on what you write in each field. Clear, focused fields produce a realistic avatar and a conversation that matches your training goal. Vague or overloaded fields produce generic or inconsistent conversations.

This article gives field-by-field guidance with Good and Poor examples, and advice on avatar behavior, company-specific realism and testing. For the steps to create a roleplay, see Creating and managing AI roleplays. For rubric guidance, see Configuring evaluation, rubrics and reviewers in AI roleplay.

Requirements and limitations

The AI does not set the interaction mode, time limit, or number of attempts from your prompt. Set them in the Settings tab.
The AI uses only the text you enter in the roleplay fields as context. It does not use documents.
AI roleplay is designed to measure conversational skills and give feedback. It is not designed to produce final scripts.

Writing the prompt

When you create a roleplay from a custom prompt, the AI fills most fields for you.

Be specific and structured. Include the situation, the roles of the learner and the avatar, and the goal. Good example: "The learner plays an IT support analyst helping a UX designer who forgot their password. The goal is clear guidance, reassurance and a professional, patient tone throughout the reset."
Keep it short. Include the essential elements only. The AI fills in the rest, and you can edit it afterward.
State the goal of the conversation. Say what the learner should achieve by the end.

Scenario tab

Scenario description

Describe the situation and how the conversation begins in one or two sentences.

Good example: An HR manager schedules a meeting with an employee to provide feedback on recent performance.

Poor example: A corporate board meeting. (Too vague: no roles and no flow.)
Poor example: A project manager at a large company that has recently gone through reorganizations and budget cuts meets with a senior engineer about missed deadlines. The project manager is juggling stakeholder expectations and the engineer feels frustrated about shifting priorities. (Too long: the background buries the goal.)

Goal to achieve

Describe what the learner must accomplish, not what the avatar does.

Good example: The HR manager delivers constructive feedback, addresses concerns and agrees on clear next steps.

Poor example: The employee listens carefully and accepts the manager's suggestions. (Focuses on the avatar, not on the learner.)

Learner role

Describe the role the learner plays. Keep it short and role-focused, without a background story.

Good example: HR manager giving feedback to an employee.

Poor example: Manager in a company. (Too generic.)

Use the same role name for the learner and the avatar in every field. If the learner is "employee" in one field, do not call them "UX designer" in another.

AI persona tab

Persona name

Give the persona a realistic name, for example Daniel.

Persona role

Specify the persona's professional role or position.

Good example: Employee.

Poor example: Employee receiving feedback from their manager. (Too descriptive: the situation belongs in the roleplay description.)

Personality

Choose a predefined option (Agreeable, Vague or Skeptical) or define a custom personality by combining 2 to 3 traits.

Good example: Open to feedback, but defensive when criticized too directly.

Poor example: Very kind, collaborative, skeptical, stressed, vague, friendly, approachable, nervous. (Too many traits: the avatar becomes inconsistent.)

Choose the personality that matches the skill you want to practice: Skeptical for handling objections, Agreeable for collaboration and Vague for asking clarifying questions.

Profile

Describe the persona's background and motivation in this roleplay.

Good example: The employee is worried about their performance and hopes to understand how to improve.

Poor example: The employee works at a multinational company with 200,000 staff and complex reporting lines. (Irrelevant detail that does not shape the conversation.)

Additional context

This field is optional. Use it for background that is not covered in the other fields and that changes how the avatar responds. Keep it relevant and avoid repeating other fields.

Good example: The company has recently gone through a reorganization, creating uncertainty in the workplace.

Poor example: The office recently moved to a new building. (Not relevant: it does not affect the conversation.)

The sections on making the avatar less agreeable, making the roleplay fit your company and regulated or specialized language explain what to put in this field for more realistic roleplays.

Making the avatar less agreeable

If the avatar accepts everything the learner says, the practice is too easy and the feedback is less useful. To make the avatar more realistic:

Combine 2 to 3 traits in a custom personality. A mix of opposing traits creates natural resistance, for example "Open to feedback, but defensive when criticized too directly."
State what the avatar will not concede in Additional context. The avatar needs to know where the learner can be wrong. Good example: "The employee believes the missed deadline was caused by changing priorities. They do not accept blame unless the manager gives a specific example and acknowledges the priority changes."
Give the avatar a motivation in the Profile field. An avatar with something to protect or gain pushes back more consistently than one with a generic personality.
Avoid long trait lists. More than three traits make the avatar inconsistent instead of tougher.

Poor example: "The employee is difficult." (No trait, no reason and no limit for the AI to work with.)

Making the roleplay fit your company

The avatar does not know your company, products, customers or methodology unless you tell it. To make the roleplay realistic for your organization, put the essentials in Additional context:

The persona of the person the learner is talking to, such as their title, priorities and typical objections.
Your terminology, such as product names, plan names and internal terms.
The key points of your playbook or methodology that shape the conversation, such as the steps a customer expects or the constraints they work under.

Good example: "The customer is a procurement director at a mid-size manufacturer. They have used our Standard plan for two years and are evaluating the Premium plan. Their main concerns are integration with their ERP and total cost over three years. They compare us to a competitor's lower price."

Poor example: "Our company sells software to many customers in different industries and has a long history of success." (General description with no effect on the conversation.)

Keep the context short and relevant. The field has a character limit. If your playbook is long, select the points that change how this customer behaves in this situation. Documents cannot be uploaded at release.

Please note: The roleplay context shapes the avatar's behavior. It does not change how the learner is evaluated. To evaluate against your own standards, configure a rubric. Learn more in Configuring evaluation, rubrics and reviewers in AI roleplay.

Regulated or specialized language

If your roleplay involves regulated, legal, medical or other specialized language, include the domain facts in Additional context. The AI cannot know what is correct or off-track in your domain unless you tell it.

State the facts or rules that apply, such as required disclosures, prohibited statements or the correct procedure.
State what the avatar should do if the learner gets it wrong, for example: "If the learner makes a promise about outcomes, the customer asks for it in writing."
Use the exact terms your learners must use.

Good example: "The customer is a family member asking about a care plan. Staff must not discuss other residents and must not promise outcomes. The family member becomes concerned if the learner uses informal terms for the person in care."

Poor example: "Follow all relevant regulations." (Does not say which regulations or what happens when the learner does not follow them.)

To assess regulated language in the evaluation, add it as a rubric criterion. Learn more in Configuring evaluation, rubrics and reviewers in AI roleplay.

Settings tab

Interaction mode

Match the mode to the goal of the roleplay.

Video: an animated avatar speaks and moves on screen. Use it when the learner should practice with a realistic, face-to-face conversation.
Voice: the learner talks with the avatar while a static avatar image is displayed. Use it for phone-style conversations or when the learner does not need to see the avatar's expressions.
Chat: the learner exchanges written messages. Use it for written channels such as support chat, or when the learner works in a setting where speaking is not practical.

Good example: A customer service roleplay about a phone complaint uses Voice mode.

Poor example: A written email-reply skill practiced in Video mode. (The mode does not match the channel you want to train.)

Time limit and number of attempts

Time limit is from 5 to 20 minutes. Choose a time that fits the conversation. Most single-situation roleplays fit in 5 to 10 minutes.
Number of attempts is how many times a learner can try. Use one attempt for assessments and several for practice.

Keeping roleplays simple

One situation per roleplay. A roleplay with several situations, goals or decisions is hard to evaluate and to practice. If you need to cover a sequence, create one roleplay for each step.
Limit each field to 2 to 3 key points. Long background stories dilute the conversation.
Include relevant context only. Leave out details that do not change what the avatar says.
Avoid contradictions. The same facts, names and roles must be consistent across fields.
Use each field for its purpose. Do not put all details in Roleplay description or Additional context.

Testing and improving a roleplay

First, click Start preview and play the roleplay as a learner would. Next, try a strong response, a weak response and an off-topic response, and check that the avatar reacts differently to each. Then check that the avatar stays in character and does not concede too fast. After that, edit the fields that caused problems and preview again. Finally, review the report to check that it reflects what happened in the conversation.

Make one change at a time, so you can see which edit changed the behavior.

Before you publish

The roleplay description names the situation and how the conversation starts, in one or two sentences.
The goal describes what the learner must do.
The learner role and avatar role use the same names in every field.
The avatar personality has 2 to 3 traits, or a predefined option that matches the skill you want to practice.
Additional context contains only details that change the conversation, including what the avatar will not concede and any company or domain facts.
The interaction mode, time limit and number of attempts match the goal. Do not rely on defaults.
The rubric matches your training goal.
The Learner view page is accurate and matches the rubric criteria.
You have previewed the roleplay at least once after your last edit.
The roleplay title is meaningful.