---
title: "Create Test"
method: POST
path: "/v1/agent/tests"
tags: ["Agent Tests"]
---

# Create Test

`POST /v1/agent/tests`

## Request

- Base URL: `https://api.fish.audio`
- URL: `https://api.fish.audio/v1/agent/tests`
- Auth: HTTP bearer

Create a test: `next_reply` judges the agent's next reply against an
expectation, `tool` checks the tool the agent calls next, and `simulation`
lets a simulated user hold a whole conversation that is scored against
success conditions. Pass `agent_ids` to attach the test right away.

The body of `GET /v1/agent/tests/{test_id}` posts back as is, so tests can
be exported and imported. Tool references use your workspace's tool ids
(list them with `GET /v1/agent/agents/{agent_id}/test-tools`), so an export
imports cleanly within the same team and needs its tool ids remapped
elsewhere.

## Request body

- PublicAgentTestCreatePayload
  - `name` string, required
  - `test_type` 'next_reply' | 'tool' | 'simulation'
  - `conversation` AgentTestMessagePayload[]
    - `role` 'agent' | 'user', required
    - `text` string, required
  - `expectation` string
  - `success_examples` string[]
  - `failure_examples` string[]
  - `referenced_tool` AgentTestReferencedTool: Tool the runner should (or should not) observe on the next turn. A webhook or client tool is referenced by its library id, an integration tool by "<provider_key>:<tool_name>" (for example "google_calendar:create_event").
    - `id` string, required
    - `name` string, required
    - `type` 'webhook' | 'client' | 'integration'
    - `description` string
  - `tool_parameters` AgentTestToolParameter[]
    - `name` string, required
    - `value` union, required
      - string
      - integer
      - number
      - boolean
    - `type` 'string' | 'number' | 'boolean', nullable
  - `verify_absence` boolean
  - `simulation` AgentTestSimulationConfig
    - `scenario` string, required
    - `max_turns` integer
    - `success_conditions` AgentTestSuccessCondition[], required
      - `name` string, required
      - `description` string, required
    - `assertions` AgentTestSimulationAssertions: Deterministic checks run before the judge, no LLM involved.
      - `tool_calls` AgentTestToolCallAssertion[]
        - `tool` AgentTestReferencedTool, required: Tool the runner should (or should not) observe on the next turn. A webhook or client tool is referenced by its library id, an integration tool by "<provider_key>:<tool_name>" (for example "google_calendar:create_event").
          - `id` string, required
          - `name` string, required
          - `type` 'webhook' | 'client' | 'integration'
          - `description` string
        - `params` object
        - `min_calls` integer
        - `max_calls` integer, nullable
      - `forbidden_tools` AgentTestReferencedTool[]
        - `id` string, required
        - `name` string, required
        - `type` 'webhook' | 'client' | 'integration'
        - `description` string
      - `ended_by` 'agent' | 'user' | 'transfer' | 'any', nullable
    - `tool_mocks` AgentTestToolMocks: all: every tool answers from a mock, except real_tools, which run for real. selected: only the listed tools do, the rest follow fallback. none: every tool hits its real endpoint.
      - `strategy` 'all' | 'selected' | 'none'
      - `fallback` 'error' | 'real'
      - `tools` AgentTestToolMock[]
        - `tool` AgentTestReferencedTool, required: Tool the runner should (or should not) observe on the next turn. A webhook or client tool is referenced by its library id, an integration tool by "<provider_key>:<tool_name>" (for example "google_calendar:create_event").
          - `id` string, required
          - `name` string, required
          - `type` 'webhook' | 'client' | 'integration'
          - `description` string
        - `result` unknown
        - `status` integer, nullable
        - `when` object, nullable
        - `error` boolean
      - `real_tools` AgentTestReferencedTool[]
        - `id` string, required
        - `name` string, required
        - `type` 'webhook' | 'client' | 'integration'
        - `description` string
    - `simulated_user_model` string, nullable
    - `repeat_count` integer
    - `channel` 'web_voice' | 'phone_inbound' | 'phone_outbound', nullable
    - `context` AgentTestSimulationContext: The run's platform context switches, the agent config's `context` section for a test. Off so a date pinned in the prompt holds.
      - `current_time` boolean
  - `dynamic_variables` object
  - `agent_ids` string[]: Agents to attach the test to. They must all be in one workspace, and the test is created there. Without agents the test goes into the API key owner's default workspace.

