Guides

Voice agent testing, step by step

Practical walkthroughs for the testing scenarios that matter most. Each guide assumes you have completed the quickstart and have at least one agent registered.

Guides are detailed docs pages that walk through a specific testing scenario from start to finish. They use the same v1 API shape documented in the API reference and are kept up to date with every API change. All code samples are real and runnable.

If you are new to Vexa, start with the documentation quickstart to register your first agent and run a suite before working through these guides.

Guides catalog

All guides

Eight practical walkthroughs. Difficulty levels reflect familiarity with the Vexa API, not programming skill.

Test a bank card-replacement agent

Beginner8 min read

Build a complete test suite for a card-replacement IVR: normal flow, angry caller, caller refusing identity verification, and mailing address confirmation. Score each variant across five accents.

BankingIVR

In the docs

Catch barge-in regressions

Intermediate5 min read

Barge-in failures are silent: your agent sounds fine until a fast-talking caller interrupts and the call collapses. Learn how to build a barge-in-heavy suite and gate deployments on bargeIns count.

Voice qualityInterruption

In the docs

Score code-switching calls

Intermediate6 min read

US Spanish bilingual callers switch languages mid-call. Use Vexa's Lucia and Rafael voices with code-switching scenarios, measure WER on each language segment, and tune your LLM prompts accordingly.

MultilingualWER

In the docs

Gate CI on task success

Beginner4 min read

Add a Vexa run step to GitHub Actions that fails the build when task success drops below 0.85 or WER rises above 8%. Includes a complete workflow YAML and tips for caching suite results.

CI/CDGitHub Actions

In the docs

Build a custom scenario suite

Advanced7 min read

Go beyond built-in suites: write your own scenario personas, opening utterances, and success conditions via the API. Learn how to seed a suite from a production call transcript.

ConfigurationAPI

In the docs

Compare two TTS providers

Intermediate6 min read

Running the same suite with two different TTS engines on your agent lets you measure whether a provider switch changes task success, latency, or WER. Step-by-step comparison workflow.

TTSProvider testing

In the docs

Audit accent coverage across 16 voices

Intermediate5 min read

High task success on General American is not enough. Run a full accent audit across all 16 Vexa voices, identify which accents expose weaknesses in your transcription pipeline, and fix them.

LocalizationAccents

In the docs

Debug WER spikes in your transcription pipeline

Advanced8 min read

A WER spike in a Vexa run points to a specific turn, voice, or latency condition. Learn how to read the turns array, isolate the failing scenario, and reproduce it outside Vexa.

WERDiagnostics

In the docs

Individual guide pages are in progress. All guides live in the documentation and the API reference covers every field referenced across these walkthroughs. Questions? Reach out at support@vexavoice.tech.

Most requested

Gate your CI pipeline in four lines

The most common first guide request. Copy this into your GitHub Actions workflow and you are done.

.github/workflows/voice-regression.yml

name: Voice regression

on:
  push:
    branches: [main]
  pull_request:

jobs:
  vexa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Vexa regression suite
        run: |
          npx vexa@latest run \
            --agent ${{ secrets.VEXA_AGENT_ID }} \
            --suite suite_card_replacement \
            --fail-below taskSuccess=0.85 \
            --fail-below werPct=8.0
        env:
          VEXA_API_KEY: ${{ secrets.VEXA_API_KEY }}

The CLI exits non-zero when a threshold is breached, failing the build automatically. See the full CI guide for caching, multi-suite runs, and PR comments with score diffs.

Every voice, tested.

Read the quickstartBrowse the API