shared-state.mdx

title	Shared State
description	Create a two-way connection between your UI and agent state.
icon	lucide/Repeat
hideTOC	true
snippet_cell	shared-state-read-write

What is shared state?

Agentic Copilots maintain a shared state that seamlessly connects your UI with the agent's execution. This shared state system allows you to:

• Display the agent's current progress and intermediate results
• Update the agent's state through UI interactions
• React to state changes in real-time across your application

When should I use this?

Use shared state when you want to facilitate collaboration between your agent and the user. Updates flow both ways: the agent's outputs are automatically reflected in the UI, and any inputs the user updates in the UI are automatically reflected in the agent's execution.

The two directions

Shared state is a single object that both the UI and the agent can read and write. In practice, most apps split it into at least two conceptual slices:

• A UI-written slice (e.g. user profile, form inputs) that the agent reads on every turn and uses to tailor its behaviour.
• An agent-written slice (e.g. notes, a document, a plan) that the UI renders in real time as the agent produces it.

The example below wires both sides against a single AgentState schema with preferences (UI-written) and notes (agent-written).

Reading agent state

The useAgent hook subscribes your component to state changes. Pass UseAgentUpdate.OnStateChanged and every mutation the agent makes to its state triggers a re-render; your UI is a reactive window into the agent's world.

Once subscribed, the agent-authored slice of state is just data you render. The NotesCard below is a plain presentational component. It doesn't know about CopilotKit at all; it just receives notes as a prop from the parent page.

Writing to agent state

Writes flow the other direction via agent.setState. Every call replaces the named fields; on the agent's next turn, the new values are visible to the backend (via middleware, prompt injection, or direct reads from state) and influence the reply.

The form that generates those writes is, again, a plain controlled component. Every onChange bubbles up to the parent, which calls agent.setState, keeping the UI and the agent in lockstep.

Going further

Two common extensions of the basic pattern:

• State streaming — stream partial state updates to the UI while a tool call is still running, so long-running outputs (documents, plans) appear token-by-token.
• Agent read-only context — when you only need a one-way UI → agent channel, useAgentContext publishes read-only values to the agent without opening up write access.

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