useThreads

Overview

useThreads is a Vue 3 composable for reading the active thread list for an agent and mutating that list from the client. It accepts reactive inputs for a required agent id, archived filter, page size, and an enabled flag. When enabled is false, the hook clears its thread-store context and skips /threads entirely; that is how the threads drawer stays idle while unlicensed.

useThreads activates when the connected runtime provides the thread endpoints it needs. It stays idle when the runtime explicitly reports that thread listing is unavailable.

The hook returns normalized thread records with only the fields the Vue UI consumes: id, agentId, name, archived, createdAt, updatedAt, and optional lastRunAt. Threads are ordered by lastRunAt, then updatedAt, then createdAt.

Signature

import { useThreads } from "@copilotkit/vue/v2";

function useThreads(input: UseThreadsInput): UseThreadsResult;

Parameters

Return Value

Usage

Listing threads

<script setup lang="ts">
import { computed } from "vue";
import { useThreads } from "@copilotkit/vue/v2";

const { threads, isLoading, listError, refetchThreads } = useThreads({
  agentId: "support-agent",
  includeArchived: true,
  limit: 20,
});

const activeThreads = computed(() =>
  threads.value.filter((thread) => !thread.archived),
);
</script>

Paginating manually

<script setup lang="ts">
import { useThreads } from "@copilotkit/vue/v2";

const { hasMoreThreads, fetchMoreThreads, fetchMoreError } = useThreads({
  agentId: "support-agent",
  limit: 20,
});
</script>

Behavior

• The hook stays reactive to agentId, includeArchived, limit, and enabled.
• When the runtime URL is missing or the runtime reports thread endpoints as unsupported, error is set and listError stays focused on store failures.
• enabled: false clears the thread-store context and skips /threads; that is what keeps unlicensed thread drawers from fetching.
• Mutations are optimistic in the core store. Delete rolls back if the request fails.
• fetchMoreError is tracked separately so a failed "load more" request can show inline without losing the loaded list.
• Threads are sorted by lastRunAt, then updatedAt, then createdAt.

Related