# Start a conversational AI agent (/en/api-reference/api-ref/conversational-ai/join)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Creates and starts a Conversational AI agent instance.

- OpenAPI: /openapi/conversational-ai/rest-api.en.yaml
- Operation ID: start-agent
- Method: POST
- Path: /v2/projects/{appid}/join

## Servers

- https://api.agora.io/api/conversational-ai-agent

## Parameters

- `appid` (path, required) - The App ID of the project.

## Request body

- `name` (string, required) - The unique identifier of the agent. The same identifier cannot be used repeatedly.
No schema.
- `preset` (string) - Deprecated. Use `credential_mode: "managed"` within the `asr`, `llm`, or `tts` block instead. See [Use managed mode](/en/ai/build/custom-model-integration/managed-mode).

A comma-separated string of one or more presets. Each preset provides a predefined configuration for ASR, LLM, and TTS. You can specify a preset for any or all of ASR, LLM, and TTS. When a preset is specified, you do not need to provide the endpoint URL, API key, or model for the preset providers. Use the `asr`, `llm`, and `tts` fields to configure additional settings.
No schema.
- `pipeline_id` (string) - The unique ID of a published agent in Conversational AI Studio. When provided, the saved agent configuration is used as the base configuration. Any fields specified in `properties` override the corresponding agent settings. When you specify a `pipeline_id`, the `asr`, `tts`, and `llm` fields in `properties` are optional.

The unique ID of a published agent in STUDIO. When provided, the saved agent configuration is used as the base configuration. Any fields specified in properties override the corresponding agent settings. When you specify a pipeline_id, the asr, tts, and llm fields in properties are optional.
No schema.
- `properties` (object, required) - Configuration details of the agent.
  - `properties.channel` (string, required) - The name of the channel to join.
No schema.
  - `properties.token` (string, required) - The authentication token used by the agent to join the channel.
No schema.
  - `properties.agent_rtc_uid` (string, required) - The user ID of the agent in the channel. All UIDs within an RTC channel must be unique. Ensure no other user or service bot is using this UID. A value of `0` means that a unique random UID is generated and assigned. Set the `token` accordingly.
No schema.
  - `properties.remote_rtc_uids` (array, required) - A list of user IDs that the agent subscribes to in the channel. Only subscribed users can interact with the agent.
    - `properties.remote_rtc_uids.items` (string)
No schema.
  - `properties.enable_string_uid` (boolean) - Whether to enable String uid:

- `true`: Both agent and subscriber user IDs use strings.

- `false`: Both agent and subscriber user IDs must be integers.
No schema.
  - `properties.idle_timeout` (integer) - The maximum idle time in seconds after all users specified in `remote_rtc_uids` are detected to have left the channel. When the idle time exceeds this value, the agent automatically stops and exits the channel. The valid range is `0` to `259200` (72 hours).
- When set to `0`, the agent does not exit due to channel idle timeout.
- Regardless of the `idle_timeout` value, the maximum running time for a single session is 72 hours. The agent automatically exits after 72 hours.
No schema.
  - `properties.geofence` (object) - Regional access restriction configuration. Use this to limit which Agora servers the Conversational AI Engine can access based on geographic regions.
    - `properties.geofence.area` (string, required) - The allowed region for server access.
No schema.
    - `properties.geofence.exclude_area` (string) - The excluded region. Only available when `area` is set to `GLOBAL`.
