useThreads
React hook for listing, managing, and syncing conversation threads with useThreads. Rename, archive, delete, and paginate threads with realtime updates via WebSocket.
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): UseThreadsResultParameters
Prop
Type
Return Value
Prop
Type
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
/threadsrequest is made anderrorexplains 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
erroris set. Rename, archive, and unarchive do not roll back. The promises resolve on server confirmation and reject on failure. - The
errorstate updates with the most recent error from any operation. - The
threadsarray is sorted by the most recent run (lastRunAt), then byupdatedAtfor 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?