> 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/en/build/agent/voice-agent.md).

# Voice Agent

Enable Agents to serve customers by listening and speaking, with real-time conversations, STT/LLM/TTS pipelines, and interruption control

{% hint style="info" %}
This feature is currently in Beta. Features and the interface may change.

A <mark style="color:blue;">Beta</mark> badge appears beside <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">Voice Agent</mark> in the left menu, the page title, and “AI Voice Assistant” under “Advanced Features” in the organization overview. Features and screens may change in the future. See [Release stage badges](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/organization-overview.md#release-stage-badges) for what the badge means.
{% endhint %}

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

Voice Agents let Agents interact through **voice**: users speak, and the AI speaks back. They integrate real-time voice models, STT (speech-to-text), TTS (text-to-speech), and interruption control for scenarios such as phone support, IVR, and voice assistants.

Once enabled, users see a button in the input bar in MaiGPT, the Agent Marketplace, and Web Chat to enter “Voice Interaction Mode.” Click it to start speaking. See [How users interact](#how-users-talk).

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

On the <mark style="color:blue;">Voice Agent</mark> settings page, select the voice workflow under <mark style="color:blue;">Interaction Mode</mark>:

| Mode                                                            | How it works                                                            |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <mark style="color:blue;">Real-time Voice</mark>                | A real-time voice model listens and responds directly with speech       |
| <mark style="color:blue;">Real-time Voice + Custom Voice</mark> | A real-time voice model uses text-to-speech (TTS) for output            |
| <mark style="color:blue;">Pipeline</mark>                       | Speech-to-text (STT) → linked AI assistant → text-to-speech (TTS)       |
| <mark style="color:blue;">Assist</mark>                         | Generates suggested replies after speech-to-text; the AI does not speak |

## Configuring a Voice Agent <a href="#voice-settings-walkthrough" id="voice-settings-walkthrough"></a>

From the left menu, go to <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">Voice Agent</mark> and open the Voice Agent you want to adjust. <mark style="color:blue;">Basic Settings</mark> lists the <mark style="color:blue;">Linked AI Assistant</mark>; the Voice Agent uses its knowledge bases, tools, and prompts to answer.

{% hint style="info" %}
Previously, voice settings were part of the AI assistant's “Response Mode Settings.” For organizations that have switched to the new entry point, this area now lists linked Voice Agents. Edit voice parameters under “Voice Agent.” If your organization has not switched and still shows “Voice Assistant Settings,” continue using the original provider and JSON configuration interface. This difference depends on the organization's interface, not whether the AI assistant is new or old.
{% endhint %}

### 1. Voice components <a href="#voice-settings-tech" id="voice-settings-tech"></a>

After selecting an interaction mode, go to <mark style="color:blue;">Voice Components</mark> to adjust the models and parameters used by that mode:

1. Find the <mark style="color:blue;">Real-time Voice Model</mark>, <mark style="color:blue;">Speech-to-Text (STT)</mark>, or <mark style="color:blue;">Text-to-Speech (TTS)</mark> you want to adjust, then click <mark style="color:blue;">Edit</mark> on the right.
2. Under <mark style="color:blue;">Model</mark> in the side panel, select a provider and model, then adjust fields such as the voice. Expand <mark style="color:blue;">Advanced Parameters</mark> as needed for other settings.
3. Click <mark style="color:blue;">Collapse</mark> to return to the settings page, then click <mark style="color:blue;">Save</mark> at the bottom of the page to apply your changes. Collapsing the panel alone does not save them.

The screen explains which voice components the current interaction mode does not use. It also explains why certain models or settings are unavailable. If you see an “Action Required” notice, follow the instructions to choose a different model or correct the parameters.

#### Choosing a real-time voice model <a href="#realtime-model-choice" id="realtime-model-choice"></a>

Go to <mark style="color:blue;">Voice Components</mark> → <mark style="color:blue;">Real-time Voice Model</mark> → <mark style="color:blue;">Edit</mark>, then expand <mark style="color:blue;">Model</mark>. The following real-time voice models are currently available, displayed as “Provider · Model Name”:

| Provider           | Model                                                                             |
| ------------------ | --------------------------------------------------------------------------------- |
| Google Gemini Live | `gemini-3.8-live`                                                                 |
| OpenAI Realtime    | `gpt-realtime-1.5`, `gpt-realtime-2`, `gpt-realtime-2.1`, `gpt-realtime-2.1-mini` |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a0ef62b3a82d53fdd5ed5ecab2d299e106b85a37%2Fvoice-agent-realtime-model-options.png?alt=media" alt="Real-time voice model menu listing Google Gemini Live&#x27;s gemini-3.8-live and OpenAI Realtime&#x27;s gpt-realtime-1.5, 2, 2.1, and 2.1-mini"><figcaption><p>Edit the real-time voice model in Voice Components</p></figcaption></figure>

`gemini-live-2.5-flash-native-audio` is no longer available in the selection list. Refer to the settings page for the current model list and available combinations.

Real-time voice calls consume Credits based on voice and text input and output usage for the selected model. Go to <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Credits</mark> → <mark style="color:blue;">Billing Methods</mark>, then expand <mark style="color:blue;">Speech Recognition and Synthesis Technologies</mark> to view each model's rates for items such as <mark style="color:blue;">Real-time Voice Output (Text)</mark>. See [Credits billing system](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md).

{% hint style="info" %}
`gemini-3.8-live` thinks before answering. This thinking usage is included in <mark style="color:blue;">Real-time Voice Output (Text)</mark> and charged at the 3.8 text output rate.
{% endhint %}

{% hint style="warning" %}
`gpt-realtime` is no longer on the menu. The platform has automatically switched Agents that previously used `gpt-realtime` to `gpt-realtime-2.1`. Existing voice, speech rate, output mode, turn detection, and user transcript settings are preserved, so no reconfiguration is needed. After the switch, only the <mark style="color:blue;">Real-time Voice Output (Text)</mark> rate is 1.5 times the original rate; rates for other real-time voice billing items remain unchanged. Compare the two models' rates under <mark style="color:blue;">Billing Methods</mark>.
{% endhint %}

### 2. Voice prompt <a href="#voice-settings-prompt" id="voice-settings-prompt"></a>

The <mark style="color:blue;">Voice Prompt</mark> provides instructions to the real-time model. Leave it blank to use the linked AI assistant's prompt. <mark style="color:blue;">Pipeline</mark> and <mark style="color:blue;">Assist</mark> modes do not have a separate prompt here. Follow the on-screen instructions to open the linked AI assistant's settings and adjust its <mark style="color:blue;">Role Instructions</mark>.

### 3. Conversation behavior <a href="#voice-settings-behavior" id="voice-settings-behavior"></a>

* <mark style="color:blue;">Voice Replies</mark>: Turn this off to keep only text records without playing the AI's voice. Some modes or models disable this option; the screen explains why.
* <mark style="color:blue;">Allow Interruptions</mark>: Determines whether the other party can interrupt while the AI is speaking. Available parameters vary by mode and model. See [Interruption control](#turn-handling).

When finished, click <mark style="color:blue;">Save</mark> at the bottom of the page. The greeting, access points and links, login settings, and test calls are under <mark style="color:blue;">Conversation Platform Settings</mark> at the top right.

For settings and instructions on holding to record and releasing to send, see [Push-to-talk](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/voice-agent/push-to-talk.md).

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

Go to <mark style="color:blue;">Conversation Behavior</mark> to view interruption settings available for the current mode. The settings page identifies unavailable options and explains why. For example, <mark style="color:blue;">Minimum Interruption Character Count</mark> only applies to Pipeline mode, because speech must first be recognized as text before characters can be counted.

## User transcript settings (Realtime mode) <a href="#user-transcript-settings" id="user-transcript-settings"></a>

The user transcript is the text of the user's side of the call in the call record. When using an OpenAI real-time voice model, go to <mark style="color:blue;">Voice Components</mark> → <mark style="color:blue;">Real-time Voice Model</mark> → <mark style="color:blue;">Edit</mark>. Under <mark style="color:blue;">Advanced Parameters</mark>, expand <mark style="color:blue;">Other Party's Transcript</mark> to adjust the transcript model, language, and prompt.

| Setting             | Description                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Transcript model    | Choose from `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-transcribe`, and `gpt-live-transcribe`; the default is `gpt-4o-mini-transcribe` |
| Transcript language | Specify a language, or leave blank for automatic detection                                                                                      |
| Prompt              | Enter expected technical terms or specify output in Traditional Chinese                                                                         |

These settings only affect the user transcript. They do not change what the voice model hears or how it answers. User transcripts consume Credits based on speech-to-text seconds using the actual transcription model. See [Credits billing system](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md) for rates.

## 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 speech
* **Thinking**: The AI is processing (searching knowledge bases, using tools, or generating a reply)
* **Responding**: The AI is responding with speech
* **Initializing**: The connection has just been established and is being prepared

## How users interact <a href="#how-users-talk" id="how-users-talk"></a>

Once voice is enabled for an Agent, users can switch from the existing text chat screen to voice without any setup:

| Where the user is                                                                                                                          | Entry point                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat pages in <mark style="color:blue;">MaiGPT</mark> and the <mark style="color:blue;">Agent Marketplace</mark> in the management console | A <mark style="color:blue;">Voice Interaction Mode</mark> button appears on the right side of the input bar. The organization must have AI Voice Assistant activated, and voice must be enabled for the Agent in the current conversation                                                                                                                                                                                                               |
| Web Chat on a website                                                                                                                      | The <mark style="color:blue;">headphones</mark> icon next to the input box (different from the microphone icon for [voice input](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat.md#voice-input-and-playback): the microphone converts a spoken utterance to text and sends it; headphones start a real-time call)                                                                                                        |
| Standalone voice conversation page                                                                                                         | A <mark style="color:blue;">Voice Mode</mark> link appears beside the conversation platform's <mark style="color:blue;">Public Access URL</mark> (see [Basic settings](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings/basic-settings.md#public-url-and-embed)). It opens a page dedicated to calls: click <mark style="color:blue;">Start Conversation</mark>; “Dialing” appears, then the call connects |

### Voice Interaction Mode window <a href="#voice-mode-window" id="voice-mode-window"></a>

After you click the button, the browser first requests microphone permission (on first use). The button displays “Connecting...”, then the <mark style="color:blue;">Voice Interaction Mode</mark> window opens:

| Section                                                                                                    | Description                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Usage Guidelines</mark>                                                          | Instructions you can read before starting; see [Limitations](#limitations) for related considerations                                                                                                                                                                                                            |
| <mark style="color:blue;">Connection Status</mark>                                                         | Disconnected → Connecting... → Connected; displays “Connection Failed” if unsuccessful                                                                                                                                                                                                                           |
| Current state                                                                                              | <mark style="color:blue;">Initializing</mark> / <mark style="color:blue;">Listening</mark> / <mark style="color:blue;">Thinking</mark> / <mark style="color:blue;">Responding</mark>; see [Conversation states](#conversation-states). Displays “Subagent Responding…” when the Agent delegates to another Agent |
| <mark style="color:blue;">Conversation History</mark>                                                      | Live text record of this call; displays “Waiting for conversation to start...” before the call connects                                                                                                                                                                                                          |
| <mark style="color:blue;">Turn Microphone Off</mark> / <mark style="color:blue;">Turn Microphone On</mark> | Temporarily mute or unmute; a “Recording” indicator appears while recording                                                                                                                                                                                                                                      |
| <mark style="color:blue;">End Call</mark>                                                                  | Disconnects and closes the window. The call content remains as text in the original conversation, so you can continue by typing                                                                                                                                                                                  |

### Common messages <a href="#voice-mode-messages" id="voice-mode-messages"></a>

| On-screen message                                                                       | What to do                                                                                                                                                    |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| “Microphone permission denied” / “Please allow microphone access to use voice features” | Allow microphone access in the site permissions on the left side of the browser's address bar, then click again                                               |
| “No microphone device found”                                                            | Check that a microphone or headset is connected and selected in your system's sound settings                                                                  |
| “Assistant connection timed out. Please try again later”                                | The voice service did not connect. Wait a few seconds and try again. If the issue persists, ask an administrator to check the Agent's voice provider settings |
| “Unable to start Voice Interaction Mode”                                                | The system temporarily cannot establish a voice connection. Try again later; if the issue persists, contact an administrator                                  |

## How does it differ from text chat? <a href="#voice-vs-text" id="voice-vs-text"></a>

|                          | Text assistant                                      | Voice assistant                                               |
| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------- |
| **Input**                | Typing and file uploads                             | Microphone audio, possibly with DTMF key presses              |
| **Output**               | Text, Markdown, images, and files                   | Speech, followed by a text transcript                         |
| **Latency requirements** | Delays of seconds are acceptable                    | Millisecond-level latency is needed for a natural experience  |
| **Suitable scenarios**   | Detailed information and records users will revisit | Immediate responses, hands-busy situations, and phone support |

## Suitable scenarios <a href="#when-to-use" id="when-to-use"></a>

* **Phone support**: Replace traditional IVR with AI that answers calls, listens to questions, and provides answers
* **Voice query systems**: Customers call to check orders, balances, or insurance policies
* **Voice FAQ**: Ask common questions directly by speaking
* **Driving / hands-busy situations**: Users need AI assistance but cannot type
* **Accessibility**: More accessible for users who have difficulty typing

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

* **Knowledge base search**: Voice Agents search all linked knowledge bases; **you cannot restrict searches to specific documents**
* **Model and mode combinations**: Choose from the options and guidance in the voice component panel. See [Choosing a real-time voice model](#realtime-model-choice)
* **Microphone permission**: Users must grant the browser microphone access before starting a conversation

## 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 <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">Voice Agent</mark>, open the Voice Agent you want to adjust, and confirm the linked AI assistant.
2. Select an [interaction mode](#interaction-modes), then adjust models and parameters under [Voice components](#voice-settings-tech).
3. Fill in the voice prompt and adjust conversation behavior as needed, then click <mark style="color:blue;">Save</mark>.
4. Go to <mark style="color:blue;">Conversation Platform Settings</mark> to configure access points and test.

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

* [Voice support: From setup to launch](https://docs.maiagent.ai/maiagent-user-guide/en/serve/voice.md)
* [Phone support (Call Center)](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/call-center.md)
* [Voice support scenarios overview](https://docs.maiagent.ai/maiagent-user-guide/en/serve/voicecs.md)
* [IVR customer intent recognition](https://docs.maiagent.ai/maiagent-user-guide/en/serve/voicecs/ivr-intent-recognition.md)
* [Voice call summaries](https://docs.maiagent.ai/maiagent-user-guide/en/serve/voicecs/call-summary.md)
* [Voice call quality evaluation](https://docs.maiagent.ai/maiagent-user-guide/en/serve/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 by asking a question.

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

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/voice-agent.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.
