# Agent Config

> Forward typed configuration from your UI into the agent's reasoning loop.

<!-- interactive demo: agent-config -->

You have a working agent and want the user to be able to tune how it behaves: tone, expertise level, response length, language, persona. By the end of this guide, your UI will own a typed config object that the agent reads on every run and rebuilds its system prompt from.

## When to use this [#when-to-use-this]

Reach for agent config whenever the agent's behaviour depends on user-controllable settings that don't fit naturally as chat input:

- **Tone, voice, persona**: "playful", "formal", "casual"
- **Expertise level**: "beginner", "intermediate", "expert"
- **Response shape**: short / medium / long, structured / prose, language
- **Domain switches**: which knowledge base to consult, which tool subset to enable

If the values are a *channel* the user occasionally tunes (a settings panel, a toolbar of selects), agent config is the right shape. If the values are *content* the agent should write back to (notes, a document, a plan), use [Shared State](/shared-state) instead.

How agent config flows from the UI into the agent's reasoning loop depends on your runtime architecture. Most agents read the config from the context that the UI publishes with `useAgentContext`. The Built-in Agent reads it from `input.forwardedProps`, which the UI sets with the `properties` prop on `<CopilotKit>`.

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

Pass the typed object as `properties` on `<CopilotKit>`:

```tsx title="frontend/src/app/page.tsx — config flows through the provider"
<CopilotKit
  runtimeUrl="/api/copilotkit"
  properties={{ tone, expertise, responseLength }}
>
  <Demo />
</CopilotKit>
```

The runtime hands the same object to the agent factory on every call as `input.forwardedProps`. The factory uses those fields to build a system prompt, then returns the model stream for that turn:

```ts title="backend/agent factory — synthesise the system prompt per turn"
import { BuiltInAgent, convertInputToTanStackAI } from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

export const agentConfigAgent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { tone, expertise, responseLength } = (input.forwardedProps ??
      {}) as Record<string, string>;
    const { messages, systemPrompts } = convertInputToTanStackAI(input);
    return chat({
      adapter: openaiText("gpt-6-luna"),
      messages,
      systemPrompts: [
        buildSystemPrompt(tone, expertise, responseLength),
        ...systemPrompts,
      ],
      abortController,
    });
  },
});
```

Change the tone in your UI and send a message. The next reply uses the new tone.

<IntegrationGrid path="agent-config" />
