tigris-agent-kit

Tigris Agent Kit

面向 Tigris 上 AI Agent 的高级存储工作流。将 @tigrisdata/storage 和 @tigrisdata/iam 的基础功能组合为四个构建模块：分支副本、工作区、检查点和协作。

前提条件

开始任何操作之前，请确保已安装 Tigris CLI：

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

如果需要安装，请告知用户：“我正在安装 Tigris CLI（@tigrisdata/cli），以便我们使用 Tigris 对象存储。”

然后安装 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
工作区	为每个 Agent 提供带 TTL 的专用存储桶	createWorkspace、teardownWorkspace
检查点	快照存储桶状态，并还原为分支副本	checkpoint、restore、listCheckpoints
协作	通过 Webhook 构建事件驱动的流水线	setupCoordination、teardownCoordination

如何选择

场景	使用
启动 N 个各自需要数据集副本的 Agent	分支副本
为一个 Agent 提供临时存储桶，并在一天后自动清理	工作区
在运行期间保存 Agent 状态，以便之后从中创建分支	检查点 + 还原
上游 Agent 写入结果后触发下游 Agent	协作

分支副本 — 并行 Agent 副本

每个分支副本都是一个独立的存储桶，存储彼此隔离。采用写时复制机制，无论大小都能即时创建，且不会重复存储数据。基础存储桶必须启用快照。

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。

工作区 — 每个 Agent 独立的存储桶

为一个 Agent 配置专用存储桶。可选的 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，而无需轮询。可用它串联 Agent：Agent A 写入结果后，Tigris 会触发 Webhook，随后 Agent 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.error，再检查 result.data | 调用对应的 teardown* 撤销凭据并删除存储桶——Agent 很快就会泄漏存储桶 | 在调用 createForks 或 checkpoint 前，为基础存储桶启用快照 | 使用按分叉/工作区限定的凭据，避免一个 Agent 遭到入侵后导致其他 Agent 暴露

切勿： 在多个 Agent 之间重复使用同一个共享访问密钥——这会让限定凭据失去意义 | 在长时间运行的服务中跳过清理——未清理的存储桶会不断累积费用 | 假设 restore 会修改原存储桶——它会创建一个新的分叉

常见错误

错误	修复方法
createForks 失败，并提示“snapshots not enabled”	使用 enableSnapshot: true 重新创建基础存储桶
Agent 运行后未清理分叉	始终在 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

官方文档

• Package：https://www.npmjs.com/package/@tigrisdata/agent-kit
• Source：https://github.com/tigrisdata/storage/tree/main/packages/agent-kit