AG-UI Streams & Framework Threads

Understand how Intelligence’s AG-UI streams deliver conversation history, catch-up, and reconnection alongside framework-managed agent context.

Conversations that never lose context.

Open your coding agent in your project's folder, or in an empty folder for a new app.

CopilotKit Intelligence AG-UI Streams keep messages, generative UI, and tool activity available across sessions and devices. Build a new agent or bring one you already have. Any frontend, any backend.

Overview

Intelligence records each conversation as AG-UI events. A user can reopen a thread, catch up after a disconnect, and see the same thread list in every tab. To choose between the prebuilt Drawer and a custom headless UI, start with the AG-UI Streams overview.

What are threads?

Framework threads manage an agent’s conversation and model context. Intelligence’s AG-UI streams record and deliver the interaction to your users.

A CopilotKit threadId identifies the conversation whose AG-UI events Intelligence stores and replays. Use useThreads or CopilotThreadsDrawer to list and select conversations, then pass the selected threadId to your chat.

ConceptResponsibility
Framework thread or ADK sessionAgent conversation, model context, and framework-specific execution state.
Intelligence’s AG-UI streamRecorded interaction events, replay, catch-up, and delivery to connected clients.
Channel threadThe native Slack or Microsoft Teams conversation.

Model-context compaction and user-visible history serve different purposes. Intelligence records the AG-UI events delivered through it independently of the framework’s context store. Replay uses those recorded events; this separation does not imply unlimited retention or recovery of history that was never recorded.

How threads work with framework storage

Starting fresh? CopilotKit Intelligence provides conversation persistence: it stores interaction events so users can reopen rich conversations across sessions and devices, reconnect to active runs, and manage their threads.

Keep your existing thread system when you connect Intelligence. As conversations run through your connected CopilotKit runtime, Intelligence automatically records its own copy of the supported AG-UI interaction history. Your framework continues managing the original conversation and agent state. Keep your durable LangGraph checkpointer or deployment configured. For ADK, keep your durable session service configured. Replaying recorded AG-UI history does not resume framework execution from a checkpoint. Your framework still handles that recovery.

Keep the same thread ID, or a stable mapping to the native thread or session ID, when you continue a conversation. Bring your own thread system explains what Intelligence records and shows an existing LangGraph app example.

Historical import is optional. It copies supported history and does not create a general replication link between databases. Intelligence rename, archive, and delete actions affect only its own records.

Key concepts

Thread vs. Run

A thread is the durable container. A run is a single agent execution within that thread. One thread can have many runs. Each time the user sends a message and the agent responds, that is a new run, and the thread accumulates events across all of its runs.

How the pieces fit together

From a developer's perspective, threads involve three things:

What you useWhat it does
Frontend thread APILists, renames, archives, and deletes threads. Supports pagination and stays in sync across tabs and devices via WebSocket.
CopilotChat with threadIdConnects to a specific thread, loads its history, and streams new events in realtime.
CopilotRuntimeServer-side layer that executes agents, stores thread data in CopilotKit Intelligence, and relays events to connected clients.

You interact with the first two. The runtime and platform handle persistence and sync behind the scenes.

To wire these pieces into a custom chat UI, follow Headless Threads.

Auto-naming

When the first run creates a thread, the runtime gives the thread a name. By default, the name is the first user message, cut to 8 words. No model runs for this.

For a short summary title (2 to 5 words), give the runtime a model:

const runtime = new CopilotRuntime({
  agents,
  intelligence,
  identifyUser: async (request) => resolveUser(request),
  generateThreadNames: { model: "openai/gpt-5-mini" },
});

The runtime calls this model once per new thread, with no tools. If the call fails, the runtime uses the first user message. The runtime never runs your agent to name a thread, because your agent's own tools could run and change app data.

Naming runs asynchronously, so it does not block thread creation or the agent's response. The name appears through the frontend thread API via realtime sync.

Auto-naming is on by default. Turn it off with generateThreadNames: false on the runtime. Users can always change the name with renameThread().

Archive vs. delete

Threads support two removal operations with different semantics:

  • Archive is a soft delete. The thread remains stored but disappears from the default list. Show archived threads by setting includeArchived: true in the frontend thread API. Threads can also be unarchived, which restores them to the active list.
  • Delete is permanent and irreversible. The thread and its history are removed entirely.

Neither operation has a built-in confirmation dialog, so your application should implement its own if needed.

How it works

The client-side steps (minting a threadId, hydrating history on load, and switching or starting threads) live in Thread & History Lifecycle.

Persistence and replay

As an agent runs, the runtime writes each event (messages, tool calls, and state updates) to the thread in CopilotKit Intelligence. Intelligence persists AG-UI events and constructs a replay for returning clients. A reconnecting client can use its replay cursor to catch up on missed events.

When a client opens an existing thread, the Runtime provides connection credentials. The frontend joins the event stream and receives the recorded history. If a run is active, new events continue over the same connection after replay. If a tool call from a previous thread completes while the client is switching away, its result is discarded rather than inserted into the new thread, so stale output never leaks between conversations.

Background execution

A browser disconnect does not by itself stop the authoritative agent run. While your Runtime and agent remain running, execution can continue and Intelligence records its events. Reopening the conversation lets the user catch up. This does not replace the framework’s checkpoint recovery or recover a run after a Runtime failure.

Realtime sync

The frontend thread client maintains a WebSocket subscription for thread metadata changes. When any client creates, renames, archives, or deletes a thread, the update is pushed to all connected clients automatically. This is how a thread created on one tab appears in the sidebar on another tab without polling.

Optimistic updates

Thread mutations (rename, archive, unarchive, delete) update the thread list at once, before the server answers:

  • If the server rejects a delete, the thread comes back in the list and the error is set.
  • Rename, archive, and unarchive do not roll back. A realtime update or the next list fetch shows the server state.
  • The returned promise resolves when the server accepts the request, and rejects on failure.

Error handling

Mutation failures

All mutation methods (renameThread, archiveThread, deleteThread) return promises that reject with an Error if the server cannot complete the operation. Common causes:

  • Network failure. The client can't reach the runtime.
  • Thread not found. Another client deleted the thread before your mutation arrived.
  • Authorization failure. The user doesn't have permission to modify the thread.

The thread client exposes the most recent list or mutation error and clears it after the next successful operation.

WebSocket disconnection

If the WebSocket connection drops (network change, server restart, laptop sleep):

  • Thread list. The frontend thread API stops receiving realtime updates, so the list becomes stale until the connection is re-established. Reconnection is automatic with exponential backoff.
  • Active conversation. If CopilotChat loses its WebSocket mid-run, the agent's output may be interrupted. Reloading the page, or switching away and back to the thread, triggers the reconnection flow, which replays any missed events.

Thread locked

If a thread already has an active run and another client tries to start a new run on the same thread, the request is rejected with a 409 Conflict. This prevents two agent runs from interleaving events on the same thread. The existing run must complete or be stopped before a new one can begin.

The runtime acquires a Redis-backed lock on the thread for the duration of each run. You can tune this behavior on the runtime:

OptionDefaultMaxDescription
lockTtlSeconds203600 (1 hour)How long the lock is held before it expires automatically.
lockHeartbeatIntervalSeconds153000 (50 min)How often the runtime renews the lock during a run. The heartbeat always runs; you only need to adjust the interval.
lockKeyPrefixNoneNoneCustom Redis key prefix for the thread lock. Useful when multiple apps share a Redis instance.

If a run completes normally, the lock is released immediately. The TTL is a safety net for cases where the runtime crashes without releasing the lock.

Design decisions

Why event replay instead of message snapshots?

Intelligence records AG-UI events rather than relying only on the framework’s current message list. This enables:

  • Catch-up. A reconnecting client can use its replay cursor to fetch missed events rather than reloading the entire history.
  • Interactive history. Recorded messages, tool calls, and state updates reconstruct the conversation. Replay may compact events for delivery; it is not a guarantee that every original event is sent unchanged.

The trade-off is that replay is more complex than loading a message array.

When threads are the wrong tool

  • Ephemeral interactions. If your users don't need conversation history (e.g., a one-shot Q&A widget), threads add unnecessary complexity. Use CopilotChat without a threadId.
  • Client-only state. If you need local-only chat history without server persistence, manage messages in frontend state or localStorage instead.

How is this guide?