Agent Config
Forward typed configuration from your UI into the agent's reasoning loop.
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
Send application context with each run
useAgentContext adds configuration to the current AG-UI request. The
Strands adapter exposes it during model calls without saving it as user
text. Add UI-owned state to a copy of that request's context:
export function withStateContext(inputData: RunAgentInput): RunAgentInput {
const state =
inputData.state && typeof inputData.state === "object"
? (inputData.state as Record<string, unknown>)
: {};
const context = [...inputData.context];
const preferences = formatPreferencesBlock(state.preferences);
if (preferences) {
context.push({
description: "Current user preferences",
value: preferences,
});
}
if ("todos" in state) {
context.push({
description: "Current sales pipeline",
value: JSON.stringify(state.todos, null, 2),
});
}
return { ...inputData, context };
}Apply current state before running the adapter
This wrapper runs for every request, including tool continuations. Changed
frontend context and state apply to the next run; messages retain their
original content. Do not prepend context with stateContextBuilder, whose
output becomes native message history.
export class ShowcaseStrandsAgent extends BoardStateStrandsAgent {
override async *run(inputData: RunAgentInput) {
// The adapter exposes context during model calls and restores history afterward.
yield* super.run(withStateContext(inputData));
}
}Existing histories created with a prompt-rewriting builder retain that content. Start a new conversation for clean history; importing an old conversation preserves its original text without guessing which parts to remove.
Agent config is a typed object the frontend owns and publishes to the agent as runtime context. The backend reads that context entry and turns it into a system prompt.
The framework setup above shows the exact backend bridge for the selected agent. In every framework, the flow is the same: read the latest valid context from the current run and use it to build the system prompt for that turn.
config = latestValidConfig(currentRun.context)
systemPrompt = buildSystemPrompt(config)
model.invoke(systemPrompt, currentUserRequest)At the start of every turn, the agent reads the latest config. Then it rebuilds the system prompt and runs the turn.
Change the tone in your UI and send a message. The next reply uses the new tone.
How is this guide?