CopilotKit

Agent Config

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

"use client";/** * Agent Config Object — typed config knobs (tone / expertise / responseLength) * forwarded from the provider into the agent so its behavior changes per turn. * * Wiring: the toggles live in `useAgentConfig`. Each render the resolved * config is published to the agent via `useAgentContext` — the v2 idiom * for "frontend → agent runtime context" in LangGraph 0.6+. The Python * graph picks it up through `CopilotKitMiddleware`, which routes the * context entry into the model's prompt before each call. * * (LangGraph 0.6 deprecated `configurable` in favor of `context`; the * `properties` prop on `<CopilotKit>` still works for v1-style relays * but goes through `forwardedProps` and does not land in `RunnableConfig` * in @ag-ui/langgraph 0.0.31. `useAgentContext` is the supported path.) */import { CopilotKit } from "@copilotkit/react-core/v2";import { DemoLayout } from "./demo-layout";import { ConfigContextRelay } from "./config-context-relay";import { useAgentConfig } from "./use-agent-config";export default function AgentConfigDemoPage() {  const { config, setTone, setExpertise, setResponseLength } = useAgentConfig();  return (    <CopilotKit      runtimeUrl="/api/copilotkit-agent-config"      agent="agent-config-demo"    >      <ConfigContextRelay config={config} />      <DemoLayout        config={config}        onToneChange={setTone}        onExpertiseChange={setExpertise}        onResponseLengthChange={setResponseLength}      />    </CopilotKit>  );}

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. Agents living behind a runtime read it from agent state on every run, while in-process agents receive the same object as forwarded properties on the provider — same UX, slightly different wiring on each side.

How it works#

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.

Backend flow
config = latestValidConfig(currentRun.context)
systemPrompt = buildSystemPrompt(config)
model.invoke(systemPrompt, currentUserRequest)

The agent reads the latest typed config at the start of every turn, rebuilds the system prompt, runs the turn. This is the same shape as the shared-state write-side pattern; agent config is just a specific use of that pattern with a UI-owned typed object on top.

On this page

When to use thisHow it works