convex-agents-messages

Sstobo's avatarfrom Sstobo

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.

⭐5stars🔀0forks📁View on GitHub🕐Updated Oct 18, 2025⬇️2downloads

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