convex-agents-messages

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