> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/ai-agent-testing/voice-ai-testing/quickstart.md).

# Run Your First Voice AI Test

Connect a Phone voice agent, prepare caller scenarios, enable audio metrics, and inspect a first voice evaluation in ContextQA.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

To test a phone-based voice agent in ContextQA, create a Phone (voice) agent with the target number, prepare a voice project and caller cases, enable the required audio criteria, and start an Evaluation run. Inspect the recording, conversation, metric reasoning, and any backend verification before deciding whether the agent passed.

## Key takeaways

* Use a target phone number and environment approved for test calls.
* Limit parallel calls to the capacity of the target agent.
* Configure audio criteria explicitly and keep business-outcome checks separate.

## 1. Create the phone connection

Open **Agents → New Agent → Phone (voice)**. Enter a name, description if useful, and the target number in E.164 format. The checked form requires a leading `+` with 7–15 digits and blocks emergency or premium destinations.

Set **Parallel calls** when the target has limited capacity. Cases wait for an available slot instead of attempting more simultaneous calls than the configured cap. This protects the validity of the test: rejected calls caused by an overloaded target should not be confused with failed conversation logic.

Choose **Voice (conversation)** for spoken interaction or **DTMF menu** when the test requires that mode. Review the advanced settings available for the selected route.

![Phone voice agent setup with E.164 number, optional parallel-call cap, and interaction mode](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-59882161fc9895b2e4441ac2b274f8ccad5f9251%2Fphone-voice-setup.jpg?alt=media)

Review the destination before **Create & Test**. The form indicates that a phone connection is active immediately; a connected status alone does not establish a successful conversation.

## 2. Prepare the project and caller

Create a project for voice testing, or the mixed modality required by your workflow. Use **QuickStart** to provide requirements, review personas and use cases, and generate cases. Follow the [shared first-evaluation guide](https://learning.contextqa.com/ai-agent-testing/agent-evaluation/quickstart.md) for the sequence.

For an initial scheduling test, define the service, date, local time, timezone, final name, confirmation requirement, and expected backend record. Start with one unambiguous caller before adding interruptions, combined answers, and corrections.

## 3. Select voice and task criteria

Open **Metrics**. Review both the standard voice criteria and the additional available audio criteria. Enable the measures your acceptance policy needs; availability does not mean they are already active. Use [the metric reference](https://learning.contextqa.com/ai-agent-testing/voice-ai-testing/metrics-reference.md) to distinguish measured timing from LLM judgment.

Add a task-specific rubric for the final booking details. If completion requires a stored booking, configure a [read-only verifier](https://learning.contextqa.com/ai-agent-testing/agent-evaluation/verify-tool-actions.md). A successful spoken confirmation alone is insufficient.

## 4. Configure and start the run

Open **Runs → New Run → Evaluation**, choose the voice agent, select cases, and review the text and audio judge configuration. Use the project preset or an explicit override. Set thresholds based on reviewed examples and your policy; the values visible in screenshots are not universal recommendations.

Check the run estimate and target capacity, then start the evaluation. Do not increase concurrency to compensate for a failing single-call integration.

## 5. Inspect and reproduce

Review each case’s audio, conversation, metric result, judge explanation, and tool evidence where available. Check that the agent answered the intended target number and that no shared test fixture caused an accidental conflict.

Expected outcome: a first reproducible voice case with evidence for both conversation behavior and the selected business requirement. Expand the suite only after its setup and evidence are reliable. Use [troubleshooting](https://learning.contextqa.com/ai-agent-testing/voice-ai-testing/troubleshooting.md) when a call is incomplete or the result cannot be confidently interpreted.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/ai-agent-testing/voice-ai-testing/quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
