Convex Agents Messages

目的

メッセージは、会話スレッド内の個々のやり取りを表します。このスキルでは、メッセージの保存、取得、表示、管理について説明します。

このスキルを使用する場面

• 会話履歴をユーザーに表示する
• 応答を生成する前にユーザーメッセージを保存する
• UI に楽観的なメッセージ更新を実装する
• リッチな書式設定に UIMessages を使用する
• 表示する履歴からツールメッセージを除外する

メッセージを取得する

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,
    });
  },
});

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>
  );
}

メッセージを手動で保存する

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 };
  },
});

楽観的な更新

保存前にメッセージをすぐに表示します：

const sendMessage = useMutation(api.chat.generateResponse).withOptimisticUpdate(
  optimisticallySendMessage(api.messages.listThreadMessages)
);

メッセージを削除する

await myAgent.deleteMessage(ctx, { messageId });
await myAgent.deleteMessages(ctx, { messageIds });
await myAgent.deleteMessageRange(ctx, { threadId, startOrder, endOrder });

UIMessage 型

エージェント固有のフィールドを含む拡張メッセージです：

interface UIMessage {
  key: string;
  role: "user" | "assistant" | "system";
  text: string;
  status: "saved" | "streaming" | "finished" | "aborted";
  agentName?: string;
  _creationTime?: Date;
  parts?: MessagePart[];
}

主な原則

• UIMessages と MessageDocs：UI には UIMessages を、バックエンドには MessageDocs を使用します
• メッセージの順序：order と stepOrder によって自動的に維持されます
• 楽観的な更新：保存前にメッセージを表示することで UX が向上します
• ミューテーションでの埋め込みのスキップ：ミューテーションで保存する際に使用します

次のステップ

• リアルタイムのメッセージ更新についてはストリーミングを参照してください
• メッセージへのメディアの添付についてはファイルを参照してください
• メッセージコンテナの管理についてはスレッドを参照してください