Headless Threads

Configure your Runtime with Enterprise Intelligence#

Your CopilotRuntime must be connected to Enterprise Intelligence before the thread UI can list and resume conversations. If your app came from a CLI starter, this Runtime configuration is generated for you. Otherwise, keep your existing Enterprise Intelligence Runtime configuration while adding the headless UI. Thread names are automatically generated by the LLM after the first message — you can disable this with generateThreadNames: false.

import { CopilotRuntime } from "@copilotkit/runtime";

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  // Thread names are auto-generated by default.
  // Set to false to disable:
  // generateThreadNames: false,

  // Optional: tune thread lock behavior
  // lockTtlSeconds: 20,              // Lock TTL (default 20s, max 3600s)
  // lockHeartbeatIntervalSeconds: 15, // Heartbeat interval (default 15s, max 3000s)
  // lockKeyPrefix: "my-app",          // Custom Redis key prefix for the lock
});

CLI-created starters write the cloud-hosted platform URLs and project-scoped INTELLIGENCE_API_KEY to .env; keep that key server-side. Existing Intelligence-enabled apps should keep their current server-side Runtime configuration. Production self-hosting uses the same React APIs and is deployed with CopilotKit Engineering through Self-Hosting Enterprise Intelligence.

Thread lock options: When an agent run starts, the runtime acquires a lock on the thread to prevent concurrent runs. You can tune this behavior:

List and manage threads with useThreads#

Use the useThreads hook to fetch and manage threads for a specific agent. The hook returns the thread list, loading state, and mutation methods.

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

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

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

  return (
    <div>
      {threads.map((thread) => (
        <div key={thread.id}>
          <span>{thread.name ?? "New conversation"}</span>
          <button onClick={() => renameThread(thread.id, "Renamed")}>
            Rename
          </button>
          <button onClick={() => archiveThread(thread.id)}>
            Archive
          </button>
        </div>
      ))}
    </div>
  );
}

The threads array is sorted by most recently updated first and stays synchronized in realtime — new threads from other tabs or devices appear automatically.

Archive vs. delete: archiveThread is a soft delete — the thread stays in the database but is hidden from the list by default. Pass includeArchived: true to show archived threads. deleteThread is permanent and irreversible. Neither has a built-in confirmation dialog — add your own if needed.

Switch between threads#

When a user selects a thread, pass its threadId to your chat component. The chat clears the current messages, fetches the selected thread's history, and replays it. If the agent is still running on that thread, the chat picks up the live stream.

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

function App() {
const [activeThreadId, setActiveThreadId] = useState<string | undefined>();

  return (
    <div className="flex">
      <ThreadSidebar onSelectThread={setActiveThreadId} />
      <CopilotChat threadId={activeThreadId} /> {}
    </div>
  );
}

When threadId changes, the chat component automatically loads the selected thread's history and reconnects to the agent's stream. If the agent is still running on that thread, the chat picks up the live stream.

Add pagination for large thread lists#

For users with many conversations, use the limit parameter to enable cursor-based pagination.

const {
  threads,
  hasMoreThreads,
  isFetchingMoreThreads,
  fetchMoreThreads,
} = useThreads({
  agentId: "my-agent",
  limit: 20, 
});

// In your JSX:
{hasMoreThreads && (
  <button
    onClick={fetchMoreThreads}
    disabled={isFetchingMoreThreads}
  >
    {isFetchingMoreThreads ? "Loading..." : "Load more"}
  </button>
)}