ai-agent-workspace

AI エージェントのワークスペース

重要：何かを始める前に、このスキルのディレクトリにある BASE_SKILL.md を必ず読んでください。デバッグ、エラー処理、状態管理、デプロイ、プロジェクトのセットアップに関する重要なガイダンスが記載されています。これらのルールとパターンは、すべての RivetKit の作業に適用されます。以下の内容は、すでに読んで理解していることを前提としています。

動作する例

参考実装が必要な場合は、次のテンプレートにある、実際に動作するコードを直接確認してください。

• agent-os

agentOS を使って各 AI エージェントに専用のコンピューターを提供するパターンです。エージェントごとに 1 つの Rivet Actor を用意し、Wasm と V8 上で動作する、移植可能で軽量なインプロセス OS を所有させます。実行間で状態を保持するコードインタープリター、共有可能なプレビュー URL で成果物を公開するエージェント、ユーザーごとの開発環境、定期メンテナンスを行うエージェントに利用できます。agentOS はプレビュー段階であり、API は変更される可能性があります。

この項目では、エージェントにワークスペースを提供する方法を扱います。会話のメモリ、メッセージキュー、ストリーミングチャットのパターンについては、AI エージェントを参照してください。

スターターコード

agent-os コレクションは機能ごとに 1 つのサブサンプルを含む参考コードです。すぐに使えるアプリではなく、プロジェクトに取り入れるパターンとして扱ってください。agent-os-e2e の例では、エンドツーエンドの一連の手順を確認できます。

例	スターターコード	利用するケース
Hello World	GitHub	最小限のループを実装したい場合。最初の操作で VM を遅延起動し、ファイルを書き込んで読み戻します。
ファイルシステム	GitHub	エージェントが再帰的な一覧表示、stat、移動、削除、カスタムマウントなど、ファイル操作一式を必要とする場合。
Git	GitHub	エージェントがワークスペース内の実際の git リポジトリを操作し、exec で init、commit、branch、clone を行う場合。
プロセス	GitHub	エージェントがパイプを使ったシェルコマンドや、長時間実行されるプロセスを起動する場合。
ネットワーク	GitHub	エージェントが VM 内で HTTP サーバーを実行し、vmFetch または署名付きプレビュー URL が必要な場合。
Cron	GitHub	ワークスペースでスケジュールされたコマンドや、定期的なエージェント作業を実行する場合。
ツール	GitHub	バックエンドの関数を、ワークスペース内の CLI コマンドとして公開したい場合。
エージェントセッション	GitHub	ワークスペース内で Pi コーディングエージェントのセッションを実行する場合。ANTHROPIC_API_KEY が必要です。
サンドボックスのマウント	GitHub	Docker を基盤とするサンドボックスから VM にマウントしたネイティブバイナリや実際の OS がエージェントに必要な場合。Docker が必要です。
エンドツーエンドの手順	GitHub	ファイル、プロセス、プレビュー URL、ストリーミング Pi エージェントセッションを網羅した、実行可能なスクリプトを 1 つ使いたい場合。

セットアップ

バックエンド全体は、1 つの agentOs() アクターを含む 1 つのレジストリで構成されます。

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

クライアント側とプロジェクトのレイアウトについては、クイックスタートを参照してください。

ワークスペースモデル

• ワークスペースごとにアクターは1つで、キーが識別子になります。 client.vm.getOrCreate(["my-agent"]) を使うと、各エージェントに専用のワークスペースが割り当てられます。ユーザーごとの開発環境には、ユーザー ID をキーにします。各ワークスペースは独自のファイルシステム、プロセス、ネットワークを持ち、状態は共有されず、相互に影響しません（概要を参照）。
• インストールするソフトウェアパッケージは選択できます。 agentOS には、コマンドがインストールされていない状態で開始します。software オプションを使って、@rivet-dev/agent-os-common（coreutils、sed、grep、gawk、findutils、diffutils、tar、gzip を含む WebAssembly 製コマンドラインツールのメタパッケージ）、@rivet-dev/agent-os-git（git）、@rivet-dev/agent-os-pi（Pi コーディングエージェント）などのパッケージをインストールします。ソフトウェアを参照してください。
• VM は必要になったときに起動し、アイドル状態になるとスリープします。 最初のアクションで VM が起動し（クライアントには vmBooted イベントが通知されます）、アクティブなものがなくなるとアクターはスリープして vmShutdown をブロードキャストします。その後、次のアクションで再び起動します。

スリープ／復帰サイクルをまたいで保持されるデータ（永続性を参照）：

