# OpenAI (/en/ai/platform/models/llm/openai)

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

> Documentation: Conversational AI.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-guides-v2.txt).


OpenAI provides frontier models ranging from lightweight to high-capability.

## Sample configuration

The following example shows how to configure OpenAI as the agent's LLM when you create or update an agent. For a complete example, see [Create an agent and start a session](/en/ai/platform/get-started/start-stop-agent#create-an-agent).

OpenAI supports managed mode and BYOK. In managed mode, Agora provides access to OpenAI, and you don't need an OpenAI account. For BYOK, store your OpenAI API key in a secret set, and refer to it from the agent. For details, see [Use managed mode](/en/ai/platform/build/managed-mode) and [Use your own provider keys](/en/ai/platform/build/use-your-own-keys).

**Python SDK**

```python
from agora_agent import Agent, OpenAI, secret_ref

# client is your configured Agora client
agent = (
    Agent(client=client)
    .with_stt(...)  # configure your ASR vendor
    .with_llm(
        OpenAI(
            api_key=secret_ref("support_prod", "openai"),  # omit to use managed mode
            base_url="https://api.openai.com/v1/chat/completions",  # omit to use managed mode
            model="gpt-4.1-mini",
            max_history=32,
            failure_message="Please hold on a second.",
            system_messages=[
                {"role": "system", "content": "You are a friendly support agent for Acme. Keep your answers short."}
            ],
        )
    )
    .with_tts(...)  # configure your TTS vendor
)
```

**TypeScript SDK**

```ts
import { Agent, OpenAI, secretRef } from 'agora-agents';

// client is your configured Agora client
const agent = new Agent({ client })
  .withStt(/* configure your ASR vendor */)
  .withLlm(
    new OpenAI({
      apiKey: secretRef('support_prod', 'openai'), // omit to use managed mode
      url: 'https://api.openai.com/v1/chat/completions', // omit to use managed mode
      model: 'gpt-4.1-mini',
      maxHistory: 32,
      failureMessage: 'Please hold on a second.',
      systemMessages: [
        { role: 'system', content: 'You are a friendly support agent for Acme. Keep your answers short.' },
      ],
    }),
  )
  .withTts(/* configure your TTS vendor */);
```

**Go SDK**

```go
// client is your configured Agora client
maxHistory := 32
agent := agentkit.NewAgent(client).
	WithStt( /* configure your ASR vendor */ ).
	WithLlm(vendors.NewOpenAI(vendors.OpenAIOptions{
		APIKey:         agentkit.SecretRef("support_prod", "openai"), // omit to use managed mode
		BaseURL:        "https://api.openai.com/v1/chat/completions", // omit to use managed mode
		Model:          "gpt-4.1-mini",
		MaxHistory:     &maxHistory,
		FailureMessage: "Please hold on a second.",
		SystemMessages: []map[string]interface{}{
			{"role": "system", "content": "You are a friendly support agent for Acme. Keep your answers short."},
		},
	})).
	WithTts( /* configure your TTS vendor */ )
```

**REST API**

- **Managed mode**

  Set `credential.mode` to `managed` in the `llm` block. Agora provides access to OpenAI, and you don't need an OpenAI account.

  ```json
  "llm": {
    "credential": { "mode": "managed" },
    "vendor": "openai",
    "style": "openai",
    "model": "gpt-4.1-mini",
    "max_history": 32,
    "failure_message": "Please hold on a second."
  }
  ```


- **BYOK**

  Set `credential.mode` to `byok` and `credential.fields.api_key` to a reference to your OpenAI API key in a secret set. In the following example, the key is stored as `openai` in the `support_prod` set:

  ```json
  "llm": {
    "credential": {
      "mode": "byok",
      "fields": {
        "api_key": "$secrets.support_prod.openai"
      }
    },
    "vendor": "openai",
    "style": "openai",
    "model": "gpt-4o-mini",
    "url": "https://api.openai.com/v1/chat/completions",
    "max_history": 32,
    "failure_message": "Please hold on a second."
  }
  ```

Set the system prompt and the greeting with the agent's `instructions` and `greeting`, not in the `llm` block.

## Key parameters

The `llm` block takes the following fields. In the SDKs, the LLM class sets them from its options. In managed mode, omit the API key, the endpoint URL, and the vendor. Managed mode supports the models listed for `model` in [Key parameters](#key-parameters).

**llm**

**`vendor` (string) required**

Set to `openai`.

**`credential` (object) required**

How the agent authenticates with OpenAI. Set `mode` to `managed`, or to `byok` with `fields.api_key` set to a `$secrets.<set>.<key>` reference to your OpenAI API key. Create or manage your API key from [OpenAI organization settings](https://platform.openai.com/settings/organization/api-keys).

**`style` (string) optional**

Set to `openai`.

**`model` (string) required**

Refer to [OpenAI models](https://platform.openai.com/docs/models) for available models. For managed mode, use `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5-nano`, `gpt-5-mini`, or `gpt-5.6-luna`.

**`url` (string) optional**

The chat completions endpoint. Not needed in managed mode.

For complete `llm` block options, see [Create an agent](/en/api-reference/api-ref/conversational-ai/platform/create-agent). For OpenAI-specific options and model capabilities, see the [OpenAI API documentation](https://platform.openai.com/docs/api-reference/chat).