useThreads

React hook for listing, managing, and syncing conversation threads with useThreads. Rename, archive, delete, and paginate threads with realtime updates via WebSocket.

useThreads needs a CopilotKit Intelligence projectCreate a cloud-hosted project or connect a self-hosted deployment to start syncing threads.Create a free account

Overview

Intelligence’s AG-UI streams provide the event history and delivery behind these conversations. For the event replay model, see AG-UI Streams & Framework Threads. Use useThreads to manage the conversation list, then pass the selected threadId to your chat. Your framework keeps its own conversation and model-context management.

useThreads is a React hook for managing conversation threads in CopilotKit Intelligence. It fetches the thread list for a given agent, keeps it synchronized in realtime via WebSocket, and exposes mutation methods for renaming, archiving, and deleting threads.

Threads are sorted by the most recent run (lastRunAt), then by updatedAt for threads that have not run. The hook supports cursor-based pagination when a limit is provided.

For a full thread sidebar, see Headless Threads.

useThreads only activates when the connected runtime advertises compatible REST thread endpoints. Cloud-hosted Intelligence provides those endpoints for thread metadata and realtime updates. A self-managed runner, such as AgentRunner, SqliteAgentRunner, or a custom runner, can persist and replay chat history. It does not provide the thread list, the thread mutations, or the realtime updates that useThreads needs.

Signature

import { useThreads } from "@copilotkit/react-core/v2";

function useThreads(input: UseThreadsInput): UseThreadsResult

Parameters

Prop

Type

Return Value

Prop

Type

Usage

ThreadList.tsx
import { useThreads } from "@copilotkit/react-core/v2";

function ThreadList() {
  const {
    threads,
    isLoading,
    renameThread,
    archiveThread,
    deleteThread,
  } = useThreads({ agentId: "my-agent" });

  if (isLoading) return <div>Loading threads...</div>;

  return (
    <ul>
      {threads.map((thread) => (
        <li key={thread.id}>
          <span>{thread.name ?? "Untitled"}</span>
          <button onClick={() => renameThread(thread.id, "New name")}>
            Rename
          </button>
          <button onClick={() => archiveThread(thread.id)}>Archive</button>
          <button onClick={() => deleteThread(thread.id)}>Delete</button>
        </li>
      ))}
    </ul>
  );
}

Behavior

  • On mount, fetches the thread list and establishes a realtime WebSocket subscription.
  • If the runtime does not advertise thread endpoints, no /threads request is made and error explains that thread endpoints are unavailable.
  • Thread creates, renames, archives, and deletes from any client are reflected immediately without polling.
  • Mutations update the list at once (optimistic). If the server rejects a delete, the thread comes back and error is set. Rename, archive, and unarchive do not roll back. The promises resolve on server confirmation and reject on failure.
  • The error state updates with the most recent error from any operation.
  • The threads array is sorted by the most recent run (lastRunAt), then by updatedAt for threads that have not run.
  • New threads are automatically named when their first run creates them. By default, the name is the first user message. To get a short summary title from a model, set generateThreadNames: { model } on the runtime.

How is this guide?