Create and provision a role-play

The current product does not have an authoring or catalog administration interface. A new Role Play is published by coordinating the design team, the SCAI team, Blob Storage, Azure Table Storage, Integration Credentials, and the SCL runtime.

Treat the SCAI agent, the ScaiAgents row, the RolePlays row, and every referenced content file as one release. A row in RolePlays alone is not enough for a usable exercise.

Operating model and responsibilities

The design team supplies the functional package. The Role Play/backend operator reviews it, requests the specialized agent from the SCAI team, and performs the manual SCL provisioning. Do not ask the design team to provide Azure row values, infrastructure URLs, or credentials.

1. Receive the design handoff

Use a stable, non-customer-sensitive naming convention such as <client>-<use-case>. The handoff normally contains:

The simulated-customer specification may be supplied as a document rather than an application-ready file. It must make these boundaries explicit:

• The AI agent acts only as the customer or counterpart.
• The human user acts as the employee being trained and evaluated.
• The AI must not become the salesperson, coach, assistant, or evaluator.
• The opening message, emotional state, information-disclosure rules, objections, close conditions, and guardrails are stated.
• Optional actions explain their trigger and expected response without contradicting the main prompt.
• Persona data contains only information needed for the simulation and no real personal data.

Content contracts

roleplayinfo is a locale-keyed JSON object. Use the backend field names and casing shown below:

{
  "en-US": {
    "Scenario": "<learner-facing situation>",
    "Objectives": ["<observable objective>"],
    "Challenges": ["<realistic difficulty>"],
    "KeyTips": ["<practical learner guidance>"],
    "Skills": ["<skill evaluated>"],
    "CharacterProfile": {
      "FullName": "<fictional character>",
      "JobTitle": "<role>",
      "Company": "<fictional or approved organization>",
      "AvatarUrl": "<approved-avatar-url>",
      "Language": "en-US"
    },
    "Interaction": {
      "CallType": "<interaction type>",
      "ContactStyle": "<contact style>"
    },
    "Competency": "intermediate"
  }
}

For every locale, CharacterProfile.Language must match the containing locale key. Translate all learner-facing fields, preserve the same scenario and difficulty across languages, and use only basic, intermediate, or advanced for Competency.

helpinfo is a locale-keyed JSON object with a section title and an ordered items list containing title and description.

evaluationcriteria is Markdown consumed by the backend and is never returned to the browser. It must include:

• An evaluation context stating that API speaker Customer is the human learner and API speaker Agent is the AI simulated customer.
• A 1–5 rubric for every phase or indicator, with evidence taken only from Customer messages.
• Weights whose total is exactly 100%.
• A deterministic, non-overlapping elapsed-time rule when duration is scored.
• Instructions for strengths, improvements, and an actionable plan grounded in transcript evidence.

SessionInfo is JSON stored as a string in the table entity:

{
  "durationInMinutes": 10,
  "mode": "strict",
  "warningBeforeEndSeconds": 60,
  "overtimeLimitSeconds": 0
}

Reconcile the timing target in the evaluation criteria with SessionInfo. A different target is allowed only when it is intentional, documented, and tested.

2. Review the package before provisioning

Do not start SCAI or Azure setup until the package passes this review:

• The briefing, simulated-customer specification, and evaluation criteria describe the same conversation, learner role, and AI role.
• Every published locale is complete; JSON is valid and its CharacterProfile.Language value matches the locale key.
• The opening message, objections, information boundaries, closing behaviour, and guardrails are testable.
• Every high-weight evaluation phase has a realistic opportunity to occur.
• Evaluation weights total 100%, speaker mapping is explicit, and duration bands have no gaps or overlaps.
• The evaluation duration and SessionInfo values are consistent.
• Names, avatar assets, examples, and persona data are fictitious or approved for use.
• No credentials, tokens, production URLs, personal data, or customer-confidential values are present.

3. Request the Role Play agent from the SCAI team

Do not create a standard agent and repurpose it without SCAI review. Agents created with the default SCAI setup are customer-service agents: they are designed to assist a customer, whereas an SCL Role Play agent must impersonate the customer or counterpart.

Send the SCAI team the approved simulated-customer specification and state explicitly that the request is for an SCL Role Play agent. Ask the team to:

1. Create the initial agent in the approved staging organization and environment.
2. Disable the platform’s default customer-service macro-prompt so it does not override the simulated-customer role.
3. Apply the character prompt, opening behaviour, objections, closing rules, guardrails, persona, and optional start action.
4. Enable the browser voice channel and assign a DNIS.
5. Configure the approved ElevenLabs voice and the required language settings.
6. Activate the SCAI agent for staging acceptance.
7. Return the stable agent ID, organization ID, environment ID, environment name, SCAI API base URL, AI Factory API base URL, DNIS, and configured locales.

The request must not contain ElevenLabs credentials, SCAI application secrets, or any other secret. Those values remain under the SCAI and integration teams’ approved controls.

4. Accept the SCAI configuration

Validate the returned agent independently before creating catalog records:

1. Confirm the agent opens as the fictional customer and never offers to assist the human as a customer-service representative.
2. Exercise the main goals, objections, vague-information path, close conditions, and guardrails.
3. Confirm the default customer-service macro-prompt is disabled for this agent.
4. Confirm the voice channel, DNIS, ElevenLabs voice, and each supported language work.
5. Record the returned identifiers and endpoints exactly as supplied by the SCAI team.

The Environment value is important: the backend uses it when obtaining technical credentials. It must match the environment configured in Integration Credentials.

See SCAI voice experience for the runtime requirements and responsibility split.

5. Prepare the SCL catalog values

Collect and approve:

• A stable RolePlayId, Role Play name, description, supported locales, and intended learner population.
• The SCAI values returned in the previous step.
• Session duration, timing mode, warning threshold, and flexible overtime limit.
• Exact blob names for role-play information, evaluation criteria, and optional help.
• Optional target platform identifier and analytics tenant identifier.
• A test launch URL and an approved staging learner identity.

Choose unique blob names and record their exact spelling and extension. Do not invent a target platform or analytics tenant merely to make a row look complete.

6. Upload the content blobs

In the Role Play storage account, upload the reviewed artifacts to the private containers:

Use the exact blob names that will be written to RolePlays. Validate JSON before upload and verify the uploaded content can be read by the backend identity. Do not use a public container. If help is intentionally omitted, leave HelpInfoBlobName unset and record that decision in the release record.

7. Create the ScaiAgents entity

In Azure Storage Explorer or the approved Azure Portal storage browser, open the ScaiAgents table and insert one entity with:

{
  "PartitionKey": "SCAI_AGENT",
  "RowKey": "<scai-agent-id>",
  "Name": "<agent-name>",
  "Description": "<agent-description>",
  "OrganizationId": "<organization-guid>",
  "EnvironmentId": "<environment-guid>",
  "Environment": "<integration-credentials-environment>",
  "ScaiApiBaseUrl": "<scai-websocket-gateway>",
  "AiFactoryApiBaseUrl": "<ai-factory-base-url>",
  "DNIS": "<dnis>",
  "IsActive": false
}

Verify that RowKey exactly matches the SCAI identifier used by the Role Play. Keep the catalog entity inactive while the complete catalog record and content package are being checked. This IsActive value is the SCL catalog flag; it is separate from the agent’s active state in SCAI.

8. Create the RolePlays entity

Insert one entity in the RolePlays table:

{
  "PartitionKey": "ROLE_PLAY",
  "RowKey": "<role-play-id>",
  "Name": "<role-play-name>",
  "Description": "<role-play-description>",
  "ScaiAgentId": "<scai-agent-id>",
  "TargetPlatformId": "<optional-target-platform>",
  "AnalyticsTenantId": "<optional-analytics-tenant>",
  "EvaluationCriteriaBlobName": "<criteria-blob-name>.md",
  "HelpInfoBlobName": "<help-blob-name>.json",
  "RolePlayInfoBlobName": "<role-play-info-blob-name>.json",
  "IsActive": false,
  "SessionInfo": "{\"durationInMinutes\":10,\"mode\":\"strict\",\"warningBeforeEndSeconds\":60,\"overtimeLimitSeconds\":0}"
}

Optional values should be omitted or left empty according to the storage tooling convention when the integration is not enabled. When help is intentionally omitted, do not include the placeholder HelpInfoBlobName property shown in the example.

9. Validate before activation

Run the checks in this order:

1. Confirm every referenced blob exists, is private, and contains valid content.
2. Confirm ScaiAgents.RowKey equals RolePlays.ScaiAgentId.
3. Confirm both records use the expected partition keys.
4. Confirm the SCAI agent is active and the two SCL catalog records remain inactive while configuration is reviewed.
5. Temporarily activate the SCL records for an approved staging test window.
6. Call the current Evaluation API role-play lookup and verify that it returns the expected localized briefing/help, session settings, and SCAI metadata.
7. Launch SCL with rolePlayId=<role-play-id>.
8. Confirm the briefing renders in every supported locale.
9. Start a voice session and verify that the AI acts as the customer, then verify the DNIS, ElevenLabs voice, audio, transcript, timer, reconnection, and end-of-session behaviour.
10. Submit an evaluation and verify the score, indicators, qualitative analysis, action plan, and any optional recommendations.
11. If configured, verify completion delivery and analytics session/events independently; feedback success does not guarantee downstream delivery.

After the smoke test passes, leave ScaiAgents.IsActive and RolePlays.IsActive set to true. Re-read the role-play lookup and perform one final learner launch. If the test fails, set RolePlays.IsActive back to false immediately and correct the coherent agent/content/catalog release before trying again.

10. Rollback

If a published Role Play is unsafe, incorrect, or unavailable:

1. Set RolePlays.IsActive to false so the exercise is no longer returned to learners.
2. Deactivate the SCAI agent when the voice behaviour itself is unsafe or invalid.
3. Restore the previous coherent set of blob references and content files when reverting a content release.
4. Record the Role Play ID, previous and new blob names, approver, timestamp, and rollback owner.
5. Re-run the role-play lookup and learner smoke tests before reactivation.

The current product has no built-in version history, approval workflow, or automatic rollback. The release record is therefore part of the operating process.