--- title: "Update an evaluator" method: PATCH path: "/test_framework/v2/scenarios/{id}/" tags: ["Scenarios"] --- # Update an evaluator `PATCH /test_framework/v2/scenarios/{id}/` ## Request - Base URL: `https://api.cekura.ai` - URL: `https://api.cekura.ai/test_framework/v2/scenarios/{id}/` - Auth: one of: - API key in header `X-CEKURA-API-KEY` - HTTP bearer - HTTP bearer Partially update an evaluator. Same field shape as create — see `scenarios_create` for details. **If you set or edit `expected_outcome_prompt`:** it is evaluated only when the project's Expected Outcome metric is attached to the scenario — check its `metrics` and attach that metric if missing. **Tip:** to add or modify a single condition inside a `conditional_actions` scenario, fetch the scenario with GET, parse its `instructions` (the same object as `conditional_actions`), edit it, and PATCH the full object back as `conditional_actions`. The server replaces all conditions atomically. ## Path parameters - `id` integer, required ## Request body - PatchedSchemaPostScenario - `agent` integer, nullable: ID of the agent. Either agent or project must be provided. - `project` integer, nullable: ID of the project. Either agent or project must be provided. - `assistant_id` string: Alternative to agent ID - the assistant ID to use for this scenario Example: `"asst_1234567890"` - `name` string: Name of the evaluator - `personality` integer: The personality of the evaluator - `scenario_type` 'instruction' | 'conditional_actions': Type of scenario to create: - `instruction`: Standard instruction-based scenario where the instructions field contains plain text - `conditional_actions`: Conditional action-based scenario where the instructions field contains a JSON structure Default: `instruction`. Must be sent as `conditional_actions` when the request includes the `conditional_actions` field. * `instruction` - Instruction * `conditional_actions` - Conditional Actions - `instructions` string: Scenario Instructions - the format depends on the scenario_type: **For scenario_type="instruction":** Provide plain text instructions that describe the scenario behavior. Example: `"You are a customer calling to inquire about your order status. Be polite and provide order number 12345 when asked."` **For scenario_type="conditional_actions":** Use the structured `conditional_actions` field instead. If you send via `instructions`, pass a JSON-formatted string with the following structure: ```json { "role": "A friendly customer calling about an appointment", "first_message": "Hi, I'd like to check on my upcoming appointment ", "conditions": [ {"when": "The agent asks for your name", "say": "My name is Sarah Johnson"}, {"when": "The agent asks for your date of birth", "say": "January first, nineteen ninety"}, { "when": "The agent confirms your identity and provides appointment details", "say": "Thank you, that's all I needed ", "then": [""] } ] } ``` **Note:** When sent via `instructions`, the value must be a JSON-formatted string (e.g. `JSON.stringify(...)` / `json.dumps(...)`). For new integrations, use the structured `conditional_actions` field below. Responses return `instructions` in this same shape. **Structure Details:** - **`role`** (string): Personality/role description for the scenario actor - **`first_message`** (string | object): What the scenario actor says first, always verbatim. Empty means wait for the agent to speak. Use `{"say": "...", "then": [...]}` to add follow-up steps after it. - **`conditions`** (array): Ordered list of conditions that define the conversation flow **Each condition object has:** - **`when`** (string): Natural-language description of the main agent's observable action, written from a third-person observer perspective (e.g. `"The agent asks for your date of birth"`, `"The agent confirms the cancellation"`). Matched semantically against the conversation context. - **`say`** (string): What the scenario actor says or does, spoken verbatim. Wrap the whole step in `...` to have the actor improvise from it instead. - **SSML pause tags:** `` (interruptible) or `` (not interruptible). `` lets the main agent jump in mid-pause; `` enforces dead air. - **Emotion markers:** `[laughter]`, `[sigh]`, etc. (can repeat like `[laughter] [laughter]`) - **Special actions:** `` to end the call - Action tags only work in verbatim steps, not inside ``. - **`then`** (array of strings, optional): Follow-up steps in order. Each fires on the actor's next turn after one main-agent reply, regardless of its content. `` is only allowed here. **Usage Tips:** - Write `when` as third-person descriptions of what the main agent does (e.g. `"The agent confirms the cancellation"`) - End with an `` step for clean call termination - Combine SSML tags and emotion markers naturally: `"Great [laughter] [laughter]"` - `conditional_actions` ConditionalActions: Structured conditional-actions object for `scenario_type="conditional_actions"`. Use either `conditional_actions` (structured) or `instructions` (plain text) on a scenario — not both. - `role` string, required: Caller role / persona for this scenario. Example: `"You are a frustrated patient calling about a billing error"`. - `first_message` union: What the caller says first, always verbatim; empty means wait for the agent. Pass `{"say": "...", "then": [...]}` to add follow-up steps. - string - object - `say` string - `then` string[] - `conditions` Condition[], required: Ordered list of conditions and their actions. - `when` string, required: Third-person description of the agent's observable action that triggers this condition, matched semantically against the conversation. - `say` string, required: Spoken verbatim by the caller. Wrap the whole step in `...` to let the caller improvise from it instead; action tags such as `` and `