データ	スリープ／復帰をまたぐ保持
セッションのトランスクリプトとイベント履歴	アクターの SQLite にイベントストリームとして保持されます。listPersistedSessions と getSessionEvents は VM を起動せずに読み出し、resumeSession は再起動した VM でセッションを再開します。
署名付きプレビュー URL トークン	アクターの SQLite に保持されます。リクエストは保存済みトークンと照合して検証され、VM はリクエストを処理するために必要になったときに再起動するため、スリープ後もプレビュー URL を使用できます。
ファイル	マウントが永続ドライバー（データベースベース、S3、またはサンドボックスマウント）によって支えられている場合に保持されます。メモリ内マウントは、復帰時に空になります。
プロセス、シェル、cron ジョブ	保持されません。復帰時に長時間実行プロセスを再起動し、cron ジョブを再スケジュールしてください（推奨される拡張方法）。

セッション、プロセス、シェル、フックがアクティブな間、アクターは起動状態を維持し、その後、猶予期間を経てスリープします。

機能の概要

領域	用途	主なアクション	ドキュメント	例
ファイルシステム	エージェントが読み書きできるファイルツリーを提供する	readFile、writeFile、mkdir、readdir、move	ファイルシステム	GitHub
プロセス	コマンドや長時間実行プログラムを実行する	exec、spawn、waitProcess、killProcess	プロセス	GitHub
シェル	出力がストリーミングされる対話型ターミナル	openShell、writeShell、resizeShell、closeShell	プロセス	単独の例はありません
ネットワークとプレビュー URL	VM 内のサービスに接続し、外部と共有する	vmFetch、createSignedPreviewUrl、expireSignedPreviewUrl	ネットワーク	GitHub
Cron	コマンドやエージェントセッションを定期的に実行する	scheduleCron、listCronJobs、cancelCronJob	Cron	GitHub
エージェントセッション	ワークスペース内でコーディングエージェントを操作する	createSession、sendPrompt、resumeSession、closeSession	セッション	GitHub

あらかじめ知っておくと便利な点が2つあります。

• createSignedPreviewUrl は、トークンと有効期限を含む相対パスを返します。完全な URL は、クライアントハンドルの getGatewayUrl() メソッドを使って組み立ててください。これはクライアントのメソッドであり、アクターのアクションではありません。
• cron ジョブは、exec と session のアクションタイプのみを使ってアクター経由でスケジュールしてください。コールバックの cron アクションはサーバーコード内で定義されており、listCronJobs ではシリアライズされません。

コーディングエージェントのセッションを実行する

現在、セッションエージェントとしてサポートされているのは Pi エージェント（@rivet-dev/agent-os-pi）のみです。Amp、Claude Code、Codex、OpenCode は近日対応予定です。セッションを参照してください。

1. createSession("pi", { env: { ANTHROPIC_API_KEY } }) は sessionId を返します。VM はホストの process.env を継承しないため、API キーはセッションごとに明示的に渡すか、LLM ゲートウェイを通じてサーバー側に保持します。
2. リアルタイム接続を開き、sessionEvent をサブスクライブして、エージェントの作業中にメッセージチャンクなどの出力をストリーミングします。
3. sendPrompt(sessionId, ...) はターンを開始し、実行中のターンは cancelPrompt で停止します。
4. エージェントがツールの使用を求めると、クライアントは permissionRequest イベントを受け取り、respondPermission で応答します。または、サーバーが onPermissionRequest 設定フックで自動承認します（権限を参照）。
5. トランスクリプトはユニバーサルなトランスクリプト形式（Agent Communication Protocol、ACP）で自動的に永続化されます。スリープ後は、resumeSession で再起動された VM 上のセッションを続行できます。また、listPersistedSessions と getSessionEvents を使うと、VM を起動せずに履歴を読み取れます。

ホストツール

バックエンド関数を、ワークスペース内の CLI コマンドとしてエージェントに公開します。toolKit() と hostTool()（ホスト上で実行される、Zod スキーマを定義した JavaScript 関数）でツールキットを定義し、agentOs({ options: { toolKits: [...] } }) を介して渡すと、agentos-weather forecast --city Paris --days 3 のようなコマンドとしてインストールされ、エージェントのシステムプロンプトに注入されます。HTTP エンドポイントや MCP サーバーを用意しなくても、エージェントはバックエンドを呼び出せます。また、CLI 形式のツールはコードモードに対応しているため、トークンを大幅に節約できます。ツールとツールの例を参照してください。

フルサンドボックスをマウントする場合

agentOS はサンドボックスの代替ではなく、サンドボックスと連携するように設計されています。ワークスペースでネイティブバイナリ、ブラウザー、コンパイル、デスクトップ操作が必要な場合は、サンドボックスのマウントを使用します。SandboxAgent.start({ sandbox: docker() }) で Docker ベースのサンドボックスを起動し、createSandboxFs を使ってそのファイルシステムをネイティブディレクトリ（例：/sandbox）として VM に投影し、createSandboxToolkit でサンドボックスのプロセス制御をホストツールとして公開します。writeFile や readFile などのファイルシステム操作はマウントを通じて透過的に投影される一方、負荷の高いワークロードはコンテナ内で実行されます。

