> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/agent-builder/voice-agent.md).

# Voice Agent

## What Is This? <a href="#what-is-this" id="what-is-this"></a>

Voice Agent enables AI Assistants to interact through **voice**: users speak, and the AI responds by speaking back. It integrates real-time voice models, STT (Speech-to-Text), TTS (Text-to-Speech), and interruption control under the hood, making it suitable for phone customer service, IVR, voice assistants, and similar scenarios.

Once enabled, the AI Assistant gains a "Voice Call" interface where users can tap the microphone to start a conversation.

## Three Interaction Modes <a href="#interaction-modes" id="interaction-modes"></a>

Different modes suit different needs, depending on latency, voice customization flexibility, and tool support.

| Mode                | How It Works                                                | Best For                                                                                                              |
| ------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Realtime**        | Uses a voice model for direct real-time voice conversation  | Scenarios requiring the lowest latency where the default voice is acceptable                                          |
| **Realtime + TTS**  | Real-time voice model paired with custom TTS output         | Scenarios needing a custom brand voice while maintaining a real-time feel                                             |
| **STT + LLM + TTS** | Traditional pipeline: Speech-to-Text → LLM → Text-to-Speech | Scenarios requiring full tool support, where slightly higher latency is acceptable and maximum flexibility is desired |

**Quick decision**: For the fastest and most natural experience → Realtime; for a branded voice → Realtime + TTS; for maximum flexibility and tool support → STT + LLM + TTS.

## Interruption Control (Turn Handling) <a href="#turn-handling" id="turn-handling"></a>

A critical aspect of the voice conversation experience — can the user interrupt the AI while it's speaking? How does the system determine whether the user is actually speaking versus background noise or filler words?

Adjustable parameters:

| Parameter                             | Description                                                                                      |
| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Minimum speech duration (seconds)** | The user's speech must last at least this many seconds to be recognized as "I want to interrupt" |
| **Minimum word count**                | The user must say at least this many words to trigger an interruption                            |

> **Note**: `min_duration` and `min_words` are only effective in **STT + LLM + TTS** mode. In Realtime mode, interruption detection is handled internally by the voice model.

## Conversation States <a href="#conversation-states" id="conversation-states"></a>

During a voice conversation, the interface displays the current state:

* **Listening**: The AI is receiving the user's voice input
* **Thinking**: The AI is processing (searching the knowledge base, using tools, generating a response)
* **Responding**: The AI is replying with voice output
* **Initializing**: The connection has just been established and is being prepared

## How Is This Different from Text Chat? <a href="#voice-vs-text" id="voice-vs-text"></a>

|                          | Text Assistant                                             | Voice Agent                                                |
| ------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------- |
| **Input**                | Keyboard typing, file attachments                          | Microphone voice input, possibly DTMF key presses          |
| **Output**               | Text, Markdown, images, files                              | Voice, with a text transcript appended afterward           |
| **Latency requirements** | Seconds-level is acceptable                                | Must be milliseconds-level to feel natural                 |
| **Best for**             | Detailed information needs, reviewing conversation history | Immediate responses, hands-busy situations, phone channels |

## Best Use Cases <a href="#when-to-use" id="when-to-use"></a>

* **Phone customer service**: Replace traditional IVR — AI directly answers calls, listens to questions, and provides answers
* **Voice query systems**: Customers call to check orders, balances, or insurance policies
* **Voice FAQ**: Common questions answered by simply speaking
* **Driving / hands-busy scenarios**: Users can't type but need AI assistance
* **Accessibility needs**: More friendly for users who have difficulty typing

## Limitations <a href="#limitations" id="limitations"></a>

* **Tool support**: Currently, **Realtime** and **Realtime + TTS** modes only support **MCP Tools**; to use API Tools, switch to STT + LLM + TTS mode
* **Knowledge base search**: Voice Agent searches all linked knowledge bases and **cannot be restricted to specific documents only**
* **Microphone permissions**: Users must grant browser microphone access before the conversation can begin

## What Do I Need to Do? <a href="#what-do-i-need-to-do" id="what-do-i-need-to-do"></a>

1. **Go to AI Assistant settings** — Navigate to the settings page of the Agent you want to enable voice for
2. **Select voice agent mode** — Choose one of the three: Realtime / Realtime + TTS / STT + LLM + TTS
3. **Configure provider and settings** — Select the corresponding STT / TTS / Realtime provider and JSON configuration for your chosen mode
4. **Adjust interruption control** (optional) — In STT + LLM + TTS mode, adjust minimum duration and minimum word count
5. **Test** — Open a voice call in the interface and confirm that the Listening, Thinking, and Responding states all work smoothly

## Further Reading <a href="#further-reading" id="further-reading"></a>

* [Voice Customer Service Scenarios Overview](/maiagent-user-guide/maiagent-user-guide-en/application/voicecs.md)
* [IVR Customer Service Intent Recognition](/maiagent-user-guide/maiagent-user-guide-en/application/voicecs/ivr-intent-recognition.md)
* [Voice Call Summary](/maiagent-user-guide/maiagent-user-guide-en/application/voicecs/call-summary.md)
* [Voice Call Quality Inspection](/maiagent-user-guide/maiagent-user-guide-en/application/voicecs/call-qa.md)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/agent-builder/voice-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.