Use managed mode

Managed mode lets you use supported ASR, LLM, and TTS providers with Agora-managed credentials, without supplying your own API keys. You can use managed mode for any or all of the three provider categories.

Prerequisites

Before you begin, ensure that you have:

An Agora account with Conversational AI Engine enabled.
A valid Agora app ID and app certificate.
For REST API only, one of the following to authenticate 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

In managed mode, Agora supplies the credentials and endpoint configuration for the selected provider, so you do not need to provide your own API keys. You still need to identify the provider and model you want to use. You can also supply additional settings such as a system prompt, a specific voice ID, or keyword hints.

You can enable managed mode independently for any combination of ASR, LLM, and TTS. To enable it for a category, set credential_mode to "managed" within its asr, llm, or tts block. Categories that omit credential_mode default to "byok", which requires you to bring your own provider credentials.

Start an agent using managed mode

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.

from agora_agent import Agent, Agora, Area, DeepgramSTT, OpenAI, MiniMaxTTS

client = Agora(
    area=Area.US,
    app_id='your-app-id',
    app_certificate='your-app-certificate',
)

# Omit API keys to use Agora-managed models for ASR, LLM, and TTS.
agent = (
    Agent(name='my-managed-agent')
    .with_stt(DeepgramSTT(model='nova-3', language='en-US'))
    .with_llm(OpenAI(
        model='gpt-4o-mini',
        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,
    ))
    .with_tts(MiniMaxTTS(
        model='speech_2_6_turbo',
        voice_id='English_captivating_female1',
    ))
)

session = agent.create_session(
    client,
    channel='my-channel',
    agent_uid='1001',
    remote_uids=['1002'],
    idle_timeout=120,
)

agent_id = session.start()
print(f'Agent started: {agent_id}')

import { Agent, AgoraClient, Area, DeepgramSTT, OpenAI, MiniMaxTTS } from 'agora-agents';

const client = new AgoraClient({
  area: Area.US,
  appId: 'your-app-id',
  appCertificate: 'your-app-certificate',
});

// Omit API keys to use Agora-managed models for ASR, LLM, and TTS.
const agent = new Agent({ name: 'my-managed-agent' })
  .withStt(new DeepgramSTT({ model: 'nova-3', language: 'en-US' }))
  .withLlm(new OpenAI({
    model: 'gpt-4o-mini',
    systemMessages: [{ role: 'system', content: 'You are a helpful assistant.' }],
    greetingMessage: 'Hello! How can I help you today?',
    failureMessage: 'Sorry, I could not process your request.',
    maxHistory: 32,
  }))
  .withTts(new MiniMaxTTS({
    model: 'speech_2_6_turbo',
    voiceId: 'English_captivating_female1',
  }));

const session = agent.createSession(client, {
  channel: 'my-channel',
  agentUid: '1001',
  remoteUids: ['1002'],
  idleTimeout: 120,
});

const agentId = await session.start();
console.log('Agent started:', agentId);

package main

import (
    "context"
    "fmt"
    "log"

    Agora "github.com/AgoraIO/agora-agents-go/v2"
    "github.com/AgoraIO/agora-agents-go/v2/agentkit"
    "github.com/AgoraIO/agora-agents-go/v2/agentkit/vendors"
    "github.com/AgoraIO/agora-agents-go/v2/option"
)

func main() {
    ctx := context.Background()

    client := agentkit.NewAgoraClient(agentkit.AgoraClientOptions{
        Area:           option.AreaUS,
        AppID:          "your-app-id",
        AppCertificate: "your-app-certificate",
    })

    // Omit API keys to use Agora-managed models for ASR, LLM, and TTS.
    agent := agentkit.NewAgent(
        agentkit.WithName("my-managed-agent"),
    ).WithStt(
        vendors.NewDeepgramSTT(vendors.DeepgramSTTOptions{
            Model:    "nova-3",
            Language: "en-US",
        }),
    ).WithLlm(
        vendors.NewOpenAI(vendors.OpenAIOptions{
            Model: "gpt-4o-mini",
            SystemMessages: []map[string]interface{}{
                {"role": "system", "content": "You are a helpful assistant."},
            },
            GreetingMessage: "Hello! How can I help you today?",
            FailureMessage:  "Sorry, I could not process your request.",
            MaxHistory:      Agora.Int(32),
        }),
    ).WithTts(
        vendors.NewMiniMaxTTS(vendors.MiniMaxTTSOptions{
            Model:   "speech_2_6_turbo",
            VoiceID: "English_captivating_female1",
        }),
    )

    session := agent.CreateSession(client, agentkit.CreateSessionOptions{
        Channel:     "my-channel",
        AgentUID:    "1001",
        RemoteUIDs:  []string{"1002"},
        IdleTimeout: Agora.Int(120),
    })

    agentID, err := session.Start(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Agent started:", agentID)
}

Set credential_mode to "managed" inside each provider block and include the required diagnostic parameters. You can use managed mode for any or all provider categories independently.

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-managed-agent",
    "properties": {
      "channel": "my-channel",
      "token": "<your_rtc_token>",
      "agent_rtc_uid": "1001",
      "remote_rtc_uids": ["1002"],
      "idle_timeout": 120,
      "asr": {
        "credential_mode": "managed",
        "vendor": "deepgram",
        "params": {
          "url": "wss://api.deepgram.com/v1/listen",
          "model": "nova-3",
          "language": "en-US",
          "keyterm": "agora"
        }
      },
      "llm": {
        "credential_mode": "managed",
        "vendor": "openai",
        "style": "openai",
        "url": "https://api.openai.com/v1/chat/completions",
        "params": {
          "model": "gpt-4.1-mini"
        },
        "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": {
        "credential_mode": "managed",
        "vendor": "minimax",
        "params": {
          "url": "wss://api.minimax.io/ws/v1/t2a_v2",
          "model": "speech-2.6-turbo",
          "voice_setting": {
            "voice_id": "English_captivating_female1"
          }
        }
      }
    }
  }'

In this example:

credential_mode: "managed" is set on each provider block. Agora supplies the credentials for each category.
The asr block uses Deepgram Nova 3 with a keyword hint.
The llm block uses OpenAI GPT-4.1 Mini with a system prompt, greeting, and history length.
The tts block uses MiniMax Speech 2.6 Turbo with a voice selection override.

Supported vendors

The following vendors and models are available in managed mode.

ASR

Vendor	Models
Deepgram	`nova-2`, `nova-3`

LLM

Vendor	Models
OpenAI	`gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5-nano`, `gpt-5-mini`

TTS

Vendor	Models
MiniMax	`speech-2.6-turbo`, `speech-2.8-turbo`
OpenAI	`tts-1`

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, see the relevant provider page.