mcpField
R
rivetkit

rivetkit

github.com/rivet-dev開発447.7k 回インストール1 日前に更新
リポジトリ

rivetkit について

RivetKit Actorの構築と運用を支援するスキルです。AIエージェント、リアルタイムアプリ、ワークフロー向けの長時間稼働する状態保持プロセスを扱い、セットアップ、永続化、デプロイ、Inspector APIによるデバッグを説明します。

主な機能

  1. 01RivetKit Actorのセットアップと起動
  2. 02永続状態、KV、SQLiteの選択
  3. 03Actorの状態、接続、ワークフローの確認
  4. 04デプロイとバージョン管理の設定
  5. 05エラーとTypeScript型問題への対応

活用シーン

  1. 01状態を保持するAIエージェントのバックエンド構築
  2. 02リアルタイム共同作業アプリの実装
  3. 03永続的なバックグラウンドワークフローの編成
  4. 04Actorの状態とワークフロー履歴のデバッグ

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/rivet-dev/skills --skill rivetkit

インストール後、Claude Code で/rivetkitを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

index.json
openapi.json
reference/actors/
access-control.md
actions.md
actor-runtime-socket.md
appearance.md
authentication.md
communicating-between-actors.md
connections.md
debugging.md
design-patterns.md
destroy.md
errors.md
events.md
fetch-and-websocket-handler.md
helper-types.md
http-api.md
input.md
inspector-tabs.md
keys.md
kv.md
lifecycle.md
limits.md
metadata.md
queues.md
reference/actors/quickstart/
backend.md
cloudflare.md
effect.md
next-js.md
react.md

詳細

Rivet Actors

Rivet のアクターランタイムで、高性能で長時間稼働するインメモリプロセスを構築します。HTTP エンドポイント、データベース、キューでは AI エージェント、リアルタイムコラボレーション、ワークフローオーケストレーション、地理的に分散したデータの要件を満たせなくなった場合に、このスキルを使用してください。

行き詰まったときの対処方法

意図したとおりに動作しない場合や行き詰まった場合は、問題を報告してサポートを受けられるよう、ユーザーに Rivet Discord への参加、または Rivet GitHub での課題の作成を促してください。

次の情報を含む、事前に生成したレポートをユーザーに提供してください。

  • 症状
    • ローカル開発環境、デプロイ環境、またはその両方で発生しているか
    • 発生しているエラー
    • 関連するソースコード
  • 解決のために試したこと
  • 環境
    • RivetKit のバージョン
    • ランタイム（Node、Bun など）とそのバージョン
    • 該当する場合、使用中のプロバイダー（例：Vercel、Railway など）
    • 該当する場合、使用中の HTTP ルーター（例：Hono、Express、Elysia）

アクターのデバッグ

