Agent Read-Only Context

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

Shared State: Frontend Context

Waking up the demo

See this in Inspector

Open Inspector on localhost. Go to Inspect, then Context. The values you publish with useAgentContext appear here.

More detail: Inspector.

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

If the agent must also write the value, use shared state. To stream agent-written state to the UI during a run, see State streaming.

How it works in code

Install the LangGraph Python SDK

uv add copilotkit

Wire read-only agent context into your graph

useAgentContext publishes read-only UI values through CopilotKitMiddleware. Attach the middleware to the agent and describe how the model should use the frontend-supplied context in the system prompt.

readonly_state_agent_context.py
graph = create_agent(
    model=ChatOpenAI(reasoning_effort="none", model="gpt-6-luna"),
    tools=[],
    middleware=[CopilotKitMiddleware()],
    system_prompt=(
        "You are a helpful, concise assistant. The frontend may provide "
        "read-only context about the user (e.g. name, timezone, recent "
        "activity) via the `useAgentContext` hook. Always consult that "
        "context when it is relevant — address the user by name if known, "
        "respect their timezone when mentioning times, and reference "
        "recent activity when it helps you answer. Keep responses short."
    ),
)

Using a custom graph instead of create_agent

CopilotKitMiddleware only works with create_agent. In a graph where you define the nodes and edges yourself, nothing adds the context to the prompt for you. Inherit your state from CopilotKitState, read the entries from state["copilotkit"]["context"] in a node, and pass them to the model yourself.

Each entry's value arrives as a JSON string. Parse it with json.loads before you read a field. Without the parse, colleagues[0] is a single character, not a colleague.

agent.py
import json

from langchain_core.runnables import RunnableConfig
from langchain_core.messages import SystemMessage
from langchain_openai import ChatOpenAI
from copilotkit import CopilotKitState # extends MessagesState

class AgentState(CopilotKitState):
    # ... Your defined state properties
    pass

def chat_node(state: AgentState, config: RunnableConfig):
    # Extract the colleagues from CopilotKit context
    colleagues_context_item = next(
        (item for item in state["copilotkit"]["context"] if item.get("description") == "The current user's colleagues"),
        None
    )

    # The value is a JSON string, so parse it to read the fields
    colleagues = []
    if colleagues_context_item:
        colleagues = json.loads(colleagues_context_item["value"])

    # Now each entry is a dict, so colleague["name"] works
    colleague_list = ", ".join(f"{c['name']} ({c['role']})" for c in colleagues)

    # Provide the list of colleagues to the LLM
    system_message = SystemMessage(
        content=f"""You are a helpful assistant that can help emailing colleagues.
        The user's colleagues are: {colleague_list}"""
    )

    response = ChatOpenAI(model="gpt-6-luna", reasoning_effort="none").invoke(
        [system_message, *state["messages"]],
        config
    )

    return {
        **state,
        "messages": response,
    }

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.
  • Sent to the agent with every run. The Built-in Agent adds each entry to the system prompt. Python LangGraph agents need CopilotKitMiddleware to add the entries, and ADK agents need an instruction provider. Microsoft Agent Framework, CrewAI Flows and Pydantic AI agents drop the entries silently unless you wire them. The setup above shows the code for your framework.
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.

Call useAgentContext in as many components as you like. The agent receives every registered entry.

Context values arrive as JSON strings

The AG-UI protocol defines a context value as a string. Therefore useAgentContext calls JSON.stringify on any value that is not already a string, and your agent receives the JSON text instead of the object or the array.

Parse the value before you read a field from it. Use json.loads(item["value"]) in Python, or JSON.parse(item.value) in TypeScript. If you skip the parse step, an index such as colleagues[0] returns a single character, and a shape check such as isinstance(value, list) can never pass.

Do not stringify the value again, because that produces double encoding. A value that is already a string is sent unchanged, so no parse step is needed for it.

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,
  CopilotPopup,
  useAgentContext,
} from "@copilotkit/react-core/v2";

import { ACTIVITIES, DemoLayout } from "./demo-layout";
import { useReadonlyStateAgentContextSuggestions } from "./suggestions";

export default function ReadonlyStateAgentContextDemo() {
  return (
    <CopilotKit
      runtimeUrl="/api/copilotkit"
      agent="readonly-state-agent-context"
    >
      <DemoContent />
      <CopilotPopup
        agentId="readonly-state-agent-context"
        defaultOpen={true}
        labels={{ chatInputPlaceholder: "Ask about your context..." }}
      />
    </CopilotKit>
  );
}

function DemoContent() {
  const [userName, setUserName] = useState("Atai");
  const [userTimezone, setUserTimezone] = useState("America/Los_Angeles");
  const [recentActivity, setRecentActivity] = useState<string[]>([
    ACTIVITIES[0],
    ACTIVITIES[2],
  ]);

Treat entries as untrusted input

Every entry is a claim your frontend made, and a user can change it. It never proves who is making the request. Let entries inform the agent's answer, but take facts that grant access, such as the authenticated user, the workspace, or the tenant, from your server. If your agent builds its prompt from entries, keep them apart from your own instructions, so text in an entry can't override them.

Try it

Ask the agent: "What is my name?" It answers with the value of userName. Change the name in your UI and ask again: the answer changes.

How is this guide?