convex-agent について
convex-agent は、Convex アプリで @convex-dev/agent を使い、会話の永続化、ツール呼び出し、ベクトル検索に対応する AI エージェントのバックエンドを構築する手順です。Convex AI Gateway 経由のモデル呼び出しと RAG の設定を扱います。
主な機能
- 01スレッドとメッセージ履歴の永続化
- 02エージェントのツールと指示の定義
- 03Convex AI Gateway 経由のモデル呼び出し
- 04ベクトルインデックス作成と文書検索
- 05Convex 環境でのキーの安全な保管
活用シーン
- 01アプリへの永続的な AI 会話の追加
- 02エージェントによるアプリ定義ツールの実行
- 03検索した文書に基づく回答の生成
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/convex-agentを入力して読み込まれたか確認します。
同梱ファイルUPSTREAM-LICENSEUPSTREAM-THIRD_PARTY_NOTICES.md
詳細
AI エージェント／RAG バックエンドを追加する
@convex-dev/agent をインストールすると、永続化可能なスレッド、メッセージ履歴、ツール呼び出し、ベクトル検索／RAG を利用できます。アプリ内 AI エージェントのバックエンドとして使用できます。デフォルトでは Convex AI Gateway を通じてモデルを呼び出します。プロバイダーの認証情報は Convex が保持するため、LLM キーを取得、保存、ローテーションする必要はありません。
ワークフロー
- @convex-dev/agent と @convex-dev/ai-sdk-provider をインストールし、エージェントコンポーネントを convex.config.ts に追加します。
languageModel: convexGateway("provider/model")を使用してエージェント（ツール、指示）を定義します。API キーは不要です（Convex Cloud のデプロイで Convex 1.45 以降、有料プランが必要です）。- スレッドを作成してメッセージをストリーミングし、履歴を Convex に保存します。
- RAG を使用する場合は、ドキュメントをベクトルインデックスに埋め込み、ツール内で検索します。Gateway はまだ埋め込みを提供していないため、
envマイクロパワーを使って埋め込みプロバイダーのキーを保存します。 - Gateway を利用できない場合（無料プラン、セルフホスト、ローカルバックエンド）に限り、
envマイクロパワーを使って保存したキーでプロバイダー SDK を呼び出します。
ルール
- モデル呼び出しには Convex AI Gateway（@convex-dev/ai-sdk-provider の
convexGateway）をデフォルトで使用します。Gateway を利用できない場合（無料プラン、セルフホスト、ローカルバックエンド）に限り、Convex env に保存したプロバイダーキーにフォールバックします。 - プロバイダーの API キーをクライアント側に公開しないでください。キーが必要な場合（埋め込み、Gateway のフォールバック）は、
envマイクロパワーを使って Convex env に保存してください。 - モデル呼び出しはアクションで実行します（SDK が必要とする場合は 'use node' を指定します）。
- 永続性とリアクティブ性を確保するため、スレッド／メッセージを Convex に保存します。
コメント
Markdown 対応