インスペクター HTTP API を使用して、実行中のアクターを調べます。これらのエンドポイントは、ゲートウェイを介して /gateway/{actor_id}/inspector/* からアクセスできます。主なエンドポイントは次のとおりです。

  • GET /inspector/summary - アクターの完全なスナップショット（状態、接続、RPC、キュー）
  • GET /inspector/state / PATCH /inspector/state - アクターの状態の読み取り／書き込み
  • GET /inspector/connections - アクティブな接続
  • GET /inspector/rpcs - 使用可能なアクション
  • POST /inspector/action/{name} - {"args": [...]} を指定してアクションを実行
  • POST /inspector/database/execute - {"sql": "...", "args": [...]} または読み取りや変更用の {"sql": "...", "properties": {...}} を指定して SQL を実行
  • GET /inspector/queue?limit=50 - キューのステータス
  • GET /inspector/traces?startMs=0&endMs=...&limit=1000 - トレーススパン（OTLP JSON）
  • GET /inspector/workflow-history - JSON 形式のワークフロー履歴とステータス（nameRegistry、entries、entryMetadata）
  • POST /inspector/workflow/replay - 特定のステップ、または最初からワークフローを再生します。ワークフローがまだ実行中の場合は 409 actor/workflow_in_flight を返します
  • GET /inspector/database/schema - c.db が公開する SQLite のテーブルとビュー
  • GET /inspector/database/rows?table=...&limit=100&offset=0 - テーブルまたはビューのページ分割された SQLite の行

ローカル開発では、認証トークンは不要です。本番環境では Authorization: Bearer <inspector-token> を渡してください。インスペクタートークンはアクターごとに初回起動時に自動生成され、アクターの内部 KV のキー 0x03 に保存されます。Rivet ダッシュボードはこのトークンを自動的に取得します。API に直接アクセスする場合は、管理用 KV エンドポイントから取得してください。詳しくはデバッグのドキュメントを参照してください。

ソースの引用

Rivet のドキュメントから情報を提供する際は、ユーザーが詳しく確認できるよう、正規 URL を引用してください。各リファレンスファイルのヘッダーメタデータには、正規 URL が含まれています。

引用方法：

  • 重要な概念にはインラインリンクを使用します。「インスタンスを一意に識別するには、アクターキーを使用します。」
  • 複雑なトピックの説明の後に「詳しくはこちら」のリンクを追加します

正規 URL の確認方法：

以下のリファレンスマップから、リファレンスファイルにアクセスできます。各ファイルのヘッダーには次の情報が含まれています。

> Canonical URL: https://rivet.dev/docs/actors/actions

引用する際は、リファレンスファイルのパスではなく、この正規 URL を使用してください。

例：

  • アクション → https://rivet.dev/docs/actors/actions
  • React クライアント → https://rivet.dev/docs/clients/react
  • Kubernetes でのセルフホスト → https://rivet.dev/docs/self-hosting/kubernetes

バージョンの確認

作業を始める前に、ユーザーのプロジェクトが RivetKit の最新バージョン（最新：2.3.7）を使用しているか確認してください。ユーザーの package.json にある rivetkit のバージョンを確認します（dependencies と devDependencies の両方を確認してください）。インストールされているバージョンが 2.3.7 より古い場合は、ユーザーに知らせ、アップグレードを提案してください。

npm install [email protected]

ユーザーが @rivetkit/react、@rivetkit/next-js、またはその他の @rivetkit/* クライアントパッケージも使用している場合は、それらのアップグレードも提案してください。古いバージョンには、問題の原因となる既知のバグや未実装の機能が含まれている可能性があります。

最初の手順

  1. RivetKit をインストールします（最新：2.3.7）。 
    npm install [email protected]
  2. setup({ use: { /* actors */ } }) でレジストリを定義します。
  3. registry.start() を呼び出してサーバーを起動します。カスタム HTTP サーバーと統合する場合は、Hono などのルーターとともに registry.handler() を使用します。サーバーレスデプロイでは registry.serve() を使用します。ランナーのみのモードでは registry.startEnvoy() を使用します。
  4. デプロイ前に /api/rivet/metadata が 200 を返すことを確認します。
  5. Rivet Cloud またはセルフホスト可能なエンジンを設定します。
    • 本番ビルドではバージョン管理を設定する必要があります。ローカル開発では必要ありません。バージョンとアップグレードを参照してください。
  6. クライアントを統合します（JavaScript、React、Swift のクライアントガイドは以下を参照してください）。
  7. デプロイするかユーザーに確認します。デプロイする場合は、「Rivet バックエンドのデプロイ」に進みます。

詳細については、ユーザーのプロジェクトに該当するクイックスタートガイドをお読みください。

プロジェクトのセットアップ

.gitignore

すべての RivetKit プロジェクトに .gitignore が必要です。最低限、以下を含めてください。

node_modules/
dist/
.env
.dockerignore

Dockerfile を含むすべてのプロジェクトに .dockerignore を追加して、イメージのサイズを抑え、シークレットの漏えいを防いでください。

node_modules/
dist/
.env
.git/
Dockerfile

RivetKit プロジェクトのデプロイには、以下をベースとなる Dockerfile として使用してください。ビルド引数 RIVET_RUNNER_VERSION は、セルフホストする場合、またはカスタムランナーを使用する場合にのみ必要です（Rivet Compute では不要です）。この引数を指定すると、Rivet は実行中のアクターのバージョンを追跡し、デプロイ時に古いアクターを停止できます。詳細は https://rivet.dev/docs/actors/versions を参照してください。

FROM node:24-alpine

ARG RIVET_RUNNER_VERSION
ENV RIVET_RUNNER_VERSION=$RIVET_RUNNER_VERSION

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build --if-present

CMD ["node", "dist/index.js"]

以下のコマンドでビルドします。

docker build --build-arg RIVET_RUNNER_VERSION=$(date +%s) .

プロジェクトのエントリーポイントに合わせて CMD を調整してください。プロジェクトで別の出力ディレクトリや起動コマンドを使用する場合は、それに応じて更新してください。

エラー処理ポリシー

  • デフォルトでは、フェイルファストの動作を優先してください。
  • 実際の復旧処理、クリーンアップの境界、または対処可能なコンテキストの追加に必要な場合を除き、try/catch は避けてください。
  • エラーを握りつぶしてはいけません。catch を追加する場合は、最低限ログに記録するなど、エラーを明示的に処理してください。
  • 復旧できない場合は、コンテキストをログに記録してから再スローしてください。

