Agent skill
Convex Agents Threads
Manages conversation threads to group messages into linear histories. Use this when organizing multi-turn conversations, managing per-user history, and handling thread metadata.
Install this agent skill to your Project
npx add-skill https://github.com/Sstobo/convex-skills/tree/main/convex-agents-threads
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
Sstobo/convex-skills
Convex Agents Streaming
Streams agent responses in real-time to clients without blocking. Use this for responsive UIs, long-running generations, and asynchronous streaming to multiple clients.
Sstobo/convex-skills
Convex Agents Files
Handles file uploads, image attachments, and media processing in agent conversations. Use this when agents analyze images, process documents, or generate files.
Sstobo/convex-skills
convex-actions-general
This skill should be used when working with Convex actions, HTTP endpoints, validators, schemas, environment variables, scheduling, file storage, and TypeScript patterns. It provides comprehensive guidelines for function definitions, API design, database limits, and advanced Convex features.
Sstobo/convex-skills
betterauth-tanstack-convex
Step-by-step guide for setting up Better Auth authentication with Convex and TanStack Start. This skill should be used when configuring authentication in a Convex + TanStack Start project, troubleshooting auth issues, or implementing sign up/sign in/sign out flows. Covers installation, environment variables, SSR authentication, route handlers, and the expectAuth pattern.
Sstobo/convex-skills
Convex Agents Tools
Enables agents to call external functions, APIs, and database operations through tool definitions. Use this when agents need to fetch data, perform actions, or integrate with external services while maintaining clean separation.
Sstobo/convex-skills
convex-queries
This skill should be used when implementing Convex query functions. It provides comprehensive guidelines for defining, registering, calling, and optimizing queries, including pagination, full text search, and indexing patterns.
Didn't find tool you were looking for?