tigris-agent-kit

name

tigris-agent-kit

description

Use when building AI agent storage workflows on Tigris — forks for isolated dataset copies, workspaces for per-agent buckets with TTL, checkpoints for snapshot/restore, and coordination for event-driven pipelines via bucket webhooks. Triggers on "@tigrisdata/agent-kit", "agent storage", "agent workspace", "agent fork", "isolated agent environment", "checkpoint and restore", "bucket webhook", "multi-agent pipeline"

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.

Prerequisites

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

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:

npm install @tigrisdata/agent-kit

Configuration

All functions accept an optional config parameter. When omitted, the SDK reads from environment variables:

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

Pass config explicitly when needed:

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

All functions return a TigrisResponse<T> — a discriminated union of { data: T } or { error: Error }. Always check error first.

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

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.

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.

Workspaces — Per-Agent Buckets

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

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.

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.

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 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 or 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

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

Related Skills

• tigris-snapshots-forking — Lower-level snapshot and fork primitives in @tigrisdata/storage
• tigris-bucket-management — Bucket creation, regions, snapshot configuration
• tigris-security-access-control — IAM, scoped keys, key rotation
• file-storage — Core @tigrisdata/storage SDK for reading/writing within fork or workspace buckets

Official Documentation

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