useThreads

Overview

useThreads is a React hook for managing conversation threads on the Enterprise Intelligence Platform. 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 most recently updated first. The hook supports cursor-based pagination when a limit is provided.

useThreads only activates when the connected runtime advertises compatible REST thread endpoints. Managed Enterprise Intelligence provides those endpoints for durable thread metadata and realtime updates. Self-managed runner persistence, such as AgentRunner, SqliteAgentRunner, or a custom runner, can still persist and replay chat history, but it does not automatically provide the managed useThreads list/mutation/realtime contract.

Signature

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

function useThreads(input: UseThreadsInput): UseThreadsResult

Parameters

Return Value

Usage

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.
• All mutation methods use pessimistic updates — the UI updates only after the server confirms the operation via WebSocket, not immediately on dispatch. Promises resolve on confirmation (15-second timeout) and reject on failure.
• The error state updates with the most recent error from any operation.
• The threads array stays sorted by updatedAt descending (most recent first).
• New threads are automatically named by the LLM after their first run (2–5 word title). This is configurable via generateThreadNames on the runtime.

Next steps

• Thread architecture: Threads & Persistence Architecture — event replay model and WebSocket sync
• Step-by-step guide: Threads — set up thread management in your app