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
Declare the shared keys on your Flow state
A Flow keeps its state in self.state. Type the Flow on a subclass of
CopilotKitState and declare every key the UI reads or writes, with a
default. CopilotKitState brings the CopilotKit messages and actions.
from typing import List, Optional
from ag_ui_crewai import CopilotKitState
from pydantic import BaseModel, Field
class Preferences(BaseModel):
name: str = ""
tone: str = "casual"
language: str = "English"
interests: List[str] = Field(default_factory=list)
class AgentState(CopilotKitState):
# Written by the UI with agent.setState
preferences: Optional[Preferences] = None
# Written by the agent, read by the UI with useAgent
notes: List[str] = Field(default_factory=list)Import CopilotKitState from ag_ui_crewai. If you promoted the Flow to a
Conversational Flow, keep inheriting
from ag_ui_crewai.CopilotKitState: it also carries the conversation
fields CrewAI needs.
Read what the UI wrote
Values the UI writes with agent.setState are on self.state when the
next run starts. A nested model can arrive as a plain dict, so convert it
before you use it:
from crewai.flow.flow import Flow, start
class SharedStateReadWriteFlow(Flow[AgentState]):
@start()
async def chat(self) -> None:
prefs = self.state.preferences
if isinstance(prefs, dict):
prefs = Preferences(**prefs)
self.state.preferences = prefsWrite state and emit it
By default the UI receives the Flow's state only when a method finishes.
To update the UI mid-run, assign the value and call
copilotkit_emit_state:
import asyncio
from typing import TypedDict
from crewai.flow.flow import Flow, start
from ag_ui_crewai import CopilotKitState, copilotkit_emit_state
class Searches(TypedDict):
query: str
done: bool
class AgentState(CopilotKitState):
searches: list[Searches] = []
class SearchFlow(Flow[AgentState]):
@start()
async def chat(self):
self.state.searches = [
{"query": "Initial research", "done": False},
{"query": "Retrieving sources", "done": False},
{"query": "Forming an answer", "done": False},
]
await copilotkit_emit_state(self.state)
for search in self.state.searches:
await asyncio.sleep(1)
search["done"] = True
await copilotkit_emit_state(self.state)The showcase's src/agents/shared_state_read_write.py does the same after
the model calls its set_notes tool: it assigns self.state.notes and
emits the state, so the notes card updates before the turn ends.
-
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?