home / skills / sstobo / convex-skills / convex-agents-threads

convex-agents-threads skill

safe

This skill helps organize multi-turn conversations by managing user threads, histories, and metadata for coherent interactions.

npx playbooks add skill sstobo/convex-skills --skill convex-agents-threads

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
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

```typescript
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:

```typescript
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

```typescript
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

```typescript
// 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

Overview

This skill manages conversation threads to group messages into linear histories for agents. It creates, continues, lists, and deletes threads while maintaining per-user association and thread metadata. Use it to organize multi-turn conversations, keep ordered message history, and control lifecycle operations. It supports both async and atomic (sync) deletion patterns.

How this skill works

The skill exposes APIs to create new threads with title and summary metadata and to associate them with a userId. You can continue a thread inside actions to access metadata and generate text responses tied to that thread. It provides queries to list threads by user and mutations to delete threads asynchronously or synchronously. Messages appended to a thread maintain ordering so histories stay consistent.

When to use it

Start a new conversation for a user and persist its context.
Manage per-user conversation history and thread-level metadata (title, summary).
Continue an existing multi-turn conversation and generate responses within that thread.
List or paginate threads for a user to display conversation histories.
Clean up old or completed conversations with async or atomic deletion.

Best practices

Associate every thread with a userId for clear ownership and retrieval.
Use title and summary fields to surface meaningful conversation labels in UIs.
Prefer async deletion for background cleanup and sync deletion for operations that require immediate consistency.
Keep messages ordered within a thread to preserve conversation semantics and make replay reliable.
Paginate thread listings to avoid loading large histories at once.

Example use cases

Create a new support conversation when a user opens a chat and store its threadId for subsequent messages.
Continue a sales assistant thread to pick up prior context and generate follow-up messages based on thread metadata.
List recent threads for a user to show their chat history in an application inbox.
Delete all threads for a departing user using an async cleanup job, or synchronously remove them during data removal requests.
Query a thread within an action to read its metadata and produce a context-aware response.

FAQ

Can threads be tied to non-user contexts?

Threads are designed to associate with userId, but you can include contextual identifiers in metadata to group by context beyond the primary user association.

When should I use async vs sync deletion?

Use async deletion for non-blocking background cleanup. Use sync deletion when you need atomic removal and immediate consistency, for example during data deletion requests.