# State Rendering

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

<!-- interactive demo: shared-state-streaming -->

## What is this? [#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? [#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 [#how-it-works-in-code]

<Steps>
  <Step>
    ### 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.

    ```python title="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.

  </Step>
  <Step>
    ### 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:

    ```python title="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
    ```

  </Step>
  <Step>
    ### 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`:

    ```python title="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.

  </Step>
</Steps>

1. On the backend, write the value to a key in the
   [agent state](/crewai-crews/shared-state). To stream a tool argument into a state key
   token by token, see [State Streaming](/crewai-crews/shared-state/streaming).
2. On the frontend, import `useAgent` from `@copilotkit/react-core/v2`:

   ```tsx
   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:

   ```typescript title="src/app/demos/shared-state-streaming/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:

   ```tsx
   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:

```tsx
<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`.

<Callout type="info">
  **Free course:** See this pattern built end-to-end in [Build Interactive Agents with Generative UI](https://www.deeplearning.ai/short-courses/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).
</Callout>

<IntegrationGrid
  path="generative-ui/state-rendering"
  exclude={["agno", "agent-spec"]}
/>
