State Rendering

Render your agent's state with custom UI components in real-time.

State Streaming

Waking up the demo

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.

src/agents/shared_state_read_write.py
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:

src/agents/shared_state_read_write.py
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 = prefs

Write 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:

agent.py
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.

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

  2. On the frontend, import useAgent from @copilotkit/react-core/v2:

    import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
  3. 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],
      });
  4. Read the key from agent.state and 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?