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.
When & Why to Use This Skill
The Convex Agents Messages skill provides a robust framework for managing the lifecycle of AI agent conversations. It enables developers to seamlessly save, retrieve, and organize message histories, while offering specialized support for UIMessages to ensure rich, real-time rendering and optimized user experiences in agent-driven applications.
Use Cases
- Developing persistent chat interfaces that maintain full conversation context across multiple user sessions.
- Implementing optimistic UI updates to display user prompts instantly while backend processing occurs, reducing perceived latency.
- Filtering complex message histories to distinguish between internal tool executions and user-facing responses for cleaner UI presentation.
- Managing data privacy and storage by programmatically deleting specific message ranges or entire conversation threads.
| name | "Convex Agents Messages" |
|---|---|
| description | "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." |
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