State Rendering

Render your agent's state with your own React Native 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 works and writes to its state, your app renders those changes: progress, drafts, or intermediate results.

When should I use this?

Use state rendering when you want to:

  • Show real-time progress (for example, "Researching... 2/5 complete")
  • Display drafts that update as the agent works
  • Build dashboards that reflect agent state
  • Render structured output outside the chat

How it works in code

Install the CopilotKit LangGraph SDK

npm install @copilotkit/sdk-js

Wire CopilotKit state into your graph

Shared state requires that your graph's state annotation extends CopilotKitStateAnnotation's spec. That's what gives the runtime a place to forward state updates from agent.setState(...).

shared-state-read-write.ts
export interface Preferences {
  name?: string;
  tone?: "formal" | "casual" | "playful";
  language?: string;
  interests?: string[];
}

const AgentStateAnnotation = Annotation.Root({
  ...CopilotKitStateAnnotation.spec,
  preferences: Annotation<Preferences | undefined>,
  notes: Annotation<string[]>,
});

export type AgentState = typeof AgentStateAnnotation.State;

See src/agent/shared-state-read-write.ts for the bidirectional pattern: a set_notes tool emits a Command({ update: ... }) to push agent-authored state, and a preferences-injecting chat node reads UI-authored state every turn.

  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, subscribe to the agent's state with useAgent. Each time the state changes, your component renders again with the latest value.
  3. Read the keys from agent.state and render them.
src/ResearchProgress.tsx
import { Text, View } from "react-native";
import { useAgent, UseAgentUpdate } from "@copilotkit/react-native/headless";

type ResearchState = {
  status?: string;
  draft?: string;
  completed?: number;
  total?: number;
};

export function ResearchProgress() {
  const { agent } = useAgent({
    agentId: "researcher",
    updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged],
  });
  const state = (agent.state ?? {}) as ResearchState;

  return (
    <View style={{ padding: 16, gap: 8 }} accessibilityLiveRegion="polite">
      <Text style={{ fontWeight: "600" }}>
        {state.status ?? (agent.isRunning ? "Working..." : "Idle")}
      </Text>
      <Text>
        {state.completed ?? 0} of {state.total ?? "?"} complete
      </Text>
      {state.draft ? <Text>{state.draft}</Text> : null}
    </View>
  );
}

updates picks which changes re-render the component. OnStateChanged fires on state changes, and OnRunStatusChanged fires when a run starts or ends, so agent.isRunning stays current. Leave updates out to re-render on messages too.

Render it next to your chat, under the same provider. The chat and ResearchProgress share one agent:

App.tsx
import { View } from "react-native";
import { CopilotKitProvider } from "@copilotkit/react-native/headless";
import { CopilotChat } from "@copilotkit/react-native/components";
import { ResearchProgress } from "./src/ResearchProgress";

const runtimeUrl = "http://localhost:8200/api/copilotkit";

export default function App() {
  return (
    <CopilotKitProvider runtimeUrl={runtimeUrl}>
      <View style={{ flex: 1 }}>
        <ResearchProgress />
        <CopilotChat agentName="researcher" />
      </View>
    </CopilotKitProvider>
  );
}

To check it, ask the researcher agent to write a report. The status line and the counter change while the agent runs, and the draft grows as the agent updates draft in its state.

Inside the chat

The rendered CopilotChat has no slot for extra content between messages. To show state inside the conversation, build your own chat and add a row for it to your FlatList data. See Headless UI.

Treat state as untrusted

Treat agent state as external data. Validate it before you use it for a privileged action, and don't put secrets in state that is streamed to the device.

How is this guide?