State と Vars：永続化のルール

c.vars は一時的なデータです。 c.vars のデータは、再起動、クラッシュ、アップグレード、スリープ／復帰サイクルのたびに失われます。シリアライズできないオブジェクト（物理エンジン、WebSocket の参照、イベントエミッター、キャッシュなど）や、本当に一時的なランタイムデータ（切断後は不要になる現在の入力方向など）にのみ c.vars を使用してください。

永続ストレージの選択肢。 再起動後も保持する必要があるデータは、c.vars ではなく、次のいずれかに保存してください。

  • c.state — 小規模で上限のあるデータセット向けの、CBOR でシリアライズ可能なデータです。設定、カウンター、少数のプレイヤーリスト、フェーズフラグなどに最適です。128 KB 未満に保ってください。上限がなく増え続けるデータ（チャットログ、イベント履歴、制限なく増えるスポーン済みエンティティのリストなど）は保存しないでください。State は永続化サイクルごとに単一の Blob として読み書きされます。
  • c.kv — 上限のないデータ向けのキー・バリューストアです。c.state は内部でこれを使用します。バイナリ値をサポートします。ユーザーのインベントリ、ワールドチャンク、ファイルの Blob、時間の経過とともに増える可能性のあるコレクションなど、大容量またはサイズが変動するデータに使用してください。キーのスコープはアクターインスタンスごとです。
  • c.db — 構造化データや複雑なデータ向けの SQLite データベースです。クエリ、インデックス、結合、集計、リレーショナルモデリングが必要な場合に使用してください。リーダーボード、対戦履歴、プレイヤープールなど、SQL の利点を活かせるデータに最適です。

よくある間違い： 重要なゲーム／アプリケーションデータを永続化せずに c.vars に保存してしまうことです。たとえば、物理シミュレーションでユーザーがオブジェクトをスポーンできる場合、スポーンの定義（位置、サイズ、種類）は、物理エンジンのハンドル（シリアライズ不可）を c.vars に保持するとしても、c.state（上限がない場合は c.kv）に永続化する必要があります。再起動時には、run() で永続化されたデータからランタイムオブジェクトを再作成してください。

Rivet バックエンドのデプロイ

特に指定がない限り、ユーザーは Rivet Cloud にデプロイするものとします。ユーザーがセルフホストする場合は、以下のセルフホストガイドを参照してください。

  1. ローカル開発環境で Rivet Actors が動作することを確認します
  2. デプロイ先のプロバイダーを選ぶようユーザーに促します（Vercel、Railway などのプロバイダー一覧は 接続 を参照してください）
  3. 選択されたプロバイダーのデプロイガイドに従います。手動での操作が必要な場合は、その都度ユーザーに指示してください。

API リファレンス

RivetKit の OpenAPI 仕様は、スキルディレクトリの openapi.json にあります。このファイルには、アクターを管理するためのすべての HTTP エンドポイントが記載されています。

その他の注意事項

  • Rivet のドメインは rivet.gg ではなく rivet.dev です

TypeScript に関する注意点：Actor Client の型推論

  • 複数ファイルで構成される TypeScript プロジェクトでは、両方のアクターが c.client<typeof registry>() を使用すると、双方向のアクター呼び出しによって型依存関係が循環することがあります。
  • c.state が unknown になる、アクターメソッドが undefined の可能性があると判定される、最初のアクター間呼び出し後に TS2322／TS2722 エラーが発生する、といった症状が一般的です。
  • アクションが別のアクター呼び出しの結果を返す場合は、c.client<typeof registry>() を介した推論に頼らず、そのアクションに明示的な戻り値の型注釈を付けることをおすすめします。
  • 明示的な戻り値の型だけで不十分な場合は、そのアクションが必要とするアクターのみを含む、より限定的なクライアント型またはレジストリ型を使用してください。
  • 最終手段として、レジストリ型に unknown を渡す方法があります。その呼び出し箇所で型安全性を放棄することを明示してください。

