tigris-agent-kit

Tigris Agent Kit

Tigris 上の AI エージェント向けの高レベルなストレージワークフローです。@tigrisdata/storage と @tigrisdata/iam のプリミティブを組み合わせて、フォーク、ワークスペース、チェックポイント、連携という 4 つの構成要素を提供します。

前提条件

何よりも先に、Tigris CLI がインストールされていることを確認してください。

tigris help || npm install -g @tigrisdata/cli

インストールが必要な場合は、ユーザーに次のように伝えてください：「Tigris オブジェクトストレージを利用できるよう、Tigris CLI（@tigrisdata/cli）をインストールしています。」

次に、agent-kit パッケージをインストールします。

npm install @tigrisdata/agent-kit

設定

すべての関数は省略可能な config パラメーターを受け取ります。省略した場合、SDK は環境変数から値を読み込みます。

TIGRIS_STORAGE_ACCESS_KEY_ID=tid_...
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_...

必要に応じて、設定を明示的に渡します。

const config = {
  accessKeyId: 'tid_...',
  secretAccessKey: 'tsec_...',
};

すべての関数は TigrisResponse<T> を返します。これは { data: T } または { error: Error } の判別可能なユニオンです。必ず最初に error を確認してください。

クイックリファレンス

構成要素	目的	関数
フォーク	共有データセットの独立したコピーを N 個作成	createForks、teardownForks
ワークスペース	エージェントごとに専用バケットを用意し、TTL を設定	createWorkspace、teardownWorkspace
チェックポイント	バケットの状態をスナップショットし、フォークとして復元	checkpoint、restore、listCheckpoints
連携	Webhook を使ったイベント駆動型パイプライン	setupCoordination、teardownCoordination

どれを使うか

シナリオ	使用するもの
それぞれがデータセットの独自コピーを必要とする N 個のエージェントを起動する	フォーク
1 つのエージェントに、一日後に自動クリーンアップされる一時用バケットを用意する	ワークスペース
後から分岐できるよう、実行中のエージェントの状態を保存する	チェックポイント + 復元
上流のエージェントが結果を書き込んだとき、下流のエージェントを起動する	連携

フォーク — エージェント用の並列コピー

各フォークはストレージが分離された独立したバケットです。コピーオンライト方式のため、サイズを問わず即座に作成でき、データも重複しません。ベースバケットではスナップショットを有効にする必要があります。

import { createForks, teardownForks } from '@tigrisdata/agent-kit';

const { data: forkSet, error } = await createForks('my-dataset', 3, {
  prefix: 'experiment-run-42',
  credentials: { role: 'Editor' },
});
if (error) throw error;

for (const fork of forkSet.forks) {
  // fork.bucket — the bucket name
  // fork.credentials?.accessKeyId / secretAccessKey — scoped per fork
}

// Revokes credentials and deletes all fork buckets
await teardownForks(forkSet);

詳細なオプション、ライフサイクル、パターンについては、./resources/forks.md を参照してください。

ワークスペース — エージェントごとのバケット

1 つのエージェント専用のバケットをプロビジョニングします。省略可能な TTL を設定するとオブジェクトが自動的に期限切れになり、省略可能なスコープ付き認証情報を使うと最小権限を適用できます。

import { createWorkspace, teardownWorkspace } from '@tigrisdata/agent-kit';

const { data: workspace } = await createWorkspace('agent-workspace-abc', {
  ttl: { days: 1 },
  enableSnapshots: true,
  credentials: { role: 'Editor' },
});

// Use workspace.bucket and workspace.credentials with @tigrisdata/storage

await teardownWorkspace(workspace);

詳細なオプション、TTL の動作、パターンについては、./resources/workspaces.md を参照してください。

チェックポイント — スナップショットと復元

特定の時点のバケットの状態を記録します。復元すると、そのスナップショットからコピーオンライト方式のフォークが作成されます。元のバケットには影響しません。

import { checkpoint, restore, listCheckpoints } from '@tigrisdata/agent-kit';

const { data: ckpt } = await checkpoint('training-data', { name: 'epoch-50' });

const { data: list } = await listCheckpoints('training-data');

const { data: restored } = await restore(
  'training-data',
  ckpt.snapshotId,
  { forkName: 'training-data-retry' },
);
// restored.bucket — independent fork at that point in time

詳細なオプションとロールバックパターンについては、./resources/checkpoints.md を参照してください。

連携 — イベント駆動型パイプライン

ポーリングを行わずに書き込み時に Webhook が発火するよう、バケット通知を設定します。エージェントの連携に利用できます。エージェント A が結果を書き込み、Tigris が Webhook を発火させ、エージェント B が起動します。

import { setupCoordination, teardownCoordination } from '@tigrisdata/agent-kit';

await setupCoordination('pipeline-bucket', {
  webhookUrl: 'https://my-service.com/webhook',
  filter: 'WHERE `key` REGEXP "^results/"',
  auth: { token: 'my-webhook-secret' },
});

await teardownCoordination('pipeline-bucket');

フィルター構文、Webhook 認証、パイプラインパターンについては、./resources/coordination.md を参照してください。

API リファレンス

フォーク

関数	説明
createForks(baseBucket, count, options?)	スナップショットを作成し、N 回フォークして、スコープ付き認証情報を設定
teardownForks(forkSet, options?)	認証情報を失効させ、フォークを削除

ワークスペース

関数	説明
createWorkspace(name, options?)	バケットを作成し、TTL とスコープ付き認証情報を設定
teardownWorkspace(workspace, options?)	認証情報を失効させ、バケットを削除

チェックポイント

関数	説明
checkpoint(bucket, options?)	バケットのスナップショットを作成し、スナップショット ID を返す
restore(bucket, snapshotId, options?)	スナップショットからフォークを作成
listCheckpoints(bucket, options?)	バケットのすべてのスナップショットを一覧表示

連携

関数	説明
setupCoordination(bucket, options)	バケット通知を設定
teardownCoordination(bucket, options?)	バケット通知を解除

重要なルール

必ず行うこと： result.data より先に result.error を確認する | 対応する teardown* を呼び出して認証情報を取り消し、バケットを削除する — エージェントはバケットをすぐに大量に残してしまいます | createForks または checkpoint を呼び出す前に、ベースバケットでスナップショットを有効にする | フォークごと、ワークスペースごとにスコープを限定した認証情報を使用し、あるエージェントが侵害されても他のエージェントが危険にさらされないようにする

決して行わないこと： エージェント間で単一の共有アクセスキーを再利用する — スコープを限定した認証情報を使う意味がなくなります | 長時間稼働するサービスでティアダウンを省略する — 削除されていないバケットが蓄積し、課金が発生します | restore が元のバケットを変更すると想定する — 新しいフォークが作成されます

よくある間違い

間違い	修正方法
createForks が "snapshots not enabled" で失敗する	enableSnapshot: true を指定してベースバケットを再作成します
エージェント実行後にフォークがクリーンアップされない	finally ブロックで createForks と teardownForks を必ずセットで呼び出します
Webhook が一度も発火しない	filter の構文を確認します — key、event などを対象とする有効な SQL WHERE 句である必要があります
ワークスペースの TTL がバケットを削除しない	TTL で期限切れになるのは オブジェクト であり、バケット自体ではありません。バケットを削除するには teardownWorkspace を呼び出します
復元したバケットが空である	restore を呼び出す前に listCheckpoints で snapshotId が存在することを確認します

関連スキル

• tigris-snapshots-forking — @tigrisdata/storage の低レベルなスナップショットおよびフォークのプリミティブ
• tigris-bucket-management — バケットの作成、リージョン、スナップショットの設定
• tigris-security-access-control — IAM、スコープを限定したキー、キーのローテーション
• file-storage — フォークまたはワークスペースのバケット内で読み書きを行うための、@tigrisdata/storage のコア SDK

公式ドキュメント

• パッケージ：https://www.npmjs.com/package/@tigrisdata/agent-kit
• ソース：https://github.com/tigrisdata/storage/tree/main/packages/agent-kit