Agent Config

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

Agent Config Object

Waking up the demo

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

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

Pass the typed object as properties on <CopilotKit>:

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:

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.

Choose your AI backend

How is this guide?