Use presets

Presets are predefined configurations managed by Agora that let you use supported third-party AI providers without supplying your own API keys. You can specify a preset for any or all of the three provider categories: ASR, LLM, and TTS. Pass them together as a comma-separated string in the preset field of the Start a conversational AI agent request body.

Prerequisites

Before you begin, make sure you have:

An Agora account with Conversational AI Engine enabled
A valid Agora app ID
One of the following to authenticate REST API requests:
- A customer ID and customer secret, to use Basic HTTP authentication
- An RTC token generated from your app ID and app certificate, to use token authentication

Understand the tech

The preset field accepts a comma-separated string of preset identifiers. Each identifier maps to one provider category, so you can specify presets from different categories in the same call. When a preset is active for a category, you do not need to supply the provider's endpoint URL, API key, or model name. You can still use the corresponding asr, llm, and tts fields to supply additional settings, such as a system prompt or a specific voice ID.

The following presets are available:

Category	Available presets
ASR	`deepgram_nova_2` `deepgram_nova_3`
LLM	`openai_gpt_4o_mini` `openai_gpt_4_1_mini` `openai_gpt_5_nano` `openai_gpt_5_mini`
TTS	`minimax_speech_2_6_turbo` `minimax_speech_2_8_turbo` `openai_tts_1`

You can specify one preset per category. If you specify a preset for a category, any API key or endpoint URL fields for that category are ignored.

Combine presets for all three categories

The following example starts an agent using Deepgram for ASR, OpenAI for LLM, and MiniMax for TTS, with no BYOK credentials required for any provider.

curl
Python
Node.js

curl --request POST \
  --url https://api.agora.io/api/conversational-ai-agent/v2/projects/<your_app_id>/join \
  --header 'Authorization: agora token=<your_agora_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "my-preset-agent",
    "preset": "deepgram_nova_3,openai_gpt_5_mini,minimax_speech_2_6_turbo",
    "properties": {
      "channel": "my-channel",
      "token": "<your_rtc_token>",
      "agent_rtc_uid": "1001",
      "remote_rtc_uids": ["1002"],
      "idle_timeout": 120,
      "llm": {
        "system_messages": [
          {
            "role": "system",
            "content": "You are a helpful assistant."
          }
        ],
        "greeting_message": "Hello! How can I help you today?",
        "failure_message": "Sorry, I could not process your request.",
        "max_history": 32
      },
      "tts": {
        "params": {
          "voice_setting": {
            "voice_id": "English_captivating_female1"
          }
        }
      },
      "asr": {
        "params": {
          "language": "en",
          "keyterm": "agora"
        }
      }
    }
  }'

import requests
app_id = '<your_app_id>'
token = '<your_agora_token>'
url = f'https://api.agora.io/api/conversational-ai-agent/v2/projects/{app_id}/join'
headers = {
    'Authorization': f'agora token={token}',
    'Content-Type': 'application/json'
}
payload = {
    'name': 'my-preset-agent',
    'preset': 'deepgram_nova_3,openai_gpt_5_mini,minimax_speech_2_6_turbo',
    'properties': {
        'channel': 'my-channel',
        'token': token,
        'agent_rtc_uid': '1001',
        'remote_rtc_uids': ['1002'],
        'idle_timeout': 120,
        'llm': {
            'system_messages': [
                {
                    'role': 'system',
                    'content': 'You are a helpful assistant.'
                }
            ],
            'greeting_message': 'Hello! How can I help you today?',
            'failure_message': 'Sorry, I could not process your request.',
            'max_history': 32
        },
        'tts': {
            'params': {
                'voice_setting': {
                    'voice_id': 'English_captivating_female1'
                }
            }
        },
        'asr': {
            'params': {
                'language': 'en',
                'keyterm': 'agora'
            }
        }
    }
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())

const appId = '<your_app_id>';
const token = '<your_agora_token>';
const url = `https://api.agora.io/api/conversational-ai-agent/v2/projects/${appId}/join`;
const payload = {
  name: 'my-preset-agent',
  preset: 'deepgram_nova_3,openai_gpt_5_mini,minimax_speech_2_6_turbo',
  properties: {
    channel: 'my-channel',
    token: token,
    agent_rtc_uid: '1001',
    remote_rtc_uids: ['1002'],
    idle_timeout: 120,
    llm: {
      system_messages: [
        {
          role: 'system',
          content: 'You are a helpful assistant.'
        }
      ],
      greeting_message: 'Hello! How can I help you today?',
      failure_message: 'Sorry, I could not process your request.',
      max_history: 32
    },
    tts: {
      params: {
        voice_setting: {
          voice_id: 'English_captivating_female1'
        }
      }
    },
    asr: {
      params: {
        language: 'en',
        keyterm: 'agora'
      }
    }
  }
};
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': `agora token=${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});
const data = await response.json();
console.log(response.status);
console.log(data);

In this example:

The preset field configures Deepgram Nova 3 for ASR, GPT-5 Mini for LLM, and MiniMax Speech 2.6 Turbo for TTS.
The llm field sets the system prompt, greeting, and history length without specifying an endpoint or API key, because those are provided by the preset.
The tts field overrides the default voice selection for MiniMax.
The asr field passes a keyword hint to Deepgram.

info

Presets are independent: you can use one, two, or all three categories in the same request. Categories without a preset require you to supply your own provider credentials.

Reference

For the full list of request parameters, see Start a conversational AI agent.

For provider-specific configuration options available within asr, llm, and tts fields when using presets, see the relevant provider page.

Prerequisites​

Understand the tech​

Combine presets for all three categories​

Reference​

Prerequisites

Understand the tech

Combine presets for all three categories

Reference