# Use managed mode (/en/ai/build/custom-model-integration/managed-mode)

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

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 [#prerequisites]

Before you begin, ensure that you have:

* An Agora account with [Conversational AI Engine enabled](/en/ai/reference/enable-conversational-ai).
* 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](/en/api-reference/api-ref/conversational-ai/authentication#basic-http-authentication).
  * An RTC token generated from your app ID and app certificate, to use [token authentication](/en/api-reference/api-ref/conversational-ai/authentication#token-authentication).

## Understand the tech [#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 [#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.

<Tabs defaultValue="python" groupId="ai-sdk-language">
  <TabsList>
    <TabsTrigger value="python">
      Python SDK
    </TabsTrigger>

    <TabsTrigger value="typescript">
      TypeScript SDK
    </TabsTrigger>

    <TabsTrigger value="go">
      Go SDK
    </TabsTrigger>

    <TabsTrigger value="rest-api">
      REST API
    </TabsTrigger>
  </TabsList>

  <TabsContent value="python">
    ```python
    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}')
    ```
  </TabsContent>

  <TabsContent value="typescript">
    ```typescript
    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);
    ```
  </TabsContent>

  <TabsContent value="go">
    ```go
    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)
    }
    ```
  </TabsContent>

  <TabsContent value="rest-api">
    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.

    ```bash
    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.
  </TabsContent>
</Tabs>

## Supported vendors [#supported-vendors]

The following vendors and models are available in managed mode.

### ASR [#asr]

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

### LLM [#llm]

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

### TTS [#tts]

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

## Reference [#reference]

For the full list of request parameters, see [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join).

For provider-specific configuration options available within [`asr`](/en/ai/models/asr/deepgram), [`llm`](/en/ai/models/llm/openai), and [`tts`](/en/ai/models/tts/minimax) fields, see the relevant provider page.