Agent Read-Only Context

Publish UI values to the agent as a one-way read-only channel via useAgentContext.

"use client";import React, { useState } from "react";import {  CopilotKit,  CopilotChat,  useAgentContext,  useConfigureSuggestions,} from "@copilotkit/react-core/v2";export default function ReadonlyStateAgentContextDemo() {  return (    <CopilotKit      runtimeUrl="/api/copilotkit"      agent="readonly-state-agent-context"    >      <DemoContent />    </CopilotKit>  );}const TIMEZONES = [  "America/Los_Angeles",  "America/New_York",  "Europe/London",  "Europe/Berlin",  "Asia/Tokyo",  "Australia/Sydney",];const ACTIVITIES = [  "Viewed the pricing page",  "Added 'Pro Plan' to cart",  "Watched the product demo video",  "Started the 14-day free trial",  "Invited a teammate",];function DemoContent() {  const [userName, setUserName] = useState("Atai");  const [userTimezone, setUserTimezone] = useState("America/Los_Angeles");  const [recentActivity, setRecentActivity] = useState<string[]>([    ACTIVITIES[0],    ACTIVITIES[2],  ]);  useAgentContext({    description: "The currently logged-in user's display name",    value: userName,  });  useAgentContext({    description: "The user's IANA timezone (used when mentioning times)",    value: userTimezone,  });  useAgentContext({    description: "The user's recent activity in the app, newest first",    value: recentActivity,  });  useConfigureSuggestions({    suggestions: [      {        title: "Who am I?",        message: "What do you know about me from my context?",      },      {        title: "Suggest next steps",        message: "Based on my recent activity, what should I try next?",      },      {        title: "Plan my morning",        message:          "What time is it in my timezone and what should I do for the next hour?",      },    ],    available: "always",  });  const toggleActivity = (activity: string) => {    setRecentActivity((prev) =>      prev.includes(activity)        ? prev.filter((a) => a !== activity)        : [...prev, activity],    );  };  return (    <div className="flex flex-col md:flex-row h-screen w-full bg-gray-50">      <aside className="p-4 md:w-[360px] md:shrink-0 overflow-y-auto">        <div          data-testid="context-card"          className="w-full max-w-md p-6 bg-white rounded-2xl shadow-lg border border-gray-100 space-y-5"        >          <div>            <h2 className="text-xl font-bold text-gray-800">Agent Context</h2>            <p className="text-xs text-gray-500 mt-1">              Read-only context provided to the agent via{" "}              <code>useAgentContext</code>. The agent cannot modify these.            </p>          </div>          <label className="block">            <span className="text-sm font-medium text-gray-700">Name</span>            <input              data-testid="ctx-name"              type="text"              value={userName}              onChange={(e) => setUserName(e.target.value)}              placeholder="e.g. Atai"              className="mt-1 w-full border rounded px-3 py-2 text-sm"            />          </label>          <label className="block">            <span className="text-sm font-medium text-gray-700">Timezone</span>            <select              data-testid="ctx-timezone"              value={userTimezone}              onChange={(e) => setUserTimezone(e.target.value)}              className="mt-1 w-full border rounded px-3 py-2 text-sm"            >              {TIMEZONES.map((tz) => (                <option key={tz} value={tz}>                  {tz}                </option>              ))}            </select>          </label>          <div>            <span className="text-sm font-medium text-gray-700">              Recent Activity            </span>            <div className="mt-2 flex flex-col gap-2">              {ACTIVITIES.map((activity) => {                const selected = recentActivity.includes(activity);                return (                  <label                    key={activity}                    className="flex items-center gap-2 text-sm cursor-pointer"                  >                    <input                      type="checkbox"                      checked={selected}                      onChange={() => toggleActivity(activity)}                    />                    <span>{activity}</span>                  </label>                );              })}            </div>          </div>          <div className="pt-3 border-t border-gray-100">            <div className="text-[11px] uppercase tracking-wide text-gray-400 mb-1">              Published Context            </div>            <pre              data-testid="ctx-state-json"              className="bg-gray-50 rounded p-2 text-xs text-gray-700 overflow-x-auto"            >              {JSON.stringify(                { name: userName, timezone: userTimezone, recentActivity },                null,                2,              )}            </pre>          </div>        </div>      </aside>      <main className="flex-1 flex flex-col min-h-0">        <CopilotChat          agentId="readonly-state-agent-context"          className="flex-1 min-h-0"          labels={{ chatInputPlaceholder: "Ask about your context..." }}        />      </main>    </div>  );}