## Response `201`

Document created, URL follows

- object
  - `test_id` string, required
  - `workspace_id` string, required
  - `name` string, required
  - `test_type` 'next_reply' | 'tool' | 'simulation', required
  - `agent_ids` string[]: Agents this test is attached to.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `conversation` PublicAgentTestMessage[]
    - `role` 'agent' | 'user', required
    - `text` string, required
  - `expectation` string
  - `success_examples` string[]
  - `failure_examples` string[]
  - `referenced_tool` AgentTestReferencedTool: Tool the runner should (or should not) observe on the next turn. A webhook or client tool is referenced by its library id, an integration tool by "<provider_key>:<tool_name>" (for example "google_calendar:create_event").
    - `id` string, required
    - `name` string, required
    - `type` 'webhook' | 'client' | 'integration'
    - `description` string
  - `tool_parameters` AgentTestToolParameter[]
    - `name` string, required
    - `value` union, required
      - string
      - integer
      - number
      - boolean
    - `type` 'string' | 'number' | 'boolean', nullable
  - `verify_absence` boolean
  - `simulation` AgentTestSimulationConfig
    - `scenario` string, required
    - `max_turns` integer
    - `success_conditions` AgentTestSuccessCondition[], required
      - `name` string, required
      - `description` string, required
    - `assertions` AgentTestSimulationAssertions: Deterministic checks run before the judge, no LLM involved.
      - `tool_calls` AgentTestToolCallAssertion[]
        - `tool` AgentTestReferencedTool, required: Tool the runner should (or should not) observe on the next turn. A webhook or client tool is referenced by its library id, an integration tool by "<provider_key>:<tool_name>" (for example "google_calendar:create_event").
          - `id` string, required
          - `name` string, required
          - `type` 'webhook' | 'client' | 'integration'
          - `description` string
        - `params` object
        - `min_calls` integer
        - `max_calls` integer, nullable
      - `forbidden_tools` AgentTestReferencedTool[]
        - `id` string, required
        - `name` string, required
        - `type` 'webhook' | 'client' | 'integration'
        - `description` string
      - `ended_by` 'agent' | 'user' | 'transfer' | 'any', nullable
    - `tool_mocks` AgentTestToolMocks: all: every tool answers from a mock, except real_tools, which run for real. selected: only the listed tools do, the rest follow fallback. none: every tool hits its real endpoint.
      - `strategy` 'all' | 'selected' | 'none'
      - `fallback` 'error' | 'real'
      - `tools` AgentTestToolMock[]
        - `tool` AgentTestReferencedTool, required: Tool the runner should (or should not) observe on the next turn. A webhook or client tool is referenced by its library id, an integration tool by "<provider_key>:<tool_name>" (for example "google_calendar:create_event").
          - `id` string, required
          - `name` string, required
          - `type` 'webhook' | 'client' | 'integration'
          - `description` string
        - `result` unknown
        - `status` integer, nullable
        - `when` object, nullable
        - `error` boolean
      - `real_tools` AgentTestReferencedTool[]
        - `id` string, required
        - `name` string, required
        - `type` 'webhook' | 'client' | 'integration'
        - `description` string
    - `simulated_user_model` string, nullable
    - `repeat_count` integer
    - `channel` 'web_voice' | 'phone_inbound' | 'phone_outbound', nullable
    - `context` AgentTestSimulationContext: The run's platform context switches, the agent config's `context` section for a test. Off so a date pinned in the prompt holds.
      - `current_time` boolean
  - `dynamic_variables` object

## Other responses

- `400`: Bad request syntax or unsupported method
- `401`: No permission -- see authorization schemes
- `422`
- `503`: The server cannot process the request due to a high load

## Changes

- **2026-11-03** `42ac421f7a12`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fish/apis/fishaudio-openapi/changes/v1/agent/tests/post.md)

---

[API](https://skmtc.dev/fish/apis/fishaudio-openapi.md) - [All operations](https://skmtc.dev/fish/apis/fishaudio-openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/fish/apis/fishaudio-openapi/revisions/42ac421f7a12?raw)