Convex Agents Fundamentals

目的

Convex エージェントのセットアップ、会話スレッドの管理、LLM レスポンスの生成に関する主要なパターンを説明します。これは、ほかのすべてのエージェント機能の基盤となります。

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

• プロジェクトで初めて Convex エージェントをセットアップする
• ユーザーとの会話スレッドを作成または続行する
• LLM からテキストレスポンスや構造化された JSON オブジェクトを生成する
• エージェントのデフォルト設定（システムプロンプト、チャットモデル、埋め込みモデル）を構成する
• メッセージ履歴が必要な基本的なチャットインターフェースを構築する

使用方法

1. インストールと構成

エージェントコンポーネントを convex.config.ts に追加します。

// convex/convex.config.ts
import { defineApp } from "convex/server";
import agent from "@convex-dev/agent/convex.config";

const app = defineApp();
app.use(agent);

export default app;

npx convex dev を実行して、必要なコードを生成します。

2. エージェントを定義する

チャットモデルを使用して、エージェントのインスタンスを作成します。

// convex/agents/myAgent.ts
import { components } from "../_generated/api";
import { Agent } from "@convex-dev/agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new Agent(components.agent, {
  name: "My Assistant",
  languageModel: openai.chat("gpt-4o-mini"),
  instructions: "You are a helpful assistant.", // Optional: default system prompt
});

3. スレッドを作成する

会話履歴を管理するために、ユーザー用のスレッドを作成します。

// convex/threads.ts
import { action } from "../_generated/server";
import { v } from "convex/values";
import { myAgent } from "./agents/myAgent";

export const createNewThread = action({
  args: { userId: v.string() },
  handler: async (ctx, { userId }) => {
    const { thread } = await myAgent.createThread(ctx, {
      userId,
      title: "New Conversation",
    });
    return { threadId: thread.getMetadata().threadId };
  },
});

4. レスポンスを生成する

スレッド内でテキストまたは構造化レスポンスを生成します。

// convex/generation.ts
export const generateReply = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { thread } = await myAgent.continueThread(ctx, { threadId });
    const result = await thread.generateText({ prompt });
    return result.text;
  },
});

重要な原則

• スレッドの分離：各ユーザー／会話に専用のスレッドを割り当て、履歴を個別に管理します
• メッセージの自動保存：生成されたレスポンスはスレッドに自動的に保存されます
• デフォルトのコンテキスト：生成のたびに、最近のメッセージ履歴が自動的に含まれます
• 非同期処理に対応：LLM の呼び出しにはアクションを、トランザクション書き込みにはミューテーションを使用します
• 型安全性：循環参照エラーを避けるため、常に明示的な戻り値の型を指定します

よくあるパターン

• ユーザーごとの管理：スレッドを作成する際は、必ず userId を含めます
• メッセージ履歴：LLM のコンテキストに自動的に含まれます
• スレッドの再利用：同じスレッドを複数のエージェントで使用できます

次のステップ

• スレッドを管理する：会話の管理については threads スキルを参照してください
• メッセージを扱う：保存と取得については messages スキルを参照してください
• ツールを追加する：エージェントがアクションを実行できるようにするには tools スキルを参照してください