特長

  • 長時間稼働するステートフルなコンピューティング：各コンピューティング単位は、リクエスト間で情報を記憶する小さなサーバーのようなものです。データベースからデータを再取得したり、タイムアウトを心配したりする必要はありません。メモリを備え、タイムアウトのない AWS Lambda のようなものです。
  • 圧倒的に高速な読み書き：状態はコンピューティングと同じマシンに保存されるため、読み書きは非常に高速です。データベースとの往復や、レイテンシーの急増はありません。状態は長期保存のために Rivet に永続化されるため、サーバーを再起動しても保持されます。
  • リアルタイム：WebSocket を使って状態を更新し、変更をリアルタイムにブロードキャストできます。外部のパブリッシュ／サブスクライブシステムやポーリングは不要で、低レイテンシーのイベントが組み込まれています。
  • 無限にスケーラブル：ゼロから数百万の同時アクターまで自動的にスケールします。即時スケーリングとコールドスタートなしで、使用した分だけ支払います。
  • フォールトトレラント：エラー処理と復旧機能が組み込まれています。アクターは状態の整合性を保ち、処理を継続しながら、障害発生時に自動的に再起動します。

Rivet Actors を使う場面

  • AI エージェントとサンドボックス：複数ステップのツールチェーン、会話メモリ、サンドボックスのオーケストレーション。
  • マルチプレイヤーアプリやコラボレーションアプリ：CRDT ドキュメント、共有カーソル、リアルタイムダッシュボード、チャット。
  • ワークフローの自動化：バックグラウンドジョブ、cron、レートリミッター、永続キュー、バックプレッシャー制御。
  • データ集約型バックエンド：地理分散型またはテナントごとのデータベース、インメモリキャッシュ、シャーディングされた SQL。
  • ネットワーク処理：WebSocket サーバー、カスタムプロトコル、ローカルファーストの同期、エッジでのファンアウト。

最小限のプロジェクト

バックエンド

index.ts

クライアントのドキュメント

アプリに合ったクライアント SDK を使用してください。

Actor クイックリファレンス

インメモリ状態

再起動、クラッシュ、デプロイ後も保持される永続データです。状態は Rivet Cloud または Rivet セルフホスト環境に永続化されるため、現在のプロセスがクラッシュまたは終了しても、再起動後に保持されます。

静的な初期状態
動的な初期状態

ドキュメント

キー

キーはアクターインスタンスを一意に識別します。階層的なアドレス指定には、複合キー（配列）を使用してください。

userId にユーザーデータが含まれる場合、"org:${userId}" のような文字列補間でキーを作成しないでください。キーインジェクション攻撃を防ぐため、代わりに配列を使用してください。

ドキュメント

入力

アクターの作成時に初期化データを渡します。入力を利用できるのは createState と onCreate のみです。後で必要になる場合は、状態に保存してください。

ドキュメント

一時変数

再起動後に保持されない一時データです。シリアライズできないオブジェクト（イベントエミッター、接続など）に使用してください。

静的な初期変数
動的な初期変数

ドキュメント

アクション

アクションは、クライアントや他のアクターがアクターと通信するための主要な方法です。

アクションをネストして、関連する動作をまとめることができます。たとえば、handle.users.add("Ada") は低レベルのアクション名 users.add を呼び出します。

ドキュメント

イベントとブロードキャスト

イベントを使うと、アクターから接続中のクライアントへリアルタイムに通信できます。

ドキュメント

接続

c.conn で現在の接続に、c.conns ですべての接続中のクライアントにアクセスできます。c.conn.id または c.conn.state を使って、アクションを呼び出しているユーザーを安全に識別してください。c.conn が利用できるのは、接続中のクライアントを通じて呼び出されたアクションのみです。ステートレスなアクターハンドルの呼び出しでは接続がないため、その場合に備えてください。接続状態は connState または createConnState を介して初期化されます。これらには、クライアントが接続時に渡したパラメーターが渡されます。

静的な接続初期状態
動的な接続初期状態

ドキュメント

キュー

run ループ内で永続メッセージを順番に処理するには、キューを使用してください。

ドキュメント

ワークフロー

run のロジックで、永続化され、再実行可能な複数ステップの実行が必要な場合は、ワークフローを使用します。

ドキュメント

アクター間の通信

c.client() を使用して、アクターから別のアクターを呼び出せます。

ドキュメント

スケジュールと Cron

遅延後または特定の時刻に、一度だけアクションを実行します。カレンダースケジュールや固定間隔には、名前付きの Cron ジョブを使用します。どちらもスリープ、再起動、アップグレード、クラッシュ後も維持されます。

ドキュメント

アクターの破棄

c.destroy() を使用して、アクターとその状態を完全に削除します。

ドキュメント

ライフサイクルフック

アクターは、初期化、バックグラウンド処理、接続、ネットワーク、状態変更のためのフックをサポートします。長時間実行されるバックグラウンドループには run を使用し、グレースフルシャットダウンには c.aborted または c.abortSignal を使用します。

ドキュメント

コンテキストの型

