State Rendering
Render your agent's state with custom UI components in real-time.
What is this?
State rendering lets you build UI that reflects your agent's state in real-time. As your agent progresses through nodes and emits state updates, your frontend renders those changes, showing progress, drafts, or intermediate results.
When should I use this?
Use state rendering when you want to:
- Show real-time progress (e.g. "Researching... 2/5 complete")
- Display drafts that update as the agent works
- Build dashboards that reflect agent state
- Render structured output outside of the chat
How it works in code
Install the LangGraph Python SDK
uv add copilotkitWire CopilotKit middleware into your graph
Shared state flows between your UI and your agent through agent.setState
on the frontend and state.get(...) in your graph nodes. Attach
CopilotKitMiddleware to your create_agent call so CopilotKit-specific
state is picked up alongside your own.
graph = create_agent(
model=ChatOpenAI(reasoning_effort="none", model="gpt-6-luna"),
tools=[set_notes],
middleware=[CopilotKitMiddleware(), PreferencesInjectorMiddleware()],
state_schema=AgentState,
system_prompt=(
"You are a helpful, concise assistant. "
"The user's preferences are supplied via shared state and will be "
"added as a system message at the start of every turn. Always "
"respect them. "
"When the user asks you to remember something, or when you observe "
"something worth surfacing in the UI, call `set_notes` with the "
"FULL updated list of short note strings (existing notes + new)."
),
)Using a custom graph instead of create_agent
In a graph where you define the nodes and edges yourself, inherit your
state from CopilotKitState and add your own keys. A default value in the
state class is not applied at runtime, so read each key with a fallback.
Return the key from the node, so the next nodes and the frontend can
read it:
from langchain_core.runnables import RunnableConfig
from copilotkit import CopilotKitState
from typing import Literal
class AgentState(CopilotKitState):
language: Literal["english", "spanish"] = "english"
def chat_node(state: AgentState, config: RunnableConfig):
# If language is not defined, set a value.
# this is because a default value in a state class is not read on runtime
language = state.get("language", "english")
# ... add the rest of the node implementation and use the language variable
return {
# ... add the rest of state to return
# return the language to make it available for the next nodes & frontend to read
"language": language
}-
On the backend, write the value to a key in the agent state. To stream a tool argument into a state key token by token, see State Streaming.
-
On the frontend, import
useAgentfrom@copilotkit/react-core/v2:import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2"; -
Subscribe to the agent state. Each time the state changes, your component renders again with the latest value:
page.tsx // Subscribe to BOTH state changes and run-status changes. The former // drives the per-token document rerender; the latter toggles the // "LIVE" badge when the agent starts / stops. const { agent } = useAgent({ agentId: "shared-state-streaming", updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); -
Read the key from
agent.stateand render it:const document = (agent.state as { document?: string }).document ?? "";
To check it, ask the agent to write a short poem. Your component renders the
poem each time the agent updates document in its state.
To render the state inside the chat instead, pass a children function to
the chat's messageView slot and add your UI next to the messages. For
example, to list the searches an agent keeps in a searches key:
<CopilotChat
agentId="sample_agent"
messageView={{
children: ({ messageElements, interruptElement }) => (
<div>
{messageElements}
{state.searches?.map((search, index) => (
<div key={index}>{search.done ? "✅" : "❌"} {search.query}</div>
))}
{interruptElement}
</div>
),
}}
/>Here state is agent.state from useAgent.
Free course: See this pattern built end-to-end in Build Interactive Agents with Generative UI. This free DeepLearning.AI short course is taught by CopilotKit's CEO. It covers the full Generative UI spectrum (Controlled, Declarative, and Open-Ended).
How is this guide?