Convex Agents Context

目的

デフォルトでは、エージェントは最近のメッセージをコンテキストとして含めます。このスキルでは、スレッドをまたいだ検索、メモリの注入、要約、フィルタリングなど、高度なパターンに合わせてその動作をカスタマイズする方法を説明します。

このスキルを使う場面

• トークンの上限超過を防ぐため、コンテキストウィンドウを制限する
• 関連するコンテキストを複数のスレッドにまたがって検索する
• メモリやユーザープロファイルをすべてのプロンプトに注入する
• 長い会話を要約してから続ける
• 機密性の高いメッセージや関連性のないメッセージを除外する
• LLM をガイドするための少数の例を追加する

デフォルトのコンテキストオプションを設定する

const myAgent = new Agent(components.agent, {
  name: "My Agent",
  languageModel: openai.chat("gpt-4o-mini"),
  contextOptions: {
    recentMessages: 50,
    excludeToolMessages: true,
    searchOptions: {
      limit: 10,
      textSearch: true,
      vectorSearch: false,
    },
  },
});

呼び出しごとにコンテキストを上書きする

export const generateWithCustomContext = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const result = await myAgent.generateText(
      ctx,
      { threadId },
      { prompt },
      {
        contextOptions: {
          recentMessages: 20,
          searchOptions: {
            limit: 5,
            textSearch: true,
            vectorSearch: true,
          },
        },
      }
    );

    return result.text;
  },
});

スレッドをまたいで検索する

export const generateWithCrossThreadContext = action({
  args: { threadId: v.string(), userId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, userId, prompt }) => {
    const result = await myAgent.generateText(
      ctx,
      { threadId, userId },
      { prompt },
      {
        contextOptions: {
          searchOtherThreads: true,
          searchOptions: {
            limit: 15,
            textSearch: true,
            vectorSearch: true,
          },
        },
      }
    );

    return result.text;
  },
});

カスタムコンテキストハンドラー

コンテキストを完全にカスタマイズします。

const myAgent = new Agent(components.agent, {
  name: "My Agent",
  languageModel: openai.chat("gpt-4o-mini"),
  contextHandler: async (ctx, args) => {
    const userMemories = await getUserMemories(ctx, args.userId);
    const examples = getExamples();

    return [
      ...userMemories,
      ...examples,
      ...args.search,
      ...args.recent,
      ...args.inputMessages,
    ];
  },
});

コンテキストを手動で取得する

LLM を呼び出さずにコンテキストを取得します。

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

export const getContextForPrompt = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { messages } = await fetchContextWithPrompt(ctx, components.agent, {
      threadId,
      prompt,
      contextOptions: {
        recentMessages: 20,
        searchOptions: { limit: 10, textSearch: true },
      },
    });

    return messages;
  },
});

主な原則

• デフォルトのコンテキストで十分です：ほとんどのユースケースではデフォルト設定で対応できます
• 検索によって関連性が向上します：長い会話では有効にします
• スレッドをまたぐ場合は userId が必要です：複数のスレッドを検索する際に指定します
• コンテキストハンドラーは強力です：メモリ、例、特殊な書式設定に使用します
• 最近のメッセージが優先されます：コンテキストの順序では、検索後に使用されます

次のステップ

• ナレッジベースのコンテキスト注入については rag を参照してください
• エージェントのセットアップについては fundamentals を参照してください
• トークン管理については rate-limiting を参照してください