Rich Threads

Build rich, persistent agent conversations that restore messages, generative UI, multimodal inputs, and live runs across sessions and devices.

A support desk application with a Threads Drawer listing customer conversations beside CopilotChat case details for Northstar Analytics

Get started#

Create a new CopilotKit app connected to cloud-hosted Enterprise Intelligence. Your application and CopilotKit Runtime run locally while Enterprise Intelligence stores and synchronizes Rich Threads.

Build and verify this with a coding agent

Set up and verify a CopilotKit Rich Threads application with cloud-hosted
Enterprise Intelligence.

First inspect this repository and follow its agent instructions. If this is not
already a CLI-created CopilotKit Threads starter, run
`npx copilotkit@latest init` and ask me to complete the interactive browser
sign-in and Enterprise Intelligence project selection when needed. Use the
scaffolded local application and CopilotKit Runtime configuration.

Keep the Threads Drawer that comes with the starter. Do not rebuild it or invent
manual Enterprise Intelligence environment configuration. Do not set up a local
Intelligence service.

Start the application and Runtime using the generated instructions. Create a
conversation through the included Threads Drawer, reload or reopen it, and
verify that the complete conversation returns. If browser interaction requires
me, give me the exact step and continue after I confirm it.

Finish by reporting the files changed, commands run, and the persistence check
you completed. Stop and explain the blocker if the cloud-hosted setup cannot be
completed; do not substitute an undocumented setup.

Or follow the steps yourself:

Run the interactive starter command:
Terminal
```
npx copilotkit@latest init
```
Complete browser sign-in, then create or select an Enterprise Intelligence project when the CLI asks.
Start the generated application and Runtime with the command printed by the CLI. For the standard npm setup:
Terminal
```
cd <project-directory>
npm run dev
```
Use the included Threads Drawer to create a conversation. Reload the page or reopen the conversation and confirm that its complete history returns.

Threads-capable CLI starters already include Threads Drawer. Use its guide when you are ready to customize the drawer. Choose Headless Threads later if your product needs a fully custom thread UI.

Production self-hosting: Run Enterprise Intelligence in your own infrastructure#

Production self-hosting keeps Rich Threads, durable event history, identity, storage, and operations inside your network, giving your organization control over data residency, security, and infrastructure. CopilotKit Engineering helps your team deploy Enterprise Intelligence in your Kubernetes environment. Book time with a CopilotKit engineer to get started.

Why use CopilotKit Rich Threads?#

With Rich Threads, users can close the browser, return on another device, reopen a conversation, and continue from the same event history while active runs reconnect in realtime. Generative UI renders again as part of that history, and multimodal inputs stay stored with the conversation.

Built on portable AG-UI event history, Rich Threads restore messages, generative UI, multimodal inputs, tool activity, state, and live-run continuity instead of saving only a chat transcript.

Without CopilotKit Rich Threads, your team has to design the storage model, replay historical events and generative UI, persist multimodal inputs, reconnect live streams, synchronize thread lists, coordinate concurrent runs, and build lifecycle APIs before you can ship the conversation experience itself. Enterprise Intelligence handles that infrastructure so you can focus on your agent and product UI.

Ship persistent conversations without building the backend

Enterprise Intelligence handles durable history, replay, realtime sync, and thread lifecycle on the free Developer tier.

Get Enterprise Intelligence free

Rich Threads provide:

durable event history across reloads, sessions, and devices
seamless replay before a conversation reconnects to a live run
generative UI restored as part of the conversation history
multimodal inputs stored alongside the thread that uses them
realtime thread-list updates without polling
generated names plus rename, archive, unarchive, delete, and pagination APIs
thread-level locking that prevents concurrent runs from interleaving events
the same persistence model across agent frameworks

How Threads work#

Both UI paths use the same Threads infrastructure. A stable threadId connects the visible conversation to the runtime and its durable event history.

A user starts a conversation on a laptop, leaves or switches devices, and returns to the same conversation on a phone.

Your UI opens a conversation with a stable threadId.
CopilotRuntime runs your agent and sends conversation events to Enterprise Intelligence.
When users return, Enterprise Intelligence replays the stored history, reconnects any live run, and synchronizes thread metadata.

How are threads scoped to each user?

Your application authenticates its users, and CopilotRuntime resolves that verified identity on the server with identifyUser. Enterprise Intelligence uses the stable user ID to scope thread lists and lifecycle actions. See Scope Rich Threads to the signed-in user for the Runtime contract and an implementation pattern.

What CopilotKit handles#

CopilotKit handles	You control
Durable event storage and replay	Your agent's behavior and tools
Replay-to-live stream reconnection	The conversation experience and layout
Realtime thread metadata synchronization	Which thread actions your users can access
Naming, pagination, archive, and delete semantics	Application authorization and permissions
Runtime-to-platform event plumbing and thread locks	Mapping to native framework sessions when needed
Cloud-hosted or self-hosted platform infrastructure	The deployment model that fits your organization

Headless means custom UI, not custom infrastructure

Threads Drawer and Headless Threads use the same persistence, replay, synchronization, and locking infrastructure. Choose Headless Threads when you want to build the interface yourself, not when you want to rebuild the Threads backend.

Choose how to build the UI#

If you want to...	Choose	Start here
Ship a mobile-friendly conversation sidebar with switching, new conversations, archive, delete, and pagination already wired to your chat	Threads Drawer	Set up the Threads Drawer →
Build a custom layout, workflow, permission model, or thread action UI while CopilotKit continues to handle the backend	Headless Threads	Build a custom thread UI →

Threads Drawer

Ship a mobile-friendly conversation sidebar with switching, new conversations, archive, delete, and pagination already wired to your chat.

Set up the Threads Drawer →

Headless Threads

Build a custom layout, workflow, permission model, or thread action UI while CopilotKit continues to handle the backend.

Build a custom thread UI →

Sync existing conversations#

Threads capture new CopilotKit conversations once your app uses Enterprise Intelligence. If you already have persisted Google ADK or LangGraph conversations, follow Import & Synchronize Thread History to synchronize supported history with the same thread store. Keep the native storage and analytics you already use; future CopilotKit-mediated runs continue through native durable persistence when it remains wired while Enterprise Intelligence records the Rich Thread experience. Users can then resume imported and new conversations through the same UI.

CopilotKit Threads are separate from native framework session or checkpoint stores. Your backend can keep a stable mapping when the agent framework also needs its own conversation identifier.

LangGraph thread IDs

CopilotKit passes the active threadId to your LangGraph backend through AG-UI. You can use it directly or persist a mapping to a LangGraph thread or checkpoint identifier. LangGraph Platform thread IDs must be UUIDs.

Next steps#

Understand the architecture: Threads & Persistence Architecture — event replay, live reconnection, synchronization, locking, and lifecycle behavior
Use the hosted platform: Cloud-Hosted Enterprise Intelligence — create and manage the project where your app stores threads and runtime credentials
Plan production self-hosting: Self-Hosting Enterprise Intelligence — work with CopilotKit Engineering to run the Threads platform in your Kubernetes environment
Look up the API: useThreads reference — parameters, lifecycle methods, pagination, and return types