# Model Selection

> Choose and configure models for your Built-in Agent.

The Built-in Agent uses the [Vercel AI SDK](https://sdk.vercel.ai), so you can use
built-in model strings or pass any custom AI SDK model.

## Supported Models [#supported-models]

Specify a model using the `"provider:model"` format. `"provider/model"` also works.

The tables list the models these docs use. The quickstart uses `openai:gpt-6-luna`.
The Built-in Agent sends the model id to the provider unchanged, so other model ids
from the same provider also work.

### OpenAI [#openai]

| Model        | Specifier             |
| ------------ | --------------------- |
| GPT-6 Luna | `openai:gpt-6-luna` |

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
});
```

### Anthropic [#anthropic]

| Model             | Specifier                     |
| ----------------- | ----------------------------- |
| Claude Opus 4.8   | `anthropic:claude-opus-4-8`   |
| Claude Sonnet 4.6 | `anthropic:claude-sonnet-4-6` |
| Claude Haiku 4.5  | `anthropic:claude-haiku-4-5`  |
| Claude Sonnet 4.5 | `anthropic:claude-sonnet-4-5` |

```typescript
const agent = new BuiltInAgent({
  model: "anthropic:claude-sonnet-4-6",
});
```

### Google [#google]

| Model                 | Specifier                      |
| --------------------- | ------------------------------ |
| Gemini 3.8 Flash      | `google:gemini-3.8-flash`      |
| Gemini 3.5 Flash      | `google:gemini-3.5-flash`      |
| Gemini 3.5 Flash Lite | `google:gemini-3.5-flash-lite` |

```typescript
const agent = new BuiltInAgent({
  model: "google:gemini-3.8-flash",
});
```

Use `gemini-3.5-flash-lite` for lower cost and latency. Google does not give
new API keys access to the Gemini 2.5 models. A key that used them before can
still call them, but a new key gets a 404. See Google's
[model list](https://ai.google.dev/gemini-api/docs/models).

### MiniMax [#minimax]

| Model        | Specifier              |
| ------------ | ---------------------- |
| MiniMax M3   | `minimax:MiniMax-M3`   |
| MiniMax M2.7 | `minimax:MiniMax-M2.7` |

```typescript
const agent = new BuiltInAgent({
  model: "minimax:MiniMax-M3",
});
```

## Environment Variables [#environment-variables]

Set the API key for your chosen provider:

```bash
# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Google
GOOGLE_API_KEY=...

# MiniMax
MINIMAX_API_KEY=...

# Optional: use the China endpoint
MINIMAX_BASE_URL=https://api.minimaxi.com/v1
```

### OpenAI-compatible endpoints [#openai-compatible-endpoints]

To send `openai:` model strings to another OpenAI-compatible endpoint, set
`OPENAI_BASE_URL`:

```bash
OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_API_KEY=gsk_...
```

The Built-in Agent picks the OpenAI API from that host:

- OpenAI (`api.openai.com`, `*.api.openai.com`) and Azure OpenAI hosts use the
  Responses API.
- Any other host uses the Chat Completions API, because most OpenAI-compatible
  servers serve only `/chat/completions`. The runtime logs this on the first run.

To choose the API yourself, set `COPILOTKIT_OPENAI_API` to `responses` or
`chat`. For example, a proxy in front of OpenAI (such as LiteLLM or Portkey)
needs `responses` to keep Responses-only features, such as reasoning summaries:

```bash
OPENAI_BASE_URL=https://my-gateway.example.com/v1
COPILOTKIT_OPENAI_API=responses
```

Alternatively, pass the API key directly in your configuration:

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  apiKey: process.env.MY_OPENAI_KEY, // [!code highlight]
});
```

## Custom Models (AI SDK) [#custom-models-ai-sdk]

To use a provider that model strings do not cover, or to configure the provider yourself (for example, a custom base URL), pass any Vercel AI SDK `LanguageModel` instance directly.
First, install the provider package from its `ai-v6` release line:

```npm
npm install @ai-sdk/openai@ai-v6
```

<Callout type="warn" title="Install the ai-v6 version of each @ai-sdk provider">
  The Built-in Agent runs on AI SDK 6 (`ai@6`), which needs `@ai-sdk/*` provider
  packages from the 3.x line. Add `@ai-v6` to every provider you install, for example
  `npm install @ai-sdk/azure@ai-v6`.
</Callout>

```typescript
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { createOpenAI } from "@ai-sdk/openai"; // [!code highlight]

const openai = createOpenAI({
  // [!code highlight]
  apiKey: process.env.OPENAI_API_KEY, // [!code highlight]
}); // [!code highlight]

const agent = new BuiltInAgent({
  model: openai("my-fine-tuned-model"), // [!code highlight]
});
```

This works with any AI SDK provider, including Azure OpenAI, AWS Bedrock, and
Ollama. For an OpenAI-compatible endpoint, read the next section first.