ハイブリッドモデルについてはサンドボックスのマウントを、どちらを選ぶべきかについてはagentOS とサンドボックスを参照してください。軽量 VM はコールドスタートがほぼゼロ（約 6 ms）で、npm install でインストールできます。一方、サンドボックスは稼働時間に応じて秒単位で課金される、完全な Linux 環境です。

アーキテクチャ

トピック	概要
トポロジー	エージェントごと、またはユーザーごとに vm[workspaceId] アクターを1つ割り当てます。アクターキーはワークスペースの識別子です。
受信処理	ファイル、プロセス、ネットワーク、cron、セッション用のアクターアクションと、ストリーミングイベント用のリアルタイム接続を使用します。
ストリーミング	エージェントの各イベントに sessionEvent、起動したプロセスには processOutput と processExit、インタラクティブシェルには shellData を使用します。
永続化	セッションのトランスクリプト、イベント履歴、プレビュー用トークンはアクターの SQLite に保存されます。ファイルは永続マウントによって保持されます。

アクター

• キー：vm[workspaceId]。例：client.vm.getOrCreate(["my-agent"])
• 責務：1つのワークスペースを所有します。最初のアクション時にVMを遅延起動し、すべての機能アクションを処理し、署名付きプレビューURLのリクエストをVMの仮想ネットワークにプロキシし、セッションとトークンをアクターの SQLite に永続化します。
• アクション（分類別。各領域の主要なものを記載）
  • ファイルシステム：readFile、writeFile、mkdir、readdir、readdirRecursive、stat、exists、move、deleteFile
  • プロセス：exec、spawn、writeProcessStdin、waitProcess、listProcesses、killProcess
  • シェル：openShell、writeShell、resizeShell、closeShell
  • ネットワーク：vmFetch、createSignedPreviewUrl、expireSignedPreviewUrl
  • Cron：scheduleCron、listCronJobs、cancelCronJob
  • セッション：createSession、sendPrompt、cancelPrompt、respondPermission、resumeSession、closeSession、destroySession、listPersistedSessions、getSessionEvents
• キュー
  • なし
• イベント
  • vmBooted
  • vmShutdown
  • sessionEvent
  • permissionRequest
  • processOutput
  • processExit
  • shellData
  • cronEvent
• 状態
  • SQLite
  • agent_os_sessions および agent_os_session_events（セッションメタデータと、シーケンス順に並んだトランスクリプトイベント）
  • agent_os_preview_tokens（有効期限付きの署名付きプレビューURLトークン）
  • agent_os_fs_entries（データベースを使用するマウントのファイル内容）

ライフサイクル

sequenceDiagram
	participant C as Client
	participant A as vm actor
	participant V as agentOS VM
	participant P as Pi session

	C->>A: getOrCreate(["my-agent"])
	C->>A: writeFile("/tmp/hello.txt", ...)
	Note over A,V: first action boots the VM
	A-->>C: vmBooted
	C->>A: exec("echo hello | tr a-z A-Z")
	A->>V: run command
	V-->>A: {exitCode: 0, stdout}
	C->>A: spawn("node", ["/tmp/server.mjs"])
	C->>A: createSignedPreviewUrl(8080, 60)
	A-->>C: {path, token, expiresAt}
	C->>A: fetch(gatewayUrl + path)
	Note over A: token checked in SQLite, request proxied into the VM network
	C->>A: createSession("pi", {env})
	A->>P: start session
	C->>A: sendPrompt(sessionId, ...)
	loop streamed agent output
		P-->>A: agent event
		A-->>C: sessionEvent
	end
	Note over A: idle, sleeps after grace period (vmShutdown)
	C->>A: resumeSession(sessionId)
	Note over A,V: wake reboots the VM, restoring transcripts, preview tokens, and persistent mounts

セキュリティチェックリスト

