convex-agents-threads

Sstobo's avatarfrom Sstobo

Manages conversation threads to group messages into linear histories. Use this when organizing multi-turn conversations, managing per-user history, and handling thread metadata.

⭐5stars🔀0forks📁View on GitHub🕐Updated Oct 18, 2025⬇️1downloads

When & Why to Use This Skill

Convex Agents Threads is a specialized skill designed to manage persistent conversation histories and multi-turn interactions for AI agents. It enables developers to organize messages into structured, linear threads, manage per-user metadata, and maintain long-term context, ensuring seamless and coherent user experiences across multiple sessions.

Use Cases

  • Case 1: Building persistent AI chatbots that require consistent memory of user interactions across different sessions.
  • Case 2: Organizing complex agent workflows by grouping related tasks and messages into distinct, searchable threads with custom metadata.
  • Case 3: Implementing user-specific conversation dashboards that allow users to list, resume, or delete their chat histories.
  • Case 4: Managing large-scale agent deployments where efficient, non-blocking thread cleanup is required for data privacy and storage optimization.
name"Convex Agents Threads"
description"Manages conversation threads to group messages into linear histories. Use this when organizing multi-turn conversations, managing per-user history, and handling thread metadata."

Purpose

Threads group related messages into organized, linear conversation histories. Every message in the Agent component belongs to a thread.

When to Use This Skill

  • Creating new conversations for users
  • Managing conversation history and metadata
  • Continuing existing conversations
  • Querying message history within a thread
  • Organizing conversations by user or context
  • Cleaning up old or completed conversations

Create a Thread

import { createThread } from "@convex-dev/agent";

export const startNewThread = mutation({
  args: { userId: v.string() },
  handler: async (ctx, { userId }) => {
    const threadId = await createThread(ctx, components.agent, {
      userId,
      title: "New Conversation",
      summary: "Conversation summary",
    });
    return { threadId };
  },
});

Continue a Thread (Actions Only)

In actions, get a thread object:

export const continueConversation = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { thread } = await myAgent.continueThread(ctx, { threadId });

    const metadata = thread.getMetadata();
    const response = await thread.generateText({ prompt });

    return response.text;
  },
});

List Threads for a User

export const getUserThreads = query({
  args: { userId: v.string(), paginationOpts: paginationOptsValidator },
  handler: async (ctx, { userId, paginationOpts }) => {
    return await ctx.runQuery(
      components.agent.threads.listThreadsByUserId,
      { userId, paginationOpts }
    );
  },
});

Delete Threads

// Async deletion (non-blocking)
await myAgent.deleteThreadAsync(ctx, { threadId });

// Sync deletion (atomic)
await myAgent.deleteThreadSync(ctx, { threadId });

// Delete all for user
await ctx.runMutation(components.agent.users.deleteAllForUserId, { userId });

Key Principles

  • User association: Threads associated with userId
  • Metadata: Use title and summary for organization
  • Message ordering: Messages within thread maintain order
  • Async vs sync: Use async for non-blocking, sync for atomic ops

Next Steps

  • See messages for saving and retrieving messages
  • See fundamentals for basic agent setup