---
title: "Clarify what evaluator scenarios should cover"
method: POST
path: "/test_framework/v2/scenarios/scenario-agent/"
tags: ["test_framework"]
---

# Clarify what evaluator scenarios should cover

`POST /test_framework/v2/scenarios/scenario-agent/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/test_framework/v2/scenarios/scenario-agent/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer

Clarify what a set of evaluator scenarios should cover before generating them.

Send the agent and a natural-language brief; the AI comes back with the questions it needs answered (or confirms it has enough) so `scenarios_generate_bg` produces scenarios that match what you actually meant.

**Response:** Returns `progress_id` for polling status at /scenario-agent-progress/

**Improving existing evaluators is not done here.** Read the evaluator with `scenarios_retrieve` (or the list endpoint), decide the edit yourself, and write it back with `scenarios_partial_update` or `scenarios_bulk_update`. This tool changes evaluator scenarios only; it never changes an AI agent's prompt, configuration, tools, or provider settings — for `improve agent <id>`, use the `cekura:cekura-self-improving-agent` skill.

## Request body

- ScenarioAgentRequest: Clarify what a batch of evaluator scenarios should cover before generating them. Improving *existing* evaluators is not done here — the Cekura agent reads the evaluators attached to its turn and writes changes back with the ordinary scenario write endpoints. See `test_framework.scenario_chat_context`.
  - `user_message` string: What the generated evaluators should cover (e.g., 'cover refund disputes and angry callers'). Do not use for agent prompt/config improvements.
  - `agent_id` integer, nullable: Agent the generated evaluators are for. Required on the first turn; on a follow-up it may be omitted and is read off `session_id`.
  - `project_id` integer, nullable: Project ID - optional, automatically inferred from evaluators if not provided
  - `session_id` integer, nullable: Session ID for tracking - automatically created if not provided
  - `num_scenarios` integer: Number of scenarios the clarification should be sized for
  - `knowledge_base` integer[]: Knowledge Base file IDs for additional context
  - `tool_ids` string[]: Tools that will be enabled on the generated evaluators (validated up front)
  - `inbound_phone_numbers` integer[]: Inbound numbers that will be attached to the generated evaluators (validated up front)

## Response `200`

- ScenarioAgentStartResponse
  - `progress_id` string, required: Use this to poll for results at /scenario-agent-progress/?progress_id={id}
  - `session_id` integer, required: Session tracking ID

## Other responses

- `400`

## Changes

- **2026-11-03** `a6fb6a739212`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/test_framework/v2/scenarios/scenario-agent/post.md)

---

[API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)