No schema.
  - `properties.advanced_features` (object) - Advanced features configuration.
    - `properties.advanced_features.enable_mllm` (boolean) - Use [mllm.enable](#properties-mllm-enable) instead.

Enable Multimodal Large Language Model for voice-to-voice processing. Enabling MLLM automatically disables ASR, LLM, and TTS since the MLLM handles end-to-end voice processing directly. See `turn_detection.type` for turn detection options available with MLLM.
No schema.
    - `properties.advanced_features.enable_rtm` (boolean) - Whether to enable the Signaling (RTM) service. When enabled, the agent can combine the capabilities provided by Signaling to implement advanced functions, such as delivering [custom information](/en/ai/build/shape-the-conversation/custom-information).
No schema.
    - `properties.advanced_features.enable_sal` (boolean) - Enable Selective Attention Locking (SAL). When enabled, configure the `sal` field to set up speaker recognition or locking modes. See the `sal` parameter for configuration details.
No schema.
    - `properties.advanced_features.enable_tools` (boolean) - Enable tool invocation. When enabled, the agent can invoke tools provided by the MCP server to implement advanced functionality.
No schema.
  - `properties.asr` (object) - Automatic Speech Recognition (ASR) configuration.
    - `properties.asr.credential_mode` (string) - The credential mode for this provider:

- `managed`: Use Agora-managed credentials. You do not need to provide an API key. See [Use managed mode](/en/ai/build/custom-model-integration/managed-mode).

- `byok`: Bring your own key. Provide your own provider credentials, including the API key.
No schema.
    - `properties.asr.language` (string) - The BCP-47 language tag identifying the primary language used for agent interaction. If `params` contains a vendor-specific language code, it takes precedence over this setting.
No schema.
    - `properties.asr.vendor` (string) - ASR provider:
- `ares`: [Adaptive Recognition Engine for Speech](/en/ai/models/asr/ares)
- `microsoft`: [Microsoft Azure](/en/ai/models/asr/microsoft)
- `deepgram`: [Deepgram](/en/ai/models/asr/deepgram)
- `openai`: [OpenAI](/en/ai/models/asr/openai)
- `speechmatics`: [Speechmatics](/en/ai/models/asr/speechmatics)
- `assemblyai`: [AssemblyAI](/en/ai/models/asr/assembly-ai)
- `amazon`: Amazon Transcribe
- `google`: [Google](/en/ai/models/asr/google)
- `sarvam`: [Sarvam](/en/ai/models/asr/sarvam)
- `xai`: [xAI](/en/ai/models/asr/xai)
No schema.
    - `properties.asr.params` (object, required) - The configuration parameters for the selected ASR vendor. For vendor-specific parameters, see the corresponding ASR provider page listed in `asr.vendor`.
No schema.
  - `properties.tts` (object, required) - Text-to-speech (TTS) module configuration.
    - `properties.tts.credential_mode` (string) - The credential mode for this provider:

- `managed`: Use Agora-managed credentials. You do not need to provide an API key. See [Use managed mode](/en/ai/build/custom-model-integration/managed-mode).

- `byok`: Bring your own key. Provide your own provider credentials, including the API key.
No schema.
    - `properties.tts.vendor` (string, required) - TTS provider.
- `microsoft`: [Microsoft Azure](/en/ai/models/tts/microsoft)
- `elevenlabs`: [ElevenLabs](/en/ai/models/tts/elevenlabs)
- `minimax`: [MiniMax](/en/ai/models/tts/minimax)
- `deepgram`: [Deepgram](/en/ai/models/tts/deepgram)
- `murf`: [Murf](/en/ai/models/tts/murf)
- `cartesia` : [Cartesia](/en/ai/models/tts/cartesia)
- `openai`: [OpenAI](/en/ai/models/tts/openai)
- `humeai`: [Hume AI](/en/ai/models/tts/humeai)
- `rime`: [Rime](/en/ai/models/tts/rime)
- `fishaudio`: [Fish Audio](/en/ai/models/tts/fish-audio)
- `google`: [Google](/en/ai/models/tts/google)
- `amazon`: [Amazon Polly](/en/ai/models/tts/amazon)
- `sarvam`: [Sarvam](/en/ai/models/tts/sarvam)
- `xai`: [xAI](/en/ai/models/tts/xai)
No schema.
    - `properties.tts.params` (object, required) - The configuration parameters for the selected TTS vendor. For vendor-specific parameters, see the corresponding TTS provider page listed in `tts.vendor`.
No schema.
    - `properties.tts.skip_patterns` (array) - Controls whether the TTS module skips bracketed content when reading LLM response text. This prevents the agent from vocalizing structural prompt information like tone indicators, action descriptions, and system prompts, creating a more natural and immersive listening experience. Enable this feature by specifying one or more values:
- `1`: Skip content in Chinese parentheses `（）`
- `2`: Skip content in Chinese square brackets `【】`
- `3`: Skip content in parentheses `( )`
- `4`: Skip content in square brackets `[ ]`
- `5`: Skip content in curly braces `{ }`
      - `properties.tts.skip_patterns.items` (integer)
No schema.
  - `properties.llm` (object, required) - Large language model (LLM) configuration.
    - `properties.llm.credential_mode` (string) - The credential mode for this provider:

- `managed`: Use Agora-managed credentials. You do not need to provide an API key. See [Use managed mode](/en/ai/build/custom-model-integration/managed-mode).

- `byok`: Bring your own key. Provide your own provider credentials, including the API key.
No schema.
    - `properties.llm.url` (string, required) - The LLM callback address.
No schema.
    - `properties.llm.api_key` (string) - The LLM verification API key. The default value is an empty string. Ensure that you enable the API key in a production environment.
No schema.
    - `properties.llm.system_messages` (array) - A set of predefined information used as input to the LLM, including prompt words and examples.
      - `properties.llm.system_messages.items` (object)
No schema.
    - `properties.llm.params` (object) - Additional LLM configuration parameters, such as the `model` used, and the maximum token limit. For vendor-specific parameters, see the corresponding LLM provider page listed in `llm.vendor`.
No schema.
    - `properties.llm.max_history` (integer) - The number of conversation history messages cached in the LLM. History includes user and agent dialog messages, tool call information, and timestamps. Agent and user messages are recorded separately.
No schema.
    - `properties.llm.input_modalities` (array) - LLM input modalities:
- `["text"]`: Text only
- `["text", "image"]`: Text plus image. Recommended configuration, requires the selected LLM to support visual input
      - `properties.llm.input_modalities.items` (string)
No schema.
    - `properties.llm.output_modalities` (array) - LLM output modalities:
- `["text"]`: The output text is converted to speech by the TTS module and then published to the RTC channel.
- `["audio"]`: Voice only. Voice is published directly to the RTC channel.
- `["text", "audio"]`: Text plus voice. Write your own logic to process the output of LLM as needed.
      - `properties.llm.output_modalities.items` (string)
No schema.
    - `properties.llm.greeting_configs` (object) - Agent greeting broadcast configuration.
      - `properties.llm.greeting_configs.mode` (string) - Determines when the agent sends greeting messages to users joining the channel.

- `single_every`: Broadcasts a greeting every time a user joins the channel.
- `single_first`: Broadcasts a greeting only once to the first user who joins the channel.
No schema.
      - `properties.llm.greeting_configs.delay_ms` (integer) - The delay in milliseconds before the agent plays the greeting message after a user joins the channel.
No schema.
      - `properties.llm.greeting_configs.interruptable` (boolean) - - `true`: Follows the global `interruption` configuration.
- `false`: Uninterruptible. The greeting plays in its entirety. If the user speaks multiple times while the greeting plays, the system merges the speech segments after the greeting ends and sends them to the LLM for a single response.
No schema.
      - `properties.llm.greeting_configs.audio_download_timeout_ms` (integer) - The timeout in milliseconds for downloading the greeting audio file. Only takes effect when `greeting_audio_url` is configured. If the download times out, the system falls back to TTS synthesis using `greeting_message`.
No schema.
      - `properties.llm.greeting_configs.audio_pcm_sample_rate` (integer) - The sample rate in Hz of the greeting audio file when the format is PCM. Only takes effect when `greeting_audio_url` is configured and the audio format is PCM. Not required for `mp3` or `wav` files.
No schema.
    - `properties.llm.greeting_audio_url` (string) - The URL of a pre-recorded audio file to play as the agent's greeting. When configured, the system downloads and plays this recording instead of synthesizing the greeting via TTS.

Supported formats: `mp3`, `wav`, `pcm`.

- Only `http://` or `https://` URLs are supported. An empty string, non-URL string, or a URL exceeding `2048` bytes causes the request to return a `400` error.
- For `pcm` files, set `greeting_configs.audio_pcm_sample_rate` to specify the sample rate.
- The system resamples the imported audio to match `tts.params.sample_rate` before playback.

You must also configure `greeting_message` as a fallback when using `greeting_audio_url`; otherwise the request returns a `400` error. If the recording fails to download, decode, or is in an unsupported format, the system automatically falls back to TTS synthesis using `greeting_message`.
No schema.
    - `properties.llm.greeting_message` (string) - Agent greeting text. This field serves the following purposes:

- **Standalone greeting**: If provided without `greeting_audio_url`, the agent greets the first user who joins the channel using TTS synthesis.
- **Audio greeting fallback**: When `greeting_audio_url` is configured, this field is required as a fallback. If the audio file fails to download, decode, or is in an unsupported format, the agent falls back to TTS synthesis using this text.
- **Interrupted greeting context**: When `greeting_configs.interruptable` is `true` and the audio greeting is interrupted, the system uses this text to estimate the portion already played and injects it into short-term memory to maintain conversation context.
No schema.
    - `properties.llm.failure_message` (string) - Prompt for agent activation failure. If provided, it is returned through TTS when the custom LLM call fails.
No schema.
    - `properties.llm.vendor` (string) - LLM provider, supports the following settings:
- `openai`: [OpenAI](/en/ai/models/llm/openai)
- `azure`: [Azure OpenAI](/en/ai/models/llm/azure-openai)
- `xai`: [xAI Grok](/en/ai/models/llm/xai)
- `custom`: [Custom LLM](/en/ai/build/custom-model-integration/custom-llm). When you set this option, the agent includes the following fields, in addition to `role` and `content` when making requests to the custom LLM:
- `turn_id`: A unique identifier for each conversation turn. It starts from `0` and increments with each turn. One user-agent interaction corresponds to one `turn_id`.
- `timestamp`: The request timestamp, in milliseconds.
No schema.
    - `properties.llm.style` (string) - The request style for chat completion:
- `openai`: For OpenAI and OpenAI-compatible APIs
- `gemini`: For Google Gemini and Google Vertex API format
- `anthropic`: For Anthropic Claude API format
- `dify`: For Dify API format

For vendor-specific parameters, see the corresponding LLM provider page listed in `llm.vendor`.
No schema.
    - `properties.llm.template_variables` (object) - Template parameter configuration used to insert variables into the agent's `system_messages`, `greeting_message`, `failure_message`, and `parameters.silence_config.content` text. Uses key-value pairs, where the key is the variable name and the value is the variable's value. Template variables, combined with prompt customization and SIP outbound calling functionality, enable dynamic content injection, automating processes such as automatic hang-up, voicemail recognition, automatic message leaving, and call transfer.
To insert defined variables in the prompt text, use the syntax `{{variable_name}}`. The system automatically replaces each variable with the corresponding value defined in `template_variables`.
No schema.
    - `properties.llm.mcp_servers` (array) - MCP (Model Context Protocol) server configuration. By configuring MCP servers, agents can call tools provided by external services to implement advanced functionality.
      - `properties.llm.mcp_servers.items` (object)
        - `properties.llm.mcp_servers.items.name` (string, required) - A unique identifier for the MCP server. Maximum 48 characters. Accepts only English letters and numbers.
No schema.
        - `properties.llm.mcp_servers.items.endpoint` (string, required) - The endpoint address of the MCP server. The agent uses this to communicate with the MCP server.
No schema.
        - `properties.llm.mcp_servers.items.transport` (string) - Transport protocol type.
- `streamable_http`: Streaming HTTP protocol
No schema.
        - `properties.llm.mcp_servers.items.headers` (object) - HTTP header information to include when requesting the MCP server, such as authentication information.
No schema.
        - `properties.llm.mcp_servers.items.allowed_tools` (array) - A list of tools that the agent is allowed to invoke. The agent can only use tools on this list.

**Behavior:**
- **Empty or omitted**: All tools are enabled.
- **Empty array `[]`**: No tools are enabled.
- **`["*"]`**: All tools are enabled.
- **Specific tools `["aa", "bb", "cc"]`**: Only `aa`, `bb`, and `cc` are enabled.
- **Mix with wildcard `["aa", "bb", "*"]`**: All tools are enabled (wildcard takes precedence).
          - `properties.llm.mcp_servers.items.allowed_tools.items` (unknown)
No schema.
        - `properties.llm.mcp_servers.items.timeout_ms` (integer) - The MCP server request timeout in milliseconds. After timeout, the agent stops waiting for the MCP server's response and continues executing subsequent logic.
No schema.
    - `properties.llm.headers` (object) - Custom headers to include in requests to the LLM. Use this field to pass business-specific information such as custom fields or tenant identifiers.
No schema.
  - `properties.mllm` (object) - Multimodal Large Language Model (MLLM) configuration for real-time audio and text processing. `mllm` is an exclusive alternative to the standard `asr` + `llm` + `tts` pipeline."
    - `properties.mllm.enable` (boolean) - Enable Multimodal Large Language Model for voice-to-voice processing. Enabling MLLM automatically disables ASR, LLM, and TTS since the MLLM handles end-to-end voice processing directly. Replaces the deprecated `advanced_features.enable_mllm`.
No schema.
    - `properties.mllm.url` (string) - The MLLM WebSocket URL for real-time communication.
No schema.
    - `properties.mllm.api_key` (string, required) - The API key used for MLLM authentication.
No schema.
    - `properties.mllm.messages` (array) - Array of conversation items used for short-term memory management. Uses the same structure as `item.content` from the [OpenAI Realtime API](https://platform.openai.com/docs/api-reference/realtime-client-events/conversation/item/create).
      - `properties.mllm.messages.items` (object)
No schema.
    - `properties.mllm.params` (object) - Additional MLLM configuration parameters.
- **Modalities override**: The `modalities` setting in params is overridden by `input_modalities` and `output_modalities`.
- **Turn detection override**: The `turn_detection` setting in `params` is overridden by `mllm.turn_detection`.

For vendor-specific parameters, see the corresponding MLLM provider page listed in `mllm.vendor`.
No schema.
    - `properties.mllm.input_modalities` (array) - MLLM input modalities:
- `["audio"]`: Audio only
- `["audio", "text"]`: Audio plus text
      - `properties.mllm.input_modalities.items` (string)
No schema.
    - `properties.mllm.output_modalities` (array) - MLLM output modalities:
- `["text", "audio"]`: Text plus audio
      - `properties.mllm.output_modalities.items` (string)
No schema.
    - `properties.mllm.greeting_message` (string) - Agent greeting message. If provided, the first user in the channel is automatically greeted with this message upon joining.
No schema.
    - `properties.mllm.vendor` (string) - MLLM provider. Currently supports:
- `openai`: [OpenAI Realtime API](/en/ai/models/mllm/openai)
- `gemini`: [Google Gemini Live](/en/ai/models/mllm/gemini)
- `vertexai`: [Google Gemini Live (Vertex AI)](/en/ai/models/mllm/google-vertex-ai)
- `xai`: [xAI Grok](/en/ai/models/mllm/xai)
No schema.
    - `properties.mllm.turn_detection` (object) - Turn detection configuration for the MLLM module.
      - `properties.mllm.turn_detection.mode` (string) - - `agora_vad`: Agora VAD-based detection.
- `server_vad`: Vendor-side VAD-based detection. Supported by OpenAI Realtime API and Gemini Live.
- `semantic_vad`: Semantic-based detection. Supported by OpenAI Realtime API only.
No schema.
      - `properties.mllm.turn_detection.agora_vad_config` (object) - Configuration for Agora VAD-based turn detection. Applicable when `mode` is `agora_vad`.
        - `properties.mllm.turn_detection.agora_vad_config.interrupt_duration_ms` (integer) - Minimum duration of speech in milliseconds required to trigger an interruption.
No schema.
        - `properties.mllm.turn_detection.agora_vad_config.prefix_padding_ms` (integer) - Duration of audio in milliseconds to include before the detected speech start.
No schema.
        - `properties.mllm.turn_detection.agora_vad_config.silence_duration_ms` (integer) - Duration of silence in milliseconds required to determine end of speech.
No schema.
        - `properties.mllm.turn_detection.agora_vad_config.threshold` (number) - VAD sensitivity threshold. A higher value reduces false positives.
No schema.
      - `properties.mllm.turn_detection.server_vad_config` (object) - Configuration for vendor-side VAD-based turn detection. Applicable when `mode` is `server_vad`. Parameters are passed through to the vendor.
        - `properties.mllm.turn_detection.server_vad_config.prefix_padding_ms` (integer) - Duration of audio in milliseconds to include before the detected speech start.
No schema.
        - `properties.mllm.turn_detection.server_vad_config.silence_duration_ms` (integer) - Duration of silence in milliseconds required to determine end of speech.
No schema.
        - `properties.mllm.turn_detection.server_vad_config.threshold` (number) - VAD sensitivity threshold. Applicable to OpenAI Realtime API only.
No schema.
        - `properties.mllm.turn_detection.server_vad_config.idle_timeout_ms` (integer) - Idle timeout in milliseconds. Applicable to OpenAI Realtime API only.
No schema.
        - `properties.mllm.turn_detection.server_vad_config.start_of_speech_sensitivity` (string) - Sensitivity for start of speech detection. Applicable to Gemini Live only.
No schema.
        - `properties.mllm.turn_detection.server_vad_config.end_of_speech_sensitivity` (string) - Sensitivity for end of speech detection. Applicable to Gemini Live only.
No schema.
      - `properties.mllm.turn_detection.semantic_vad_config` (object) - Configuration for semantic-based turn detection. Applicable when `mode` is `semantic_vad`. Supported by OpenAI Realtime API only.
        - `properties.mllm.turn_detection.semantic_vad_config.eagerness` (string) - Controls how eagerly the model ends its turn.
No schema.
  - `properties.avatar` (object) - Avatar configuration.
    - `properties.avatar.enable` (boolean) - Whether to enable the avatar function for the agent. To enable, set to `true` and configure the `vendor` and `params` fields.
No schema.
    - `properties.avatar.vendor` (string) - Avatar vendor. Supports the following values:
- `akool`: [Akool](/en/ai/models/avatar/akool)
- `liveavatar`: [LiveAvatar](/en/ai/models/avatar/heygen)
- `anam`: [Anam](/en/ai/models/avatar/anam)
- `generic`: [Generic](/en/ai/models/avatar/generic)
No schema.
    - `properties.avatar.params` (object) - The configuration parameters for the selected avatar vendor. For vendor-specific parameters, see the corresponding avatar provider page listed in `avatar.vendor`.
No schema.
  - `properties.turn_detection` (object) - Conversation turn detection settings. Controls the logic for voice activity detection and conversation turn determination. The previous version of `turn_detection` is deprecated. Refer to [Deprecated parameters](#deprecated-parameters) for details. Agora recommends switching to the latest parameters.
    - `properties.turn_detection.mode` (string) - Conversation turn detection mode:
- `default`: Uses standard conversation turn detection configuration.
No schema.
    - `properties.turn_detection.type` (string) - Deprecated turn detection mechanism. `agora_vad` uses Agora VAD, `server_vad` lets the model detect speech start and end based on audio volume, and `semantic_vad` uses semantic estimation with VAD.
Compatible with both cascade (ASR/LLM/TTS) and MLLM modes.
No schema.
    - `properties.turn_detection.interrupt_mode` (string) - Deprecated interruption behavior when human voice interrupts the agent while it is speaking or thinking.
Sets the agent's behavior when human voice interrupts the agent while it is interacting (speaking or thinking).
No schema.
    - `properties.turn_detection.interrupt_duration_ms` (number) - The amount of time in milliseconds that the user's voice must exceed the VAD threshold before an interruption is triggered.
No schema.
    - `properties.turn_detection.interrupt_keywords` (array) - Keywords that trigger an interruption when `turn_detection.interrupt_mode` is set to `keyword`.
Specifies the list of keywords that trigger an interruption when the `turn_detection.interrupt_mode` is set to `"keyword"`.
      - `properties.turn_detection.interrupt_keywords.items` (string)
No schema.
    - `properties.turn_detection.prefix_padding_ms` (integer) - The extra forward padding time in milliseconds before processing starts.
No schema.
    - `properties.turn_detection.silence_duration_ms` (integer) - The duration of audio silence in milliseconds after which the agent assumes the user has stopped speaking.
No schema.
    - `properties.turn_detection.threshold` (number) - Voice activity detection sensitivity. The valid range is `(0.0, 1.0)`.
Identification sensitivity determines the level of sound in the audio signal that is considered voice activity.
No schema.
    - `properties.turn_detection.eagerness` (string) - The eagerness of the model to respond. Only available in `semantic_vad` mode when using OpenAI Realtime API.
No schema.
    - `properties.turn_detection.config` (object) - Detailed configuration for conversation turn detection.
      - `properties.turn_detection.config.speech_threshold` (number) - Voice activity detection sensitivity. Determines the sound level in the audio signal that is considered voice activity. Lower values make it easier for the agent to detect speech, and higher values ignore weak sounds.
No schema.
      - `properties.turn_detection.config.start_of_speech` (object) - Start of Speech (SoS) detection configuration. Determines when a user begins speaking.
        - `properties.turn_detection.config.start_of_speech.mode` (string, required) - Start of speech detection mode:
- `vad`: Based on VAD (Voice Activity Detection). Uses audio signal detection.
- `manual`: Manual SoS mode. Disables automatic start-of-speech detection. The client explicitly signals the start of user speech via RTM.
- `keywords`: Deprecated. Use [`interruption.mode = "keywords"`](#properties-interruption-mode) instead.
- `disabled`: Deprecated. Use [`interruption.enable = false`](#properties-interruption-enable) with [`interruption.disabled_config.strategy`](#properties-interruption-disabled-config-strategy) to configure the handling strategy.
No schema.
        - `properties.turn_detection.config.start_of_speech.{mode}_config` (object) - Start of speech detection configuration parameters. The structure and supported fields vary depending on the detection mode.
**Configuration examples:**
- `vad_config`
```json
"vad_config": {
"interrupt_duration_ms": 160,
"speaking_interrupt_duration_ms": 160,
"prefix_padding_ms": 800
}
```
- `keywords_config`
```json
"keywords_config": {
"interrupt_duration_ms": 160,
"prefix_padding_ms": 800,
"triggered_keywords": ["Are you there", "hello"]
}
```
- `disabled_config`
```json
"disabled_config": {
"strategy": "append"
}
```
          - `properties.turn_detection.config.start_of_speech.{mode}_config.interrupt_duration_ms` (integer) - The amount of time in milliseconds that the user's voice must exceed the VAD threshold before an interruption is triggered.
No schema.
          - `properties.turn_detection.config.start_of_speech.{mode}_config.speaking_interrupt_duration_ms` (integer) - Interruption duration in milliseconds while the agent is speaking.
No schema.
          - `properties.turn_detection.config.start_of_speech.{mode}_config.prefix_padding_ms` (integer) - The extra forward padding time in milliseconds before the processing system starts to process the speech input. This padding helps capture the beginning of speech.
No schema.
          - `properties.turn_detection.config.start_of_speech.{mode}_config.triggered_keywords` (array) - Specifies the list of keywords that trigger an interruption. When the agent detects any of these keywords in the user's speech, it immediately stops its current interaction and processes the new input.
            - `properties.turn_detection.config.start_of_speech.{mode}_config.triggered_keywords.items` (string)
No schema.
          - `properties.turn_detection.config.start_of_speech.{mode}_config.strategy` (string) - Voice processing strategy when the agent is interacting (speaking or thinking):
- `append`: Append mode. Human voice does not interrupt the agent. The agent processes the human voice input after the current interaction ends.
- `ignore`: Ignore mode. The agent ignores human voice input. If the agent receives human voice while speaking or thinking, the agent discards the input without storing it in context.
No schema.
      - `properties.turn_detection.config.end_of_speech` (object) - End of Speech (EoS) detection configuration. Determines when a user ends their speech.
        - `properties.turn_detection.config.end_of_speech.mode` (string) - End of speech detection mode. Possible values:
- `vad`: Based on VAD (Voice Activity Detection). Detects silence duration.
- `semantic`: Based on semantic triggering. Uses semantic understanding to determine when conversation ends.
- `manual`: Manual EoS mode. Disables automatic end-of-speech detection. The client explicitly signals the end of user speech via RTM.
No schema.
        - `properties.turn_detection.config.end_of_speech.{mode}_config` (object) - End of speech detection configuration parameters. The structure and supported fields vary depending on the detection mode.
**Configuration examples:**
- `vad_config`
```json
"vad_config": {
"silence_duration_ms": 640
}
```
- `semantic_config`
```json
"semantic_config": {
"silence_duration_ms": 320,
"max_wait_ms": 3000,
"pause_state_enabled": true
}
```
          - `properties.turn_detection.config.end_of_speech.{mode}_config.silence_duration_ms` (integer) - **Default**: `640` in `vad_config`, `320` in `semantic_config`
Silence duration threshold in milliseconds. The minimum silence duration at the end of a speech segment,  to ensure that a brief pause does not prematurely end the speech segment.
No schema.
          - `properties.turn_detection.config.end_of_speech.{mode}_config.max_wait_ms` (integer) - `-1` means forever.

Maximum wait time in milliseconds. The maximum time to wait for semantic determination. After timeout, the conversation end is determined based on the current state.
No schema.
          - `properties.turn_detection.config.end_of_speech.{mode}_config.pause_state_enabled` (boolean) - Whether to detect user intent to pause the conversation:
- `true`: The agent uses semantic understanding to determine if the user intends to pause the conversation. For example, when the user's input ends with phrases such as "hold on" or "just a moment", the agent waits for further input rather than treating the utterance as complete and sending it to the LLM.
- `false`: The agent does not detect intent to pause the conversation.
No schema.
  - `properties.interruption` (object) - Interruption control configuration. Provides unified management of the agent's behavior when interrupted by the user.
    - `properties.interruption.enable` (boolean) - Whether to enable agent interruption:
- `true`: Enable interruption.
- `false`: Disable interruption. When disabled, the agent cannot be interrupted mid-response.
No schema.
    - `properties.interruption.mode` (string) - The interruption trigger mode:
- `start_of_speech`: Trigger interruption when the user starts speaking.
- `keywords`: Trigger interruption when the user speaks a specified keyword. Configure the trigger keywords in `keywords_config`.
No schema.
    - `properties.interruption.keywords_config` (object) - Configuration for keyword-based interruption triggering. Applicable only when `mode` is `keywords`.
      - `properties.interruption.keywords_config.trigger_keywords` (array) - The list of keywords that trigger an interruption. A maximum of 128 keywords is supported.
        - `properties.interruption.keywords_config.trigger_keywords.items` (string)
No schema.
    - `properties.interruption.disabled_config` (object) - Configuration for agent behavior when interruption is disabled. Applicable only when `interruption.enable` is `false`.
      - `properties.interruption.disabled_config.strategy` (string) - The processing strategy when interruption is disabled:
- `append`: User speech does not interrupt the agent. The agent processes the user's input after the current interaction ends.
- `ignore`: The agent ignores user speech. If the agent receives user speech while speaking or thinking, it discards the input without storing it in context.
No schema.
  - `properties.sal` (object) - Selective Attention Locking (SAL) configuration. **(Beta)**
    - `properties.sal.sal_mode` (string) - Selective attention lock mode. Supports the following options:

- `locking`: Speaker Lock Mode. The agent locks onto the speaker, blocking 95% of ambient human voices and noise. You can enable this mode in two ways:

- Seamless mode: When a user speaks loudly and clearly at the beginning of a conversation, the intelligent agent automatically recognizes the user as the speaker.
- Personalized mode: When creating an agent, a speaker's voiceprint URL is pre-registered through the `sample_urls` field. The agent then locates the speaker based on the pre-registered voiceprint.

- `recognition`: Voiceprint recognition mode. You can pre-register only one voiceprint URL using the `sample_urls` field. The agent identifies different speakers and suppresses other background voices and environmental noise. The target speaker is identified through the `vpids` field in the `metadata` field and sent to the LLM. Set `llm.vendor` to "custom" and refer to [Custom LLM](/en/ai/build/custom-model-integration/custom-llm) for instructions on how to make the LLM process speaker information.
No schema.
    - `properties.sal.sample_urls` (object) - The registered voiceprint URL as a key-value pair, where the key is the voiceprint name and the value is the download URL for the speaker's voiceprint. Only one voiceprint URL is supported.
Example:
```json
{
"speaker1": "https://example.com/speaker1.pcm"
}
```
No schema.
  - `properties.labels` (object) - Custom labels in key-value pair format, where the key is the label name and the value is the label value. Enables agents to carry custom business information.

These labels are bound to the agent and returned in the `payload` field of all message notification callbacks from the conversational AI engine. Use them to implement custom business logic, such as tagging activity IDs, customer groups, and business scenarios.
No schema.
  - `properties.rtc` (object) - RTC media encryption configuration.
    - `properties.rtc.encryption_key` (string) - The encryption key for RTC media content. The key has no length limit. Agora recommends using a 32-byte key. If no encryption key is set or if the key is empty, built-in encryption is not used.
No schema.
    - `properties.rtc.encryption_salt` (string) - The salt value used for encryption. This is a Base64-encoded string that is 32 bytes long after decoding. This parameter only takes effect when `encryption_mode` is set to `7` (`AES_128_GCM2`) or `8` (`AES_256_GCM2`). Ensure that the salt parameter is not empty for these encryption modes.
No schema.
    - `properties.rtc.encryption_mode` (integer) - The built-in encryption mode.
- `1`: `AES_128_XTS` - 128-bit AES encryption, XTS mode.
- `2`: `AES_128_ECB` - 128-bit AES encryption, ECB mode.
- `3`: `AES_256_XTS` - 256-bit AES encryption, XTS mode.
- `4`: `SM4_128_ECB` - 128-bit SM4 encryption, ECB mode.
- `5`: `AES_128_GCM` - 128-bit AES encryption, GCM mode.
- `6`: `AES_256_GCM` - 256-bit AES encryption, GCM mode.
- `7`: `AES_128_GCM2` - 128-bit AES encryption, GCM mode. Requires setting `encryption_salt`.
- `8`: `AES_256_GCM2` - 256-bit AES encryption, GCM mode. Requires setting `encryption_salt`.

Agora recommends using either `7` (`AES_128_GCM2`) or `8` (`AES_256_GCM2`) mode. Both modes support cryptographic salts to enhance security.
No schema.
  - `properties.filler_words` (object) - Filler word configuration. Plays filler words while waiting for LLM responses to reduce user anxiety and improve conversation flow.

Filler word playback follows these rules:
- **Playback order**: When multiple filler words or LLM responses are waiting to be played, they are played in the order they arrive.
- **Interruption control**: Inherits the interruption mode setting from the [`interruption`](#properties-interruption) field.
    - `properties.filler_words.enable` (boolean) - Whether to enable filler words:
- `true`: Enable filler words.
- `false`: Disable filler words.
No schema.
    - `properties.filler_words.trigger` (object) - Filler word trigger configuration. Defines when to trigger filler word playback.
      - `properties.filler_words.trigger.mode` (string) - Filler word trigger mode:
- `fixed_time`: Fixed time trigger. Triggers filler word playback when LLM response wait time exceeds the threshold.
No schema.
      - `properties.filler_words.trigger.{mode}_config` (object) - Filler word trigger configuration parameters. The parameter name and structure vary depending on the trigger mode.
**Configuration example:**
```json
"fixed_time_config": {
"response_wait_ms": 1500
}
```
        - `properties.filler_words.trigger.{mode}_config.response_wait_ms` (integer) - LLM response wait threshold in milliseconds. Triggers filler word playback when the LLM waits this duration without generating a response, such as when waiting for RAG retrieval or tool call results.
No schema.
    - `properties.filler_words.content` (object) - Filler word content configuration. Defines the source and selection rules for filler words.
      - `properties.filler_words.content.mode` (string) - Filler word content mode:
- `static`: Static filler words. Uses a predefined list of filler words.
No schema.
      - `properties.filler_words.content.{mode}_config` (object) - Filler word content configuration parameters. The parameter name and structure vary depending on the content mode.
        - `properties.filler_words.content.{mode}_config.phrases` (array, required) - List of filler word phrases.

**Limits:**
- Maximum 100 filler words.
- Each filler word must not exceed 50 English words.
          - `properties.filler_words.content.{mode}_config.phrases.items` (string)
No schema.
        - `properties.filler_words.content.{mode}_config.selection_rule` (string) - Filler word selection rule:
- `shuffle`: Random shuffle. Already-used filler words are not repeated until all filler words have been used once. After all filler words are played, they are reshuffled randomly and a new round begins.
- `round_robin`: Round-robin. Selects and plays filler words sequentially from the list. After all filler words are played once, a new cycle begins.
No schema.
  - `properties.parameters` (object) - Agent configuration parameters.
    - `properties.parameters.silence_config` (object) - Settings related to agent silence behavior.
      - `properties.parameters.silence_config.timeout_ms` (integer) - Specifies the maximum duration (in milliseconds) that the agent can remain silent.
After the agent is successfully created and the user joins the channel, any time during which the agent is not listening, thinking, or speaking is considered silent time. When the silent time reaches the specified value, the agent broadcasts a silent reminder message. This feature is useful for prompting users when they become inactive.
- `0`: Disables the silent reminder feature.
- `(0, 60000]`: Enables the silent reminder. You must also set `content`; otherwise, the configuration is invalid.
No schema.
      - `properties.parameters.silence_config.action` (string) - Specifies how the agent behaves when the silent timeout is reached. Valid values:
- `speak`: Uses the TTS module to announce the silent prompt (`content`).
- `think`: Appends the silent prompt (`content`) to the context and passes it to the LLM.
No schema.
      - `properties.parameters.silence_config.content` (string) - Specifies the silent prompt message. The message use depends on the value of `action` parameter.
No schema.
    - `properties.parameters.farewell_config` (object) - Graceful hang-up settings for the agent.
      - `properties.parameters.farewell_config.graceful_enabled` (boolean) - Enable graceful leave:
* `true`: Enabled. When enabled, calling the POST method to stop the agent ensures that the agent is in an `IDLE` state before leaving the channel.
* `false`: Disabled.
No schema.
      - `properties.parameters.farewell_config.graceful_timeout_seconds` (integer) - Graceful exit timeout (in seconds). Represents the maximum time to wait for the agent to enter an `IDLE` state before exiting the channel. After this time, the agent will exit the channel immediately, even if it is not in an idle state. This field is only effective when `graceful_enabled` is `true`.
No schema.
    - `properties.parameters.data_channel` (string) - Agent data transmission channel:
- `rtm`: Use RTM transmission. This configuration takes effect only when `advanced_features.enable_rtm` is `true`.
- `datastream`: Use RTC data stream transport.
No schema.
    - `properties.parameters.enable_metrics` (boolean) - Whether to receive agent performance data:
- `true`: Receive agent performance data.
- `false`: Do not receive agent performance data.

This setting only takes effect when `advanced_features.enable_rtm` is `true`. See [Listen to agent events](/en/ai/build/handle-runtime-events/webhooks) to learn how to use client components to receive agent performance data.
No schema.
    - `properties.parameters.enable_error_message` (boolean) - Whether to receive agent error events:
- `true`: Receive agent error events.
- `false`: Do not receive agent error events.

This setting only takes effect when `advanced_features.enable_rtm` is `true`. See [Listen to agent events](/en/ai/build/handle-runtime-events/webhooks) to learn how to use client components to receive agent error events.
No schema.
    - `properties.parameters.audio_scenario` (string) - The audio scenario for the RTC channel.

- `default`: Maps to `aiserver`.
- `chorus`: Real-time chorus scenario, where users have good network conditions and require ultra-low latency.
- `aiserver`: Optimized for interactions between the user and the conversational AI agent in terms of latency and network resilience.
No schema.
    - `properties.parameters.opt_out` (boolean) - Whether to disable data retention for the current session.
- `false`: (Default) Data retention is enabled.
- `true`: Data retention is disabled. When disabled, session interaction text and audio are not retained, which means troubleshooting, performance review, and agent optimization based on session history will not be available.
No schema.

## Responses

### 200

The request was successful. The response body contains the result of the request.

- `agent_id` (string) - Unique id of the agent instance
No schema.
- `create_ts` (integer) - Timestamp of when the agent was created
No schema.
- `status` (string) - Current status.

- `IDLE` (0): Agent is idle.

- `STARTING` (1): The agent is being started.

- `RUNNING` (2): The agent is running.

- `STOPPING` (3): The agent is stopping.

- `STOPPED` (4): The agent has exited.

- `FAILED` (6): The agent failed to execute.
No schema.
### default

The request failed. The response body includes the error details.

- `detail` (string) - Detailed error information.
No schema.
- `reason` (string) - The reason for the failure.
No schema.