Agent skill
Convex Agents Messages
Sends, saves, retrieves, and manages messages within agent conversations. Use this when handling user messages, displaying conversation history, and working with UIMessages for rich rendering.
Install this agent skill to your Project
npx add-skill https://github.com/Sstobo/convex-skills/tree/main/convex-agents-messages
SKILL.md
Purpose
Messages represent individual exchanges in a conversation thread. This skill covers saving, retrieving, displaying, and managing messages.
When to Use This Skill
- Displaying conversation history to users
- Saving user messages before generating responses
- Implementing optimistic message updates in UI
- Working with UIMessages for rich formatting
- Filtering tool messages from displayed history
Retrieve Messages
import { listUIMessages } from "@convex-dev/agent";
export const listThreadMessages = query({
args: { threadId: v.string(), paginationOpts: paginationOptsValidator },
handler: async (ctx, { threadId, paginationOpts }) => {
return await listUIMessages(ctx, components.agent, {
threadId,
paginationOpts,
});
},
});
Display in React
import { useUIMessages } from "@convex-dev/agent/react";
function ChatComponent({ threadId }: { threadId: string }) {
const { results } = useUIMessages(
api.messages.listThreadMessages,
{ threadId },
{ initialNumItems: 20 }
);
return (
<div>
{results?.map((message) => (
<div key={message.key}>{message.text}</div>
))}
</div>
);
}
Save a Message Manually
import { saveMessage } from "@convex-dev/agent";
export const saveUserMessage = mutation({
args: { threadId: v.string(), prompt: v.string() },
handler: async (ctx, { threadId, prompt }) => {
const { messageId } = await saveMessage(ctx, components.agent, {
threadId,
prompt,
skipEmbeddings: true,
});
return { messageId };
},
});
Optimistic Updates
Show messages immediately before they're saved:
const sendMessage = useMutation(api.chat.generateResponse).withOptimisticUpdate(
optimisticallySendMessage(api.messages.listThreadMessages)
);
Delete Messages
await myAgent.deleteMessage(ctx, { messageId });
await myAgent.deleteMessages(ctx, { messageIds });
await myAgent.deleteMessageRange(ctx, { threadId, startOrder, endOrder });
UIMessage Type
Extended message with agent-specific fields:
interface UIMessage {
key: string;
role: "user" | "assistant" | "system";
text: string;
status: "saved" | "streaming" | "finished" | "aborted";
agentName?: string;
_creationTime?: Date;
parts?: MessagePart[];
}
Key Principles
- UIMessages vs MessageDocs: Use UIMessages for UI, MessageDocs for backend
- Message ordering: Maintained automatically by order and stepOrder
- Optimistic updates: Better UX showing messages before save
- Skip embeddings in mutations: Use when saving in mutations
Next Steps
- See streaming for real-time message updates
- See files for attaching media to messages
- See threads for managing message containers
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?