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.
Stars
23
Forks
4
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
typescript
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
typescript
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
typescript
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:
typescript
const sendMessage = useMutation(api.chat.generateResponse).withOptimisticUpdate(
optimisticallySendMessage(api.messages.listThreadMessages)
);
Delete Messages
typescript
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:
typescript
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
Didn't find tool you were looking for?