State Rendering

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

Shared 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

Install the LangGraph Python SDK

uv add copilotkit

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

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

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