Model Selection

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-5.4-mini. The Built-in Agent sends the model id to the provider unchanged, so other model ids from the same provider also work.

OpenAI#

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
});

Anthropic#

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

Google#

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

Use gemini-3.5-flash-lite for lower cost and latency. Google no longer gives 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#

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/v1

OpenAI-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=responses

Alternatively, pass the API key directly in your configuration:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  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-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.

new BuiltInAgent({ model: "openai:gpt-5.4-mini" }); // built-in string
new BuiltInAgent({ model: openrouter.chat("...") }); // any LanguageModel

How it works#

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

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