What is this?#

Sometimes you want the agent to know something about the current UI, like the logged-in user, the current page, or a recent activity log, but you don't want the agent to be able to modify it. That's what useAgentContext is for: a one-way UI → agent channel for read-only context.

Unlike full shared state (where the agent can call tools that mutate the state back to the UI), useAgentContext values are pure inputs. The agent sees them on every turn via the runtime's context injection, but it has no setter and no tool to write them back.

When should I use this?#

Reach for useAgentContext instead of full shared state when:

The value is UI-owned and has no meaning to the agent beyond "what the user is looking at right now".
The agent should read but never write (user identity, feature flags, selected record, scroll position).
You want the value to automatically unregister on unmount (e.g. the "current record" context disappears when you leave the page).

Think of it as "props for the agent".

How it works in code#

Call useAgentContext({ description, value }) once per value you want to publish. Each call registers a dynamic context entry with the runtime that is:

Refreshed whenever value changes (React re-renders).
Automatically removed when the component unmounts.
Surfaced to the agent via the backend's CopilotKitMiddleware, which threads the entries into the model's message history on every turn.

page.tsx

  useAgentContext({    description: "The currently logged-in user's display name",    value: userName,  });  useAgentContext({    description: "The user's IANA timezone (used when mentioning times)",    value: userTimezone,  });  useAgentContext({    description: "The user's recent activity in the app, newest first",    value: recentActivity,  });

The description is important: it's a short human-readable label the agent sees alongside the value, so it knows what to do with it. Treat it like a parameter docstring.

Wire it to your own state#

useAgentContext doesn't care where the value comes from: local state, a React Context, Redux, a query cache, anything. The only requirement is that the identity of the value is stable enough for React to avoid a render loop. In the demo we use a handful of useState hooks; in a real app these would likely come from an auth provider, a router hook, and your domain state stores.

page.tsx

import React, { useState } from "react";import {  CopilotKit,  CopilotChat,  useAgentContext,  useConfigureSuggestions,} from "@copilotkit/react-core/v2";export default function ReadonlyStateAgentContextDemo() {  return (    <CopilotKit      runtimeUrl="/api/copilotkit"      agent="readonly-state-agent-context"    >      <DemoContent />    </CopilotKit>  );}const TIMEZONES = [  "America/Los_Angeles",  "America/New_York",  "Europe/London",  "Europe/Berlin",  "Asia/Tokyo",  "Australia/Sydney",];const ACTIVITIES = [  "Viewed the pricing page",  "Added 'Pro Plan' to cart",  "Watched the product demo video",  "Started the 14-day free trial",  "Invited a teammate",];function DemoContent() {  const [userName, setUserName] = useState("Atai");  const [userTimezone, setUserTimezone] = useState("America/Los_Angeles");  const [recentActivity, setRecentActivity] = useState<string[]>([    ACTIVITIES[0],    ACTIVITIES[2],  ]);

Read-only, by design#

Because the agent never sees a setter or a mutation tool for these values, there's no way for a confused LLM to "update" them. That makes useAgentContext the right tool whenever the value in question is an input, not a field: the "context object passed to the agent on every turn", rather than "shared workspace you both edit".

When you need both reads and writes, you want full shared state instead.

Shared State (overview) — bidirectional reads + writes.
State streaming — stream agent-written state back to the UI during a run.