Convex Agents Threads

目的

スレッドは、関連するメッセージを整理された時系列の会話履歴にまとめます。Agent コンポーネント内のすべてのメッセージは、いずれかのスレッドに属します。

このスキルを使う場面

• ユーザー向けの新しい会話を作成する
• 会話履歴とメタデータを管理する
• 既存の会話を続ける
• スレッド内のメッセージ履歴を照会する
• ユーザーまたはコンテキストごとに会話を整理する
• 古い会話や完了した会話を整理する

スレッドを作成する

import { createThread } from "@convex-dev/agent";

export const startNewThread = mutation({
  args: { userId: v.string() },
  handler: async (ctx, { userId }) => {
    const threadId = await createThread(ctx, components.agent, {
      userId,
      title: "New Conversation",
      summary: "Conversation summary",
    });
    return { threadId };
  },
});

スレッドを続ける（アクションのみ）

アクション内で、スレッドオブジェクトを取得します。

export const continueConversation = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { thread } = await myAgent.continueThread(ctx, { threadId });

    const metadata = thread.getMetadata();
    const response = await thread.generateText({ prompt });

    return response.text;
  },
});

ユーザーのスレッド一覧を取得する

export const getUserThreads = query({
  args: { userId: v.string(), paginationOpts: paginationOptsValidator },
  handler: async (ctx, { userId, paginationOpts }) => {
    return await ctx.runQuery(
      components.agent.threads.listThreadsByUserId,
      { userId, paginationOpts }
    );
  },
});

スレッドを削除する

// Async deletion (non-blocking)
await myAgent.deleteThreadAsync(ctx, { threadId });

// Sync deletion (atomic)
await myAgent.deleteThreadSync(ctx, { threadId });

// Delete all for user
await ctx.runMutation(components.agent.users.deleteAllForUserId, { userId });

主な原則

• ユーザーとの関連付け：スレッドは userId に関連付けられます
• メタデータ：整理にはタイトルと概要を使用します
• メッセージの順序：スレッド内のメッセージは順序を維持します
• 非同期と同期：ブロッキングを避ける場合は非同期を、アトミックな操作には同期を使用します

次のステップ

• メッセージの保存と取得については、messages を参照してください
• 基本的なエージェントのセットアップについては、fundamentals を参照してください