```typescript
import { createAzure } from "@ai-sdk/azure";

const azure = createAzure({
  resourceName: "my-resource",
  apiKey: process.env.AZURE_API_KEY,
});

const agent = new BuiltInAgent({
  model: azure("my-deployment"),
});
```

### OpenAI-compatible providers: use `provider.chat(model)` [#openai-compatible-providers-use-providerchatmodel]

`@ai-sdk/openai` 3.x sends a bare `provider(model)` call to the OpenAI
**Responses** API (`POST {baseURL}/responses`). Many OpenAI-compatible
providers do not serve that endpoint. They serve only the Chat Completions API
(`POST {baseURL}/chat/completions`). When you point `createOpenAI` at such a
provider and call `provider(model)`, the agent run fails with an error from
the provider, such as a 404.

Call `provider.chat(model)` instead. It sends the request to the Chat
Completions API:

```typescript
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { createOpenAI } from "@ai-sdk/openai";

const provider = createOpenAI({
  apiKey: process.env.PROVIDER_API_KEY,
  baseURL: "https://api.example-provider.com/v1",
});

const agent = new BuiltInAgent({
  model: provider.chat("provider-model-id"), // [!code highlight]
});
```

Use the bare `provider(model)` form only when the host serves the Responses
API, such as OpenAI itself or a proxy that forwards to OpenAI. The
`"openai:..."` model strings do not have this problem: with `OPENAI_BASE_URL`
set to a host that is not OpenAI or Azure, the Built-in Agent picks the Chat
Completions API for you (see
[OpenAI-compatible endpoints](#openai-compatible-endpoints)).

## OpenRouter, proxies, and bring-your-own LLM [#openrouter-proxies-and-bring-your-own-llm]

Anything that exposes an **OpenAI-compatible** API, including [OpenRouter](https://openrouter.ai),
a self-hosted gateway, an internal LLM proxy, [Ollama](https://ollama.com), [Together](https://together.ai),
[Groq](https://groq.com), [Novita](https://novita.ai), or your own fine-tuned endpoint, works through the same
`createOpenAI({ baseURL })` pattern shown in [Custom Models](#custom-models-ai-sdk)
above. Point `baseURL` at the provider's OpenAI-compatible route and pass your key:

```typescript
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { createOpenAI } from "@ai-sdk/openai"; // [!code highlight]

// OpenRouter: one key, hundreds of models behind an OpenAI-compatible API
const openrouter = createOpenAI({
  // [!code highlight]
  apiKey: process.env.OPENROUTER_API_KEY, // [!code highlight]
  baseURL: "https://openrouter.ai/api/v1", // [!code highlight]
}); // [!code highlight]

const agent = new BuiltInAgent({
  model: openrouter.chat("anthropic/claude-sonnet-4-6"), // [!code highlight]
});
```

The same shape works for any OpenAI-compatible proxy. Swap the `baseURL` and key.
There is no CopilotKit-specific provider to install. Install
`@ai-sdk/openai@ai-v6` as shown in [Custom Models](#custom-models-ai-sdk). If the
AI SDK can talk to it, the Built-in Agent can use it.

<Callout type="warn" title="The model is set on the agent">
  CopilotKit does **not** expose a cloud-hosted endpoint for choosing or
  switching the model at request time. The model is configured **on the agent**,
  either as a `"provider:model"` string or an AI SDK `LanguageModel` instance:

```typescript
new BuiltInAgent({ model: "openai:gpt-6-luna" }); // built-in string
new BuiltInAgent({ model: openrouter.chat("...") }); // any LanguageModel
```

To let each request pick the model, add `overridableProperties: ["model"]` to
the agent. The frontend then sends `model` in the provider's `properties`, which
reach the agent as `forwardedProps`. See
[Overridable properties](/slack/advanced-configuration#overridable-properties).
The agent then runs any provider and model the browser names, on your server's
keys. To limit the choice, check `forwardedProps.model` against your own list in
a [factory](/slack/backend/custom-agent#with-forwardedprops) instead.
Otherwise, construct the agent with the desired `model` on your own backend.
For full control over the runtime you can also use a
[Custom Agent](/slack/backend/custom-agent).

</Callout>

## How it works [#how-it-works]

The Built-in Agent resolves model strings to AI SDK provider instances:

| Model string                    | AI SDK provider     | Resolved call                    |
| ------------------------------- | ------------------- | -------------------------------- |
| GPT-6 Luna | `openai:gpt-6-luna` |
| `"anthropic:claude-sonnet-4-6"` | `@ai-sdk/anthropic` | `anthropic("claude-sonnet-4-6")` |
| `"google:gemini-3.8-flash"`     | `@ai-sdk/google`    | `google("gemini-3.8-flash")`     |

Both `"provider:model"` and `"provider/model"` separators are supported and work identically.

<Callout type="info" title="Need a different AI SDK or full control?">
  The [Custom Agent](/slack/backend/custom-agent) lets you bring your own AI SDK,
  TanStack AI, or any custom LLM backend while CopilotKit handles the rest.
</Callout>
