# 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](/react-native/strands-typescript/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]

<Steps>
  <Step>
    ### 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:

~~~~typescript title="src/agent/state.ts"
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 };
}
~~~~

  </Step>
  <Step>
    ### 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.

~~~~typescript title="src/agent/agent.ts"
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.

  </Step>
</Steps>

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.

```text title="Backend flow"
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.

<IntegrationGrid path="agent-config" />