• 接続を認証する：agentOs() 設定に onBeforeConnect フックを追加し、認証済みの呼び出し元だけがワークスペースに接続できるようにします。署名付きプレビューURLのリクエストでは、トークンが認証情報となるため、このフックを意図的にスキップします。プレビューURLにアクセスするブラウザーからは、アクター接続パラメーターを渡せません。
• エージェントのツール使用を権限で制御する：セッションの権限リクエストは permissionRequest イベントとしてブロードキャストされ、人間が respondPermission を使って承認できます。または、自動化されたパイプラインではサーバー側の onPermissionRequest ポリシーを実行します。権限を参照してください。
• プレビューURLをベアラー認証情報として扱う：トークンはランダムに生成される32文字の値で、デフォルトの有効期限は1時間、最大24時間です。早期に無効化するには expireSignedPreviewUrl を使用します。プレビューのレスポンスには寛容なCORSヘッダーが含まれるため、アプリケーションレベルの認証なしでプレビューポートから非公開データを配信しないでください。
• LLMの認証情報をブラウザーに置かない：信頼できるサーバーコードから createSession の env にキーを指定してセッションを作成するか、LLMゲートウェイを使ってキーをサーバー側だけに保持します。セッションキーはVM内のセッション環境に注入され、アクター設定や SQLite に保存されることはありません。
• マウントされたサンドボックスを独立した信頼境界として扱う：マウントされたサンドボックスは、ワークスペースのWasmおよびV8分離環境の外部にある、完全なLinux環境です。エージェントのVMに接続する前に、ネットワークとファイルシステムからアクセスできる範囲を制限してください。
• リソースとコストの上限を設定する：ワークスペースごとのメモリとCPUを制限します（maxMemoryMb、maxCpuPercent。セキュリティを参照してください）。アクティブなセッション、プロセス、シェルがある間はアクターが起動状態を保つため、ワークスペースごとのセッション数上限とトークン予算を追加することを推奨します。

リファレンスマップ

アクター

• アクセス制御
• アクション
• アクターキー
• アクターのスケジューリング
• アクターのステータス
• 認証
• Cloudflare Workers クイックスタート
• アクター間の通信
• 接続
• カスタムインスペクタータブ
• デバッグ
• 設計パターン
• アクターの破棄
• Effect.ts クイックスタート（ベータ版）
• エラー
• Fetch および WebSocket ハンドラー
• ヘルパー型
• アイコンと名前
• メモリ内の状態
• 入力パラメーター
• ライフサイクル
• 制限
• 低レベル HTTP リクエストハンドラー
• 低レベル KV ストレージ
• 低レベル WebSocket ハンドラー
• メタデータ
• Next.js クイックスタート
• Node.js と Bun のクイックスタート
• キューと実行ループ
• React クイックスタート
• リアルタイム
• Rust クイックスタート（ベータ版）
• スケーリングと並行処理
• 状態の共有と参加
• SQLite
• SQLite + Drizzle
• Supabase Functions クイックスタート
• テスト
• トラブルシューティング
• 型
• 標準 HTTP API
• バージョンとアップグレード
• ワークフロー

Agent Os

• エージェント間通信
• agentOS と Sandbox の比較
• 認証
• ベンチマーク
• 設定
• コアパッケージ
• 入門ガイド
• Cron ジョブ
• デプロイ
• 組み込み LLM ゲートウェイ
• イベント
• ファイルシステム
• 制限事項
• LLM 認証情報
• マルチプレイヤー
• ネットワークとプレビュー
• 権限
• 永続化とスリープ
• Pi
• プロセスとシェル
• キュー
• クイックスタート
• サンドボックスのマウント
• セキュリティと認証
• セキュリティモデル
• セッション
• ソフトウェア
• SQLite
• システムプロンプト
• ツール
• Webhook
• ワークフロー自動化

CLI

• CLI

クライアント

• Node.js と Bun
• React
• Swift
• SwiftUI

クックブック

• AI エージェント
• AI エージェントのワークスペース
• チャットルーム
• 共同編集テキストエディター
• Cron ジョブとスケジュール済みタスク
• テナントごとのデータベース
• VPC またはエアギャップネットワークへの Rivet のデプロイ
• ライブカーソルとプレゼンス
• マルチプレイヤーゲーム

デプロイ

• Amazon Web Services Lambda へのデプロイ
• AWS ECS へのデプロイ
• Cloudflare Workers へのデプロイ
• Freestyle へのデプロイ
• Google Cloud Run へのデプロイ
• Hetzner へのデプロイ
• Kubernetes へのデプロイ
• Railway へのデプロイ
• Rivet Compute へのデプロイ
• Supabase Functions へのデプロイ
• Vercel へのデプロイ
• VM とベアメタルへのデプロイ

一般

• アクターの設定
• アーキテクチャ
• クロスオリジンリソース共有
• LLM と AI 向けドキュメント
• エッジネットワーキング
• エンドポイント
• 環境変数
• HTTP サーバー
• ログ記録
• プールの設定
• 本番環境チェックリスト
• レジストリの設定
• ランタイムモード
• WASM とネイティブ SDK の比較

セルフホスティング

• 設定
• Docker Compose
• Docker コンテナ
• ファイルシステム
• FoundationDB（エンタープライズ）
• Rivet Engine のインストール
• Kubernetes
• マルチリージョン
• PostgreSQL
• 本番環境チェックリスト
• Railway へのデプロイ
• Render へのデプロイ
• TLS と証明書