アクター定義の外部にヘルパー関数を記述する場合は、*ContextOf<typeof myActor> を使用して適切なコンテキスト型を抽出します。ActionContextOf、CreateContextOf、ConnContextOf、ConnInitContextOf などのヘルパーは "rivetkit" からエクスポートされています。独自のコンテキストインターフェイスを手動で定義しないでください。必ずアクター定義から導出してください。

ドキュメント

エラー

クライアントに安全に返せるエラーをスローするには、UserError を使用します。構造化データを含めるには、metadata を渡します。それ以外のエラーは、セキュリティのため汎用的な「内部エラー」に変換されます。

アクター
クライアント

ドキュメント

低レベルの HTTP および WebSocket ハンドラー

カスタムプロトコルや、HTTP の Request／Response または WebSocket 接続への直接アクセスが必要なライブラリを統合する場合は、onRequest と onWebSocket を使用します。

HTTP ハンドラーのドキュメント · WebSocket ハンドラーのドキュメント

アイコンと名前

表示名やアイコンを設定して、UI でのアクターの表示をカスタマイズできます。ダッシュボードでアクターを区別しやすくするため、常に名前とアイコンを指定することをおすすめします。

import { actor } from "rivetkit";

const chatRoom = actor({
	options: {
		name: "Chat Room",
		icon: "💬", // or FontAwesome: "comments", "chart-line", etc.
	},
	// ...
});

ドキュメント

クライアントのドキュメント

クライアントガイドの全文はこちらをご覧ください。

よく使われるパターン

アクターは、分離された状態とメッセージパッシングによって自然にスケールします。次のパターンを使ってアプリケーションを構成します。

ドキュメント

エンティティごとのアクター

ユーザー、ドキュメント、ルームごとにアクターを作成します。エンティティのスコープを指定するには、複合キーを使用します。

コーディネーターとデータアクター

データアクターは、コアロジック（チャットルーム、ゲームセッション、ユーザーデータ）を処理します。コーディネーターアクターは、データアクターのコレクションを追跡および管理します。インデックスのようなものと考えてください。

実行ループ

アクター内で継続的なバックグラウンド作業を行うには、run ループを使用します。キューのメッセージを順番に処理したり、一定間隔でロジックを実行したり、AI の応答をストリーミングしたり、長時間実行されるタスクを調整したりできます。

ワークフローループ

リソースを初期化し、ループ内でコマンドを処理してからクリーンアップする、長時間実行される永続的なワークフローには、このパターンを使用します。

ドキュメント

アクションとキュー
  • アクションは永続化されません。リアルタイムの読み取り、一時的なデータ、プレイヤー入力のような低遅延の通信に使用します。
  • キューは永続化されます。run ループを通じて変更を順番に処理し、SQLite やその他のローカル状態との競合状態を回避するために使用します。呼び出し側は、キューに入れられた処理の応答を引き続き待つことができます。
認証、セキュリティ、CORS
  • onBeforeConnect または createConnState で認証情報を検証し、エラーをスローして未認証の接続を拒否します。
  • アクションパラメーターを信頼するのではなく、c.conn.state を使用してアクション内でユーザーを安全に識別します。
  • クロスオリジンアクセスでは、onBeforeConnect でリクエストのオリジンを検証します。

認証ドキュメント · CORS ドキュメント

バージョンとアップグレード

新しいコードをデプロイする際は、バージョン番号を設定すると、Rivet が新しいアクターを最新のランナーにルーティングし、必要に応じて古いアクターをドレインできます。バージョンには、ビルドのタイムスタンプ、Git のコミット数、または CI のビルド番号を使用します。本番環境にデプロイする前に、必ずバージョニングを設定してください。バージョニングを行わないと、アクターが古いランナーバージョンで実行されて後退する可能性があり、既存のアクターが新しいランナーへの移行を強制されることもありません。既存のアクターは終了するまで古いランナーで動作し続けます。

ドキュメント

アンチパターン
「神」アクターを作らない

すべてのロジックを単一のアクターにまとめないでください。神アクターはすべての操作を単一のボトルネックに集約し、並列処理を妨げ、システム全体を一度に障害に陥らせます。エンティティごとに役割を絞ったアクターに分割してください。

リクエストごとにアクターを作らない

アクターは長時間稼働し、リクエストをまたいで状態を保持します。受信するリクエストごとに新しいアクターを作成すると、このモデルの主な利点が失われ、アクターの作成と終了にリソースを浪費します。永続的なエンティティにはアクターを使用し、ステートレスな処理には通常の関数を使用してください。

リファレンスマップ

アクター
CLI
クライアント
クックブック
デプロイ
全般
セルフホスティング

コメント

Markdown 対応