# Advanced Configuration

> Fine-tune your Built-in Agent's behavior with advanced options.

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

## Multi-step tool calling [#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:

```typescript title="src/copilotkit.ts"
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  maxSteps: 5, // [!code highlight]
  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 [#tool-choice]

Control how the agent selects tools:

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  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 [#system-prompt]

Customize the agent's system prompt:

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  prompt: "You are a customer support agent for Acme Corp. Be concise and helpful. Always check the knowledge base before answering.", // [!code highlight]
});
```

## Generation parameters [#generation-parameters]

Fine-tune the model's output:

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  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
});
```

<Callout type="info">
Not all parameters are supported by every provider. For example, `topK` is supported by Google but not OpenAI. Unsupported parameters are ignored.
</Callout>

## Provider-specific options [#provider-specific-options]

Pass options specific to a model provider using `providerOptions`:

```typescript
// OpenAI reasoning models (`gpt-6-luna`) with reasoning effort
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  providerOptions: { // [!code highlight:3]
    openai: { reasoningEffort: "high" },
  },
});
```

```typescript
// Anthropic with adaptive thinking
const agent = new BuiltInAgent({
  model: "anthropic:claude-sonnet-4-6",
  providerOptions: { // [!code highlight:3]
    anthropic: { thinking: { type: "adaptive" }, effort: "high" },
  },
});
```

## Overridable properties [#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:

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  temperature: 0.5,
  overridableProperties: ["model", "temperature", "prompt"], // [!code highlight]
});
```

The frontend sends overrides in the provider's `properties`, which reach the agent as `forwardedProps`. The agent applies only the keys in `overridableProperties`:

```tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  properties={{ model: "anthropic:claude-sonnet-4-6" }}
>
  {children}
</CopilotKitProvider>
```

<Callout type="warn">
  The browser picks these values. With `model` overridable, any client can run
  any provider and model on your server's keys. With `prompt` overridable, any
  client can replace the system prompt. To let users choose from a fixed set,
  check the value on the server in a
  [factory](/backend/custom-agent#with-forwardedprops).
</Callout>

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

## Message forwarding [#message-forwarding]

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

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

## URL attachments [#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:

```typescript
const agent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  urlDownload: { // [!code highlight:4]
    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 applies these limits:
  - `maxBytes`: 20 MiB per download.
  - `timeoutMs`: 30 seconds per download.
  - `maxDownloads`: 20 distinct URLs per model call.
  - `maxTotalBytes`: 50 MiB in total per model call.

  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:

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

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

## Full configuration reference [#full-configuration-reference]

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `model` | `string \| LanguageModel` | none | Model specifier or AI SDK instance |
| `apiKey` | `string` | env var | API key for the provider |
| `maxSteps` | `number` | `1` (`10` when learned skills load) | Max tool-calling iterations |
| `toolChoice` | `ToolChoice` | `"auto"` | How tools are selected: `"auto"`, `"required"`, `"none"`, or `{ type: "tool", toolName: string }` |
| `maxOutputTokens` | `number` | none | Max tokens in response |
| `temperature` | `number` | none | Sampling temperature |
| `topP` | `number` | none | Nucleus sampling |
| `topK` | `number` | none | Top-K sampling |
| `presencePenalty` | `number` | none | Presence penalty |
| `frequencyPenalty` | `number` | none | Frequency penalty |
| `stopSequences` | `string[]` | none | Stop sequences |
| `seed` | `number` | none | Random seed |
| `maxRetries` | `number` | none | Retry count |
| `prompt` | `string` | none | System prompt |
| `tools` | `ToolDefinition[]` | `[]` | Server-side tools |
| `mcpServers` | `MCPClientConfig[]` | `[]` | MCP server connections (agent-managed, per-request) |
| `mcpClients` | `MCPClientProvider[]` | `[]` | User-managed MCP clients (persistent, user controls lifecycle) |
| `overridableProperties` | `string[]` | `[]` | Properties the frontend can override |
| `providerOptions` | `Record<string, any>` | none | Provider-specific options |
| `forwardSystemMessages` | `boolean` | `false` | Forward system messages |
| `forwardDeveloperMessages` | `boolean` | `false` | Forward developer messages |
| `urlDownload` | `"disabled"`, object, or function | public addresses only | Server-side download of URL attachments. Pass `"disabled"`, a `SafeUrlDownloadOptions` object, or an `Experimental_DownloadFunction` |
| `capabilities` | `Partial<AgentCapabilities>` | inferred | Capabilities the agent reports. Each category you set replaces the inferred one |
| `learnedSkills` | `BuiltInAgentLearnedSkillsOptions` | none | Loads learned skills before each run. See [Skill delivery](/intelligence/learned-skills#builtinagent) |

<Callout type="info" title="Need even more control?">
  If `BuiltInAgent`'s configuration options don't cover your needs (for example, if you want to use TanStack AI, a custom LLM backend, or async initialization), see [Custom Agent](/backend/custom-agent).
</Callout>
