Agent Read-Only Context

Send UI values to the agent as a one-way, read-only channel with useAgentContext.

What is this?

Sometimes you want the agent to know something about the current UI, like the signed-in user, the open screen, or a recent activity log, but you don't want the agent to change 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 write state back to the UI, useAgentContext values are pure inputs. The agent sees them on every turn, but it has no setter and no tool to write them back.

When should I use this?

Use useAgentContext instead of full shared state when:

  • The value is UI-owned and means nothing 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, open screen).
  • You want the value to go away when the component unmounts. For example, the "current record" context disappears when the user leaves that screen.

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

ADK agents must put the context in the prompt

Unlike the Built-in Agent, an ADK agent does not receive this context automatically. The AG-UI adapter stores it in ADK session state under CONTEXT_STATE_KEY ("_ag_ui_context") and stops there. Nothing puts it in the prompt.

An LlmAgent built with a plain string instruction therefore never sees it. The agent still answers, fluently and in the right shape, from nothing. That reads like a working integration until you check the answer against your own records. The instruction provider below is the step that connects them.

Install the ADK + AG-UI bridge

pip install ag-ui-adk

Read CopilotKit context before each model call

The adapter copies the AG-UI request's context list into ADK session state at CONTEXT_STATE_KEY (the public constant for "_ag_ui_context"). Read it from an instruction provider's ctx.state, a callback's callback_context.state, or a tool's tool_context.state.

Each entry is a dictionary with description and value strings. Object and array values registered with useAgentContext arrive as JSON strings; use json.loads(entry["value"]) when you need structured data.

An instruction provider can include the context in the model's prompt. The fully defined callback preserves the Gemini termination safeguard without stopping partial responses or pending tool calls:

from ag_ui_adk import AGUIToolset, CONTEXT_STATE_KEY
from google.adk.agents import LlmAgent
from google.adk.agents.readonly_context import ReadonlyContext
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_response import LlmResponse

def stop_on_terminal_text(
    callback_context: CallbackContext, llm_response: LlmResponse
) -> None:
    content = llm_response.content
    if llm_response.partial or not content or content.role != "model":
        return
    finish_reason = llm_response.finish_reason
    if getattr(finish_reason, "name", finish_reason) != "STOP":
        return
    parts = content.parts or []
    if not any(part.text for part in parts) or any(part.function_call for part in parts):
        return
    # ADK's invocation context is private; tolerate SDK changes.
    invocation = getattr(callback_context, "_invocation_context", None)
    if invocation is not None:
        try:
            invocation.end_invocation = True
        except AttributeError:
            pass

def instructions(ctx: ReadonlyContext) -> str:
    entries = ctx.state.get(CONTEXT_STATE_KEY, [])
    context = "\n".join(
        f"{entry['description']}: {entry['value']}" for entry in entries
    )
    return (
        "Help the user using the following read-only application context.\n"
        + context
    )

agent = LlmAgent(
    name="assistant",
    model="gemini-3.1-flash-lite",
    instruction=instructions,
    tools=[AGUIToolset()],
    after_model_callback=stop_on_terminal_text,
)

AGUIToolset() exposes frontend tools; it does not automatically add context to the model's instructions. The instruction provider above performs that step. Expose this agent through your ADKAgent endpoint.

When only one tool needs the data, read the same entries from tool_context.state[CONTEXT_STATE_KEY] inside that tool instead of adding them to the whole prompt. On google-adk 1.22.0 or later, ctx.run_config.custom_metadata["ag_ui_context"] holds the same entries.

Check that the agent really reads it

This is the one integration that fails quietly, so check the answer against your own records. The reliable check is a control: send the same request once with the context and once with an empty context. Two answers that describe the same record mean the context changed nothing, and the agent is answering from its own invention.

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

  • Refreshed whenever value changes.
  • 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.
src/ProfileScreen.tsx
import { Text, View } from "react-native";
import { useAgentContext } from "@copilotkit/react-native/headless";

export function ProfileScreen({
  userName,
  timezone,
  recentActivity,
}: {
  userName: string;
  timezone: string;
  recentActivity: string[];
}) {
  useAgentContext({
    description: "The signed-in user's name and timezone",
    value: { userName, timezone },
  });

  useAgentContext({
    description: "The last actions the user took in the app, newest first",
    value: recentActivity,
  });

  return (
    <View style={{ padding: 16 }}>
      <Text>Signed in as {userName}</Text>
    </View>
  );
}

The description matters. It's a short label the agent sees next to 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 entry that is registered at the time of the run.

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, or your navigation state. The value must be JSON-serializable. Its serialized form is compared on each render, so a new object with the same contents does not register the entry again.

Rendering data does not send it

A screen that renders a list has put the list in the view tree, not in the agent's context. Those are separate steps. An agent without the second step still answers: the text reads well, the values look plausible, and nothing errors.

Register the data with useAgentContext, and tell the agent in its instructions to refuse to answer about records that the context doesn't carry. Then check one answer against the records your app actually holds.

Treat entries as untrusted input

Every entry is a claim your app 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 app and ask again: the answer changes.

For every option, see the useAgentContext reference.

How is this guide?