Tigris Agent Kit
High-level storage workflows for AI agents on Tigris. Composes
and
primitives into four building blocks:
forks,
workspaces,
checkpoints, and
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 (
) so we can work with Tigris object storage."
Then install the agent-kit package:
bash
npm install @tigrisdata/agent-kit
Configuration
All functions accept an optional
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
— a discriminated union of
or
. Always check
first.
Quick Reference
| Building Block | Purpose | Functions |
|---|
| Forks | N isolated copies of a shared dataset | , |
| Workspaces | Dedicated per-agent bucket with TTL | , |
| Checkpoints | Snapshot bucket state, restore as fork | , , |
| Coordination | Event-driven pipelines via webhooks | , |
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 |
Forks — Parallel Agent Copies
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
.
Workspaces — Per-Agent Buckets
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
.
Checkpoints — Snapshot and Restore
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
.
Coordination — Event-Driven Pipelines
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
.
API Reference
Forks
| Function | Description |
|---|
createForks(baseBucket, count, options?)
| Snapshot + fork N times + scoped credentials |
teardownForks(forkSet, options?)
| Revoke credentials + delete forks |
Workspaces
| Function | Description |
|---|
createWorkspace(name, options?)
| Create bucket + TTL + scoped credentials |
teardownWorkspace(workspace, options?)
| Revoke credentials + delete bucket |
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 |
Coordination
| Function | Description |
|---|
setupCoordination(bucket, options)
| Configure bucket notifications |
teardownCoordination(bucket, options?)
| Clear bucket notifications |
Critical Rules
Always: Check
before
| Call the corresponding
to revoke credentials and delete buckets — agents leak buckets fast | Enable snapshots on the base bucket before calling
or
| 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
mutates the original bucket — it creates a new fork
Common Mistakes
| Mistake | Fix |
|---|
| fails with "snapshots not enabled" | Recreate base bucket with |
| Forks not cleaned up after agent run | Always pair with in a block |
| Webhook never fires | Check syntax — must be a valid SQL clause against , , etc. |
| Workspace TTL doesn't delete bucket | TTL expires objects, not the bucket itself. Call to delete the bucket |
| Restored bucket is empty | Verify exists with before calling |
Related Skills
- tigris-snapshots-forking — Lower-level snapshot and fork primitives in
- tigris-bucket-management — Bucket creation, regions, snapshot configuration
- tigris-security-access-control — IAM, scoped keys, key rotation
- file-storage — Core SDK for reading/writing within fork or workspace buckets
Official Documentation