CopilotKit

Agent Read-Only Context

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


"""AG2 agent with weather and sales tools for CopilotKit showcase.Uses AG2's ConversableAgent with AGUIStream to exposethe agent via the AG-UI protocol."""from __future__ import annotationsimport jsonimport osfrom typing import Annotated, Anyfrom autogen import ConversableAgent, LLMConfigfrom autogen.ag_ui import AGUIStreamfrom dotenv import load_dotenvload_dotenv()# Import shared tool implementationsfrom tools import (    get_weather_impl,    query_data_impl,    manage_sales_todos_impl,    get_sales_todos_impl,    schedule_meeting_impl,    search_flights_impl,    build_a2ui_operations_from_tool_call,    RENDER_A2UI_TOOL_SCHEMA,)from tools.types import Flight# =====# Tools# =====async def get_weather(    location: Annotated[str, "City name to get weather for"],) -> dict[str, str | float]:    """Get current weather for a location."""    result = get_weather_impl(location)    return {        "city": result["city"],        "temperature": result["temperature"],        "feels_like": result["feels_like"],        "humidity": result["humidity"],        "wind_speed": result["wind_speed"],        "conditions": result["conditions"],    }async def query_data(    query: Annotated[str, "Natural language query for financial data"],) -> list:    """Query financial database for chart data."""    return query_data_impl(query)async def manage_sales_todos(    todos: Annotated[list, "Complete list of sales todos"],) -> dict:    """Manage the sales pipeline."""    return {"todos": manage_sales_todos_impl(todos)}async def get_sales_todos() -> list:    """Get the current sales pipeline."""    return get_sales_todos_impl(None)async def schedule_meeting(    reason: Annotated[str, "Reason for the meeting"],) -> dict:    """Schedule a meeting with user approval."""    return schedule_meeting_impl(reason)async def search_flights(    flights: Annotated[        list[dict[str, Any]], "List of flight objects to display as rich A2UI cards"    ],) -> str:    """Search for flights and display the results as rich cards. Return exactly 2 flights.    Each flight must have: airline, airlineLogo, flightNumber, origin, destination,    date (short readable format like "Tue, Mar 18" -- use near-future dates),    departureTime, arrivalTime, duration (e.g. "4h 25m"),    status (e.g. "On Time" or "Delayed"),    statusColor (hex color for status dot),    price (e.g. "$289"), and currency (e.g. "USD").    For airlineLogo use Google favicon API:    https://www.google.com/s2/favicons?domain={airline_domain}&sz=128    """    typed_flights: list[Flight] = [Flight(**f) for f in flights]    result = search_flights_impl(typed_flights)    return json.dumps(result)async def generate_a2ui(    context: Annotated[str, "Conversation context to generate UI for"],) -> str:    """Generate dynamic A2UI components based on the conversation.    A secondary LLM designs the UI schema and data. The result is    returned as an a2ui_operations container for the middleware to detect.    """    import openai    client = openai.OpenAI()    response = client.chat.completions.create(        model="gpt-4.1",        messages=[            {"role": "system", "content": context or "Generate a useful dashboard UI."},            {                "role": "user",                "content": "Generate a dynamic A2UI dashboard based on the conversation.",            },        ],        tools=[            {                "type": "function",                "function": RENDER_A2UI_TOOL_SCHEMA,            }        ],        tool_choice={"type": "function", "function": {"name": "render_a2ui"}},    )    choice = response.choices[0]    if choice.message.tool_calls:        args = json.loads(choice.message.tool_calls[0].function.arguments)        result = build_a2ui_operations_from_tool_call(args)        return json.dumps(result)    return json.dumps({"error": "LLM did not call render_a2ui"})# =====# Agent# =====agent = ConversableAgent(    name="assistant",    system_message=(        "You are a helpful sales assistant. You can look up current weather "        "for any city using the get_weather tool, query financial data with "        "query_data, manage the sales pipeline with manage_sales_todos and "        "get_sales_todos, schedule meetings with schedule_meeting, search "        "flights and display rich A2UI cards with search_flights, and "        "generate dynamic A2UI dashboards with generate_a2ui. "        "When asked about the weather, always use the tool rather than guessing. "        "Be concise and friendly in your responses."    ),    llm_config=LLMConfig({"model": "gpt-4o-mini", "stream": True}),    human_input_mode="NEVER",    # Guard against infinite tool-call loops: AG2's ConversableAgent with    # human_input_mode="NEVER" will keep executing tool calls indefinitely    # if the LLM keeps requesting them.  Without this limit the agent floods    # Railway's log stream (500 logs/sec rate-limit), becomes unresponsive    # to health probes, and gets killed by the watchdog.    max_consecutive_auto_reply=15,    functions=[        get_weather,        query_data,        manage_sales_todos,        get_sales_todos,        schedule_meeting,        search_flights,        generate_a2ui,    ],)# AG-UI stream wrapperstream = AGUIStream(agent)

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.