Model Selection
Choose and configure models for your Built-in Agent.
The Built-in Agent uses the Vercel AI SDK, so you can use built-in model strings or pass any custom AI SDK model.
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
| Model | Specifier |
|---|---|
| GPT-6 Luna | openai:gpt-6-luna |
const agent = new BuiltInAgent({
model: "openai:gpt-6-luna",
});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 |
const agent = new BuiltInAgent({
model: "anthropic:claude-sonnet-4-6",
});| 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 |
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.
MiniMax
| Model | Specifier |
|---|---|
| MiniMax M3 | minimax:MiniMax-M3 |
| MiniMax M2.7 | minimax:MiniMax-M2.7 |
const agent = new BuiltInAgent({
model: "minimax:MiniMax-M3",
});Environment Variables
Set the API key for your chosen provider:
# 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/v1OpenAI-compatible endpoints
To send openai: model strings to another OpenAI-compatible endpoint, set
OPENAI_BASE_URL:
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:
OPENAI_BASE_URL=https://my-gateway.example.com/v1
COPILOTKIT_OPENAI_API=responsesAlternatively, pass the API key directly in your configuration:
const agent = new BuiltInAgent({
model: "openai:gpt-6-luna",
apiKey: process.env.MY_OPENAI_KEY,
});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 install @ai-sdk/openai@ai-v6Install 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.
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { createOpenAI } from "@ai-sdk/openai";
const openai = createOpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
const agent = new BuiltInAgent({
model: openai("my-fine-tuned-model"),
});This works with any AI SDK provider, including Azure OpenAI, AWS Bedrock, and Ollama. For an OpenAI-compatible endpoint, read the next section first.
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)
@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:
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"),
});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).
OpenRouter, proxies, and bring-your-own LLM
Anything that exposes an OpenAI-compatible API, including OpenRouter,
a self-hosted gateway, an internal LLM proxy, Ollama, Together,
Groq, Novita, or your own fine-tuned endpoint, works through the same
createOpenAI({ baseURL }) pattern shown in Custom Models
above. Point baseURL at the provider's OpenAI-compatible route and pass your key:
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { createOpenAI } from "@ai-sdk/openai";
// OpenRouter: one key, hundreds of models behind an OpenAI-compatible API
const openrouter = createOpenAI({
apiKey: process.env.OPENROUTER_API_KEY,
baseURL: "https://openrouter.ai/api/v1",
});
const agent = new BuiltInAgent({
model: openrouter.chat("anthropic/claude-sonnet-4-6"),
});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. If the
AI SDK can talk to it, the Built-in Agent can use it.
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:
new BuiltInAgent({ model: "openai:gpt-6-luna" }); // built-in string
new BuiltInAgent({ model: openrouter.chat("...") }); // any LanguageModelTo 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.
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 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.
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.
Need a different AI SDK or full control?
The Custom Agent lets you bring your own AI SDK, TanStack AI, or any custom LLM backend while CopilotKit handles the rest.
How is this guide?