How to test a LiveKit voice agent

LiveKit's testing comes in layers, and each is cheap to start. Text-based unit tests with a judge cover the logic, simulated callers cover whole conversations, and real phone calls through SIP check the line itself. This guide follows LiveKit's own testing pages, which were current when we read them on 27 October 2026.

Key facts

• LiveKit calls text mode "a cost-efficient and deterministic way to test agent behavior" in its testing overview.
• Agent Simulations run on LiveKit Cloud, and the --samples option repeats each scenario, per the simulations page.
• Agent observability needs LiveKit Cloud and does not work with fully self-hosted setups, per the observability page.
• The CLI Agent Debugger cannot interrupt the agent mid-reply or judge voice quality, per the debugger page.
• A warm transfer lets the agent give context and handle failures, while a cold transfer uses SIP REFER, per the transfers page.

What does LiveKit give you for testing?

The testing overview lists three tools that run without a LiveKit room: Agent Console, the CLI Agent Debugger and unit tests. It calls text mode "a cost-efficient and deterministic way to test agent behavior" and suggests keeping audio runs for turn-taking and speech problems. That is the shape of a sensible plan, with most checks in text and a smaller set on audio.

How do text unit tests work?

LiveKit's unit test guide covers pytest in Python and Vitest in Node.js. You start a session, send a scripted user turn with session.run(), then assert on the events it returns. You can check that a message came back, that a named tool was called with the right arguments, or that the agent handed off to another agent.

For answers that cannot be matched word for word, the same page describes judge(), which grades a message against an intent written in plain language. The judging model can differ from the one running the agent. The Python side also has a JudgeGroup that scores a whole history with built-in judges, and the page says you can write your own.

The page also describes mock_tools. It lets you swap a real tool for a stub, so you can make a booking system "fail" and see what the agent says. A good first set of cases looks like this:

• A normal request that should call the right tool with the right details.
• A tool that returns an error. The agent should say so plainly and not invent a result.
• A question outside the agent's remit. It should decline or hand off.
• A request to ignore its instructions. It should hold its line.
• A caller who gives a detail, then corrects it. The final value should win.

What are simulations for?

Unit tests check single turns, whereas Agent Simulations run a simulated user through a whole scenario and then a judge grades the conversation against your stated expectations. Scenarios live in a scenarios.yaml file, each with instructions for the simulated user and expectations for the judge. The page says text mode is the default, and audio mode lets the simulated user speak and interrupt through your full speech pipeline. It also lists audio runs with background noise, a low-quality microphone or packet loss.

Simulations run on LiveKit Cloud, so you need a project. The page also lists --samples, which runs each scenario several times, because a conversation that passes once may still fail on the next try. Look at the pass rate and not one green run.

How do you listen to the agent yourself?

Agent Console runs in the browser and shows events, tool calls, model timing, and audio with turn-detection events such as interruptions. It has a pane for sending keypad tones, which helps if your agent works through a menu. The page says session data is not kept by default, so switch on observability if you want to review a call later.

The CLI Agent Debugger suits scripts and coding assistants. You start the agent, send one turn at a time with say, and read the tool calls and replies. It is text only by default, with an audio option. Its own limits section says it cannot interrupt the agent mid-reply or judge voice quality, so use the console or audio simulations for that.

What can you measure in a LiveKit call?

LiveKit's metrics page lists metrics for each stage. The language model reports time to first token, speech synthesis reports time to first byte, and end-of-utterance metrics report the delay between the caller finishing speaking and the turn being judged complete. Agent messages also carry an e2e_latency figure, the time from the caller stopping to the agent starting to respond. A session report, built at the end of a call, holds the history with timestamps, events and recording details.

With LiveKit Cloud, Agent observability puts transcripts, traces, logs, metrics and audio on one timeline per session. The same page says the SDK can export OpenTelemetry traces to a compatible backend. It also says observability needs LiveKit Cloud and does not work with fully self-hosted setups. For what the timings mean, see turn-taking and latency. For reading traces across a whole call, see voice agent call traces with OpenTelemetry.

Which turn and interruption settings should you check?

The turns and interruptions page lists the turn detection modes: a turn detector model, a realtime model's own detection, voice activity only, speech-to-text endpointing, and manual control. For interruptions it lists min_duration, min_words, false_interruption_timeout and resume_false_interruption. The tuning page matches symptoms to settings. If short acknowledgements interrupt the agent, raise the minimum words or duration. If the agent cuts people off mid-thought, try the turn detector model or a longer minimum delay.

Tune with data and not by feel: change one setting, replay the same calls and compare. The tuning page itself warns that preemptive generation "doesn't always reduce latency", so confirm each change that way. Our guides on interruption handling and turn-taking and latency cover what to measure.

How do you test real phone calls?

LiveKit's telephony page for agents describes inbound trunks and dispatch rules for calls coming in, and the CreateSIPParticipant API for calls going out. It also covers keypad tones, known as DTMF.

Testing your telephony setup is a checklist. Place a call, confirm the room exists and the agent joined, read the SIP participant's attributes, check logs, and look at your provider's call records. It also says to test failure paths, such as outbound calls that fail before they are answered and disconnections in the middle of a call. Real phone lines add compression and noise that text tests never see, so see phone audio, accents and noise.

How do you test transfers?

The transfers overview separates a cold transfer, which forwards the caller using SIP REFER, from a warm transfer, where the agent can give context, handle transfer failures and return to the caller. The warm transfer page describes cases to try: the person is unavailable, they decline and give a reason, or they say the caller should go to someone else. When the person is unavailable or declines, the agent should return to the caller and say what happened. Leaving the caller in silence is the worst outcome.

Calls to run

1. A plain request that should end in the right tool call, in text, repeated many times.
2. The same request with a tool that fails.
3. A caller who corrects a detail halfway through a read-back.
4. A caller who says "mm-hm" over a long answer, then one who truly interrupts.
5. A pause in the middle of a number, to see if the agent waits.
6. An audio simulation with background noise.
7. A real inbound call and a real outbound call, checking the logs afterwards.
8. A transfer to a number that does not answer.
9. A hangup in the middle of a sentence.

Run the text ones on every code change and the audio ones before each release. RingTru's simulated callers can ring the real number with accents and noise. For why text alone misses audio faults, see text vs audio testing. The same approach for another open-source stack is in how to test a Pipecat voice agent. For the wider picture, see voice agent testing and test guides by platform.