Headless Threads

Build a custom thread UI with useThreads while CopilotKit handles persistence, replay, synchronization, and lifecycle infrastructure.

What is this?

CopilotKit Rich Threads enable persistent, resumable multi-turn conversations. The useThreads composable lists, creates, renames, archives, and deletes CopilotKit Intelligence threads with realtime synchronization. Threads work with any agent framework because CopilotKit Intelligence stores conversation history server-side, so users can close their browser and pick up where they left off. It does not list or mutate native LangGraph, ADK, or other framework stores unless your backend explicitly bridges those systems.

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.

Prebuilt thread UI: Threads Drawer

If your app came from a CopilotKit CLI starter, it may already include the prebuilt Threads Drawer. Keep it for the shortest path to a production thread switcher. Use the useThreads steps below when adding custom thread UI or replacing the Drawer with your own layout and interactions, including thread rename.

When should I use this?

  • Your app needs multiple saved conversations per user, like a chat-history sidebar.
  • Users should be able to resume a prior conversation across sessions or devices.
  • You want realtime sync so threads created on one tab appear on another.
  • You need to let users organize conversations by renaming or archiving them.

Prerequisites

  • A CopilotKit application connected to CopilotKit Intelligence, cloud-hosted or self-hosted
  • The current @copilotkit/vue v2 package
  • A model provider key supported by your runtime

For multi-user applications, configure the runtime to scope Rich Threads to the signed-in user before exposing thread lists or lifecycle actions.

Implementation

Configure your Runtime with CopilotKit Intelligence

Your CopilotRuntime must be connected to CopilotKit Intelligence before the thread UI can list and resume conversations. CLI-created starters generate this setup; otherwise follow Connect your runtime to Intelligence.

server.ts
import {
  CopilotKitIntelligence,
  CopilotRuntime,
} from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: { default: agent },
  intelligence: new CopilotKitIntelligence({
    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
  }),
  identifyUser: async (request) => {
    const session = await verifyAppSession(request);
    if (!session?.user) throw new Error("Unauthorized");
    return { id: session.user.id, name: session.user.name };
  },
  // Each new thread is named from its first user message.
  // For a short title from a model, pass { model: "openai/gpt-5-mini" }.
  // Set to false to disable:
  // generateThreadNames: false,
  // lockTtlSeconds: 20,
  // lockHeartbeatIntervalSeconds: 15,
  // lockKeyPrefix: "my-app",
});

Keep the project-scoped CPK_INTELLIGENCE_API_KEY on the server. Existing Intelligence-enabled apps should retain their current runtime configuration.

OptionDefaultMaxDescription
lockTtlSeconds203600How long a run lock is held before it expires.
lockHeartbeatIntervalSeconds153000How often the runtime renews the lock.
lockKeyPrefixNoneNoneOptional Redis prefix when several apps share one instance.

List and manage threads with useThreads

useThreads returns reactive refs for the thread list and loading state, plus mutation methods. The useThreads reference lists every parameter and return value.

src/components/ThreadSidebar.vue
<script setup lang="ts">
import {
  useCopilotChatConfiguration,
  useThreads,
} from "@copilotkit/vue/v2";

const config = useCopilotChatConfiguration();
const {
  threads,
  isLoading,
  renameThread,
  archiveThread,
  deleteThread,
} = useThreads({ agentId: "my-agent" });
</script>

<template>
  <p v-if="isLoading">Loading…</p>
  <ul v-else>
    <li v-for="thread in threads" :key="thread.id">
      <button
        @click="config?.setActiveThreadId(thread.id, { explicit: true })"
      >
        {{ thread.name ?? "New conversation" }}
      </button>
      <button @click="renameThread(thread.id, 'Renamed')">Rename</button>
      <button @click="archiveThread(thread.id)">Archive</button>
      <button @click="deleteThread(thread.id)">Delete</button>
    </li>
  </ul>
</template>
  • threads is sorted by recent activity and stays synchronized in realtime.
  • archiveThread hides a thread from the default list. Pass includeArchived: true to list archived threads.
  • deleteThread removes a thread permanently.

Neither method asks the user to confirm, so add a confirmation dialog where you need one.

Switch between threads

Keep the list and chat inside one CopilotChatConfigurationProvider. Selecting a row with setActiveThreadId(..., { explicit: true }) clears the current view, connects the chat to the selected thread, and replays its history. If a run is still active, the chat rejoins its stream. For how replay and sync work, see Threads & Persistence Architecture.

src/App.vue
<script setup lang="ts">
import {
  CopilotChat,
  CopilotChatConfigurationProvider,
  CopilotKitProvider,
} from "@copilotkit/vue/v2";
import ThreadSidebar from "./components/ThreadSidebar.vue";
</script>

<template>
  <CopilotKitProvider runtime-url="/api/copilotkit">
    <CopilotChatConfigurationProvider agent-id="my-agent">
      <div class="flex" style="height: 100dvh">
        <ThreadSidebar />
        <CopilotChat />
      </div>
    </CopilotChatConfigurationProvider>
  </CopilotKitProvider>
</template>
ADK sessions

An ADK backend can map the AG-UI threadId to an ADK session id. Durable ADK persistence still requires a durable ADK session service. useThreads manages CopilotKit Intelligence records, not ADK's native session store.

Click a thread in the sidebar. The chat clears and shows the messages of that thread.

Add pagination for large thread lists

Pass limit for cursor-based pagination and render fetchMoreThreads while more pages remain:

<script setup lang="ts">
const {
  threads,
  hasMoreThreads,
  isFetchingMoreThreads,
  fetchMoreThreads,
} = useThreads({ agentId: "my-agent", limit: 20 });
</script>

<template>
  <button
    v-if="hasMoreThreads"
    :disabled="isFetchingMoreThreads"
    @click="fetchMoreThreads"
  >
    {{ isFetchingMoreThreads ? "Loading…" : "Load more" }}
  </button>
</template>
Migrating existing history?

Threads capture new CopilotKit conversations once your app is connected to CopilotKit Intelligence. To move historical Google ADK or LangGraph conversations into the same store, start with Import & Synchronize Thread History, or the framework-specific synchronization guide.

How is this guide?