tigris-agent-kit

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

When to Use Which

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

Workspaces

Checkpoints

Coordination

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

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