convex-agents-threads_skill

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.