Advanced Configuration

The BuiltInAgent accepts a full set of configuration options to control model behavior, tool calling, and more.

Multi-step tool calling#

By default, the agent performs a single generation step. Set maxSteps to allow the agent to call tools and then continue reasoning:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  maxSteps: 5, 
  tools: [searchDocs, createTicket],
});

With maxSteps: 5, the agent can call a tool, process the result, call another tool, and so on — up to 5 iterations. This is essential for workflows where the agent needs to chain multiple tool calls.

Tool choice#

Control how the agent selects tools:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  toolChoice: "auto",       // Let the model decide (default)
  // toolChoice: "required", // Force the model to call a tool
  // toolChoice: "none",     // Disable tool calling
  // toolChoice: { type: "tool", toolName: "searchDocs" }, // Force a specific tool
});

System prompt#

Customize the agent's system prompt:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  prompt: "You are a customer support agent for Acme Corp. Be concise and helpful. Always check the knowledge base before answering.", 
});

Generation parameters#

Fine-tune the model's output:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  temperature: 0.7,        // Creativity (0 = deterministic, 1+ = creative)
  topP: 0.9,               // Nucleus sampling
  topK: 40,                // Top-K sampling (provider-dependent)
  maxOutputTokens: 4096,   // Maximum tokens in the response
  presencePenalty: 0.1,    // Penalize repeated topics
  frequencyPenalty: 0.1,   // Penalize repeated tokens
  stopSequences: ["END"],  // Stop generation at these sequences
  seed: 42,                // Deterministic output (provider-dependent)
  maxRetries: 3,           // Retry on transient failures
});

Provider-specific options#

Pass options specific to a model provider using providerOptions:

// OpenAI reasoning models (o3, o4-mini) with reasoning effort
const agent = new BuiltInAgent({
  model: "openai:o3",
  providerOptions: { 
    openai: { reasoningEffort: "high" },
  },
});

// Anthropic with adaptive thinking
const agent = new BuiltInAgent({
  model: "anthropic:claude-sonnet-4-6",
  providerOptions: { 
    anthropic: { thinking: { type: "adaptive" }, effort: "high" },
  },
});

Overridable properties#

Allow the frontend to override specific configuration at runtime. This is useful when you want users to switch models or adjust behavior without redeploying:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  temperature: 0.5,
  overridableProperties: ["model", "temperature", "prompt"], 
});

The full list of overridable properties: model, toolChoice, maxOutputTokens, temperature, topP, topK, presencePenalty, frequencyPenalty, stopSequences, seed, maxRetries, prompt, providerOptions

Message forwarding#

Control whether system and developer messages from the conversation are forwarded to the LLM:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  forwardSystemMessages: true,    // Forward system-role messages
  forwardDeveloperMessages: true, // Forward developer-role messages (as system messages)
});

URL attachments#

When a message has an image or file given by URL, and the model cannot take that URL directly, the server downloads the file and sends its content to the model. Use urlDownload to control these downloads:

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  urlDownload: { 
    allowedHosts: ["cdn.example.com", "*.example-uploads.com"],
    maxBytes: 10 * 1024 * 1024,
  },
});

• Default: download only from public internet addresses. The server resolves the hostname and refuses loopback, private, link-local (including cloud metadata), and other non-public addresses. It connects only to the addresses it checked, checks each redirect again, and refuses a redirect from https to http. It limits each download to 20 MiB (maxBytes) and 30 seconds (timeoutMs), and each model call to 20 distinct URLs (maxDownloads) and 50 MiB in total (maxTotalBytes). The AI SDK downloads the attachments again for each step of a multi-step run, so each step counts on its own.
• allowedHosts: download only from the hostnames you list. The addresses must still be public, and each redirect target must also be in the list. cdn.example.com matches only that host. *.example-uploads.com matches its subdomains but not example-uploads.com itself; list both if you need both. Matching ignores case and a trailing dot. Give hostnames only: an entry with a scheme, port, or path, and a wildcard over an IP address (*.1.2.3.4), are rejected when the agent is created. An empty list refuses every server-side download.
• "disabled": never download from the network. Any attachment URL other than data: that the model cannot take directly fails the run.
• A function: your own AI SDK download function (Experimental_DownloadFunction from ai). Use this only if you must fetch from a private network, and check each URL yourself.

Invalid options, including an unknown option name, throw when the agent is created, not when a request arrives.

URLs that the model takes directly go to the model provider unchanged. data: URLs are decoded by the AI SDK without a network request, in every mode. When a download fails or is refused, the client gets a short message without the URL's query or the network error; the server logs the reason with a [BuiltInAgent] prefix. The message is the same whether the hostname could not be resolved or resolved to a non-public address.

The default downloader needs Node.js networking modules. On a runtime without them, such as an edge runtime, every download fails; set urlDownload to "disabled" or to your own download function there.

In AI SDK factory mode you call streamText() yourself, so urlDownload does not apply; setting it there throws when the agent is created. Pass the same downloader to get the same protection, with the run's abort signal so that an aborted run stops its downloads:

import { createSafeUrlDownload } from "@copilotkit/runtime/v2";

factory: (ctx) =>
  streamText({
    // ...
    abortSignal: ctx.abortSignal,
    experimental_download: createSafeUrlDownload({ signal: ctx.abortSignal }),
  }),

Full configuration reference#