> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lehar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a test suite

> Auto-generates a suite of persona scenarios for an agent by asking the Test Runner's scenario generator (grounded in the agent's prompt and the judge criteria), then persists it as a normal, editable suite. Backs the dashboard Test Runner's "Generate scenarios" action and consumes credits (metered against the generator model). Scope `sessions:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /agent-test-suites/generate
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /agent-test-suites/generate:
    post:
      tags:
        - Agent Testing
      summary: Generate a test suite
      description: >-
        Auto-generates a suite of persona scenarios for an agent by asking the
        Test Runner's scenario generator (grounded in the agent's prompt and the
        judge criteria), then persists it as a normal, editable suite. Backs the
        dashboard Test Runner's "Generate scenarios" action and consumes credits
        (metered against the generator model). Scope `sessions:write`.
      operationId: generate_suite_route_ca_api_v0_agent_test_suites_generate_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
              properties:
                agent_id:
                  type: string
                  description: >-
                    Agent to generate scenarios for. Must exist in the
                    workspace.
                judges:
                  type: array
                  items:
                    type: string
                  description: >-
                    Judge criteria to ground generation and store on the suite.
                    Defaults to `["task_completion", "tool_use", "safety",
                    "accuracy", "relevancy"]`.
                count:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 8
                  description: How many scenarios to generate (clamped to 1-100).
                hint:
                  type: string
                  description: >-
                    Optional free-text steer for the generator (e.g. focus
                    areas).
                name:
                  type: string
                  description: >-
                    Optional suite name; defaults to "<agent name> — generated"
                    (auto-suffixed to avoid a name collision).
            example:
              agent_id: agent_sales_hi
              count: 8
              judges:
                - task_completion
                - safety
              hint: Focus on price objections and callback scheduling.
      responses:
        '201':
          description: Created (generated) test suite
          content:
            application/json:
              example:
                id: test_suite_01hzya5f7g8h9j0k1m2n3p4q5r
                agent_id: agent_sales_hi
                name: Sales Agent — generated
                scenarios:
                  - label: Price objection
                    instructions: >-
                      You think the renewal is overpriced and ask for a discount
                      before committing.
                    runs: 1
                    max_turns: 8
                  - label: Busy prospect
                    instructions: >-
                      You are short on time and want the agent to get to the
                      point quickly.
                    runs: 1
                    max_turns: 8
                config:
                  judges:
                    - task_completion
                    - safety
                  variables:
                    callee_name: ''
                    company: ''
                created_by_user_id: user_01EXAMPLE
                created_at: '2026-05-22T10:02:00Z'
                updated_at: '2026-05-22T10:02:00Z'
        '400':
          description: >-
            `agent_id` missing, body not a JSON object, or the agent is not in
            the workspace.
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: agent_id is required
        '401':
          description: Missing or invalid credentials (code `unauthorized`).
        '402':
          description: Workspace is out of credits.
          content:
            application/json:
              example:
                error:
                  code: insufficient_credits
                  message: >-
                    Workspace is out of credits. Add credits before generating a
                    suite.
        '403':
          description: >-
            The credential is missing the required `sessions:write` scope (code
            `forbidden`).
        '429':
          description: >-
            The scenario generator is rate-limited. Retry after the
            `Retry-After` window.
          headers:
            Retry-After:
              description: Seconds to wait before retrying (60).
              schema:
                type: integer
          content:
            application/json:
              example:
                error:
                  code: too_many_requests
                  message: Scenario generation is rate-limited. Try again shortly.
        '500':
          description: >-
            Unexpected server error, including a generic generation failure
            (code `internal_error`, e.g. "Scenario generation failed — check
            that the Test Runner is running.").
        '502':
          description: The Test Runner returned an unusable or failed generation result.
          content:
            application/json:
              example:
                error:
                  code: bad_gateway
                  message: >-
                    The generator returned no usable scenarios. Try again in a
                    moment.
        '503':
          description: The Test Runner is unreachable (the test-serve process is down).
          content:
            application/json:
              example:
                error:
                  code: service_unavailable
                  message: >-
                    The Test Runner is unreachable — is the test-serve process
                    running?
        '504':
          description: The Test Runner timed out while generating scenarios.
          content:
            application/json:
              example:
                error:
                  code: gateway_timeout
                  message: Scenario generation timed out. Try again.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````