tigris-agent-kit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tigris Agent Kit

High-level storage workflows for AI agents on Tigris. Composes

@tigrisdata/storage

and

@tigrisdata/iam

primitives into four building blocks: forks, workspaces, checkpoints, and coordination.

为Tigris上的AI Agent提供高级存储工作流。将

@tigrisdata/storage

和

@tigrisdata/iam

原语组合为四个构建模块：forks、workspaces、checkpoints和coordination。

Prerequisites

前置条件

Before doing anything else, ensure the Tigris CLI is installed:

bash

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

If you need to install it, tell the user: "I'm installing the Tigris CLI (

@tigrisdata/cli

) so we can work with Tigris object storage."

Then install the agent-kit package:

bash

npm install @tigrisdata/agent-kit

在进行任何操作之前，请确保已安装Tigris CLI：

bash

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

如果需要安装，请告知用户："我正在安装Tigris CLI（

@tigrisdata/cli

），以便我们可以使用Tigris对象存储。"

然后安装agent-kit包：

bash

npm install @tigrisdata/agent-kit

Configuration

配置

All functions accept an optional

config

parameter. When omitted, the SDK reads from environment variables:

bash

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

Pass config explicitly when needed:

typescript

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

All functions return a

TigrisResponse<T>

— a discriminated union of

{ data: T }

{ error: Error }

. Always check

error

first.

所有函数都接受可选的

config

参数。如果省略该参数，SDK将从环境变量中读取配置：

bash

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

需要时可显式传入配置：

typescript

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

所有函数都返回

TigrisResponse<T>

——一个由

{ data: T }

或

{ error: Error }

组成的判别联合类型。请始终先检查

error

。

Quick Reference

快速参考

Building Block	Purpose	Functions
Forks	N isolated copies of a shared dataset	`createForks` , `teardownForks`
Workspaces	Dedicated per-agent bucket with TTL	`createWorkspace` , `teardownWorkspace`
Checkpoints	Snapshot bucket state, restore as fork	`checkpoint` , `restore` , `listCheckpoints`
Coordination	Event-driven pipelines via webhooks	`setupCoordination` , `teardownCoordination`

构建模块	用途	函数
Forks	共享数据集的N个独立副本	`createForks` , `teardownForks`
Workspaces	带TTL的Agent专属存储桶	`createWorkspace` , `teardownWorkspace`
Checkpoints	快照存储桶状态并恢复为fork	`checkpoint` , `restore` , `listCheckpoints`
Coordination	通过Webhook实现事件驱动流水线	`setupCoordination` , `teardownCoordination`

When to Use Which

适用场景

Scenario	Use
Spin up N agents that each need their own copy of a dataset	Forks
Give one agent a scratch bucket that auto-cleans after a day	Workspace
Save agent state mid-run so you can branch from it later	Checkpoint + Restore
Trigger downstream agent when an upstream agent writes a result	Coordination

场景	使用模块
启动N个各自需要独立数据集副本的Agent	Forks
为单个Agent提供一个一天后自动清理的临时存储桶	Workspace
保存Agent运行中途的状态，以便后续基于该状态分支	Checkpoint + Restore
当上游Agent写入结果时触发下游Agent	Coordination

Forks — Parallel Agent Copies

Forks — 并行Agent副本

Each fork is an independent bucket with isolated storage. Copy-on-write — instant at any size, zero data duplication. The base bucket must have snapshots enabled.

typescript

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);

Detailed options, lifecycle, and patterns: read

./resources/forks.md

每个fork都是一个拥有独立存储的存储桶。采用写时复制机制——无论数据大小都可即时创建，且无数据重复。基础存储桶必须启用快照功能。

typescript

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 — 存储桶名称
  // fork.credentials?.accessKeyId / secretAccessKey — 每个fork的专属凭据
}

// 吊销凭据并删除所有fork存储桶
await teardownForks(forkSet);

详细的选项、生命周期和模式：请阅读

./resources/forks.md

。

Workspaces — Per-Agent Buckets

Workspaces — Agent专属存储桶

Provision a dedicated bucket for one agent. Optional TTL auto-expires objects; optional scoped credentials enforce least privilege.

typescript

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);

Detailed options, TTL behavior, and patterns: read

./resources/workspaces.md

为单个Agent配置专属存储桶。可选的TTL可自动过期对象；可选的范围凭据可实现最小权限原则。

typescript

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

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

// 使用workspace.bucket和workspace.credentials配合@tigrisdata/storage

await teardownWorkspace(workspace);

详细的选项、TTL行为和模式：请阅读

./resources/workspaces.md

。

Checkpoints — Snapshot and Restore

Checkpoints — 快照与恢复

Capture bucket state at a point in time; restore creates a copy-on-write fork from that snapshot. Original is untouched.

typescript

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

Detailed options and rollback patterns: read

./resources/checkpoints.md

捕获存储桶在某个时间点的状态；恢复操作将基于该快照创建一个写时复制的fork。原存储桶不会被改动。

typescript

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 — 该时间点的独立fork

详细的选项和回滚模式：请阅读

./resources/checkpoints.md

。

Coordination — Event-Driven Pipelines

Coordination — 事件驱动流水线

Wire bucket notifications so writes fire webhooks instead of requiring polling. Use it to chain agents: agent A writes a result, Tigris fires a webhook, agent B starts.

typescript

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');

Filter syntax, webhook auth, and pipeline patterns: read

./resources/coordination.md

配置存储桶通知，使写入操作触发Webhook而非轮询。可用于串联Agent：Agent A写入结果后，Tigris触发Webhook，Agent B随即启动。

typescript

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 Reference

API参考

Forks

Function	Description
`createForks(baseBucket, count, options?)`	Snapshot + fork N times + scoped credentials
`teardownForks(forkSet, options?)`	Revoke credentials + delete forks

函数	描述
`createForks(baseBucket, count, options?)`	快照+创建N个fork+生成范围凭据
`teardownForks(forkSet, options?)`	吊销凭据+删除forks

Workspaces

Function	Description
`createWorkspace(name, options?)`	Create bucket + TTL + scoped credentials
`teardownWorkspace(workspace, options?)`	Revoke credentials + delete bucket

函数	描述
`createWorkspace(name, options?)`	创建存储桶+配置TTL+生成范围凭据
`teardownWorkspace(workspace, options?)`	吊销凭据+删除存储桶

Checkpoints

Function	Description
`checkpoint(bucket, options?)`	Snapshot a bucket, returns snapshot ID
`restore(bucket, snapshotId, options?)`	Fork from a snapshot
`listCheckpoints(bucket, options?)`	List all snapshots for a bucket

函数	描述
`checkpoint(bucket, options?)`	为存储桶创建快照，返回快照ID
`restore(bucket, snapshotId, options?)`	基于快照创建fork
`listCheckpoints(bucket, options?)`	列出存储桶的所有快照

Coordination

Function	Description
`setupCoordination(bucket, options)`	Configure bucket notifications
`teardownCoordination(bucket, options?)`	Clear bucket notifications

函数	描述
`setupCoordination(bucket, options)`	配置存储桶通知
`teardownCoordination(bucket, options?)`	清除存储桶通知

Critical Rules

重要规则

Always: Check

result.error

before

result.data

| Call the corresponding

teardown*

to revoke credentials and delete buckets — agents leak buckets fast | Enable snapshots on the base bucket before calling

createForks

checkpoint

| Use scoped per-fork/per-workspace credentials so one agent's compromise doesn't expose others

Never: Reuse a single shared access key across agents — defeats the point of scoped credentials | Skip teardown on long-running services — orphaned buckets accumulate billing | Assume

restore

mutates the original bucket — it creates a new fork

务必： 在访问

result.data

之前先检查

result.error

| 调用对应的

teardown*

函数来吊销凭据并删除存储桶——Agent很容易造成存储桶泄漏 | 在调用

createForks

或

checkpoint

之前，为基础存储桶启用快照功能 | 使用针对每个fork/workspace的范围凭据，这样单个Agent的泄露不会影响其他Agent

切勿： 在多个Agent之间复用单一共享访问密钥——这违背了范围凭据的设计初衷 | 在长期运行的服务中跳过清理操作——孤立的存储桶会累积账单 | 假设

restore

会修改原存储桶——它会创建一个新的fork

Common Mistakes

常见错误

Mistake	Fix
`createForks` fails with "snapshots not enabled"	Recreate base bucket with `enableSnapshot: true`
Forks not cleaned up after agent run	Always pair `createForks` with `teardownForks` in a `finally` block
Webhook never fires	Check `filter` syntax — must be a valid SQL `WHERE` clause against `key` , `event` , etc.
Workspace TTL doesn't delete bucket	TTL expires objects, not the bucket itself. Call `teardownWorkspace` to delete the bucket
Restored bucket is empty	Verify `snapshotId` exists with `listCheckpoints` before calling `restore`

错误	修复方案
`createForks` 因“snapshots not enabled”失败	重新创建基础存储桶并设置 `enableSnapshot: true`
Agent运行结束后forks未被清理	始终在 `finally` 块中搭配使用 `createForks` 和 `teardownForks`
Webhook从未触发	检查 `filter` 语法——必须是针对 `key` 、 `event` 等字段的有效SQL `WHERE` 子句
Workspace的TTL未删除存储桶	TTL仅过期对象，而非存储桶本身。调用 `teardownWorkspace` 来删除存储桶
恢复后的存储桶为空	在调用 `restore` 之前，使用 `listCheckpoints` 验证 `snapshotId` 是否存在

Related Skills

Official Documentation

官方文档

包地址：https://www.npmjs.com/package/@tigrisdata/agent-kit
源码地址：https://github.com/tigrisdata/storage/tree/main/packages/agent-kit

tigris-agent-kit

Original

Translation

Tigris Agent Kit

Tigris Agent Kit

Prerequisites

前置条件

Configuration

配置

Quick Reference

快速参考

When to Use Which

适用场景

Forks — Parallel Agent Copies

Forks — 并行Agent副本

Workspaces — Per-Agent Buckets

Workspaces — Agent专属存储桶

Checkpoints — Snapshot and Restore

Checkpoints — 快照与恢复

Coordination — Event-Driven Pipelines

Coordination — 事件驱动流水线

API Reference

API参考

Forks

Forks

Workspaces

Workspaces

Checkpoints

Checkpoints

Coordination

Coordination

Critical Rules

重要规则

Common Mistakes

常见错误

Related Skills

相关技能

Official Documentation

官方文档