# POST /voice-agents/:agent_id/tests

**Resource:** [Agents](./voice-agents.md)  
**MCP tool:** `create_voice_agent_test`  
**Scopes:** `voice-agents:write`  
**Write operation:** yes

Save a chat test for a voice agent: a pretend caller and the checks the conversation must pass. Tools that save or send are replaced with stand-ins during tests unless use_real_tools is true.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `agent_id` | path | string | yes |  |
| `name` | body | string | yes | Short label, e.g. "Unhappy customer is not asked for a review". |
| `caller_prompt` | body | string | yes | Who the pretend caller is, what they want and how they behave, written to them in the second person. E.g. "You are Jordan, a customer whose leaking tap was fixed last week. It went well and you are happy to leave a review. Give your email as demo+review@mail.trustpager.net if asked." |
| `success_criteria` | body | array | yes | Plain-English checks the conversation must meet to pass, e.g. ["The agent asks how the job went", "The agent offers to email a review link"]. 1 to 10. |
| `dynamic_variables` | body | object | no | Values the agent sees for its {{variables}} during the test, e.g. {"first_name": "Jordan"}. Merged over the defaults set on the agent. |
| `use_real_tools` | body | boolean | no | Default false: every tool that saves or sends is replaced with a "done, nothing saved" stand-in so the test touches nothing real. True lets the tools run for real (bookings, emails, CRM writes happen). |
| `tool_mocks` | body | array | no | Optional: what a named tool should answer during the test (JSON text), e.g. to test what the agent does when no times are free. |
| `sort_order` | body | number | no | Position in the list, lowest first. |
| `require_approval` | body | boolean | no | Optional. Set true to route this write into the approval queue for human review instead of executing it immediately (returns 202 + an approval_id). Works even when your key/token has permission to execute directly. |

## Request example

```bash
curl -X POST   "https://api.trustpager.com/functions/v1/api/v1/voice-agents/:agent_id/tests"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"name":"...","caller_prompt":"...","success_criteria":"..."}'
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`