Agent Kit | Tigris Object Storage Documentation

Agent Kit Overview

Agent Kit is a TypeScript library that packages storage workflows for AI agents on Tigris.

Agents need more than object storage. They need isolated storage workspaces they can write into without stepping on each other, snapshots they can roll back to when a run goes sideways, scoped credentials so a single compromised key doesn't expose the whole dataset, and events that fire when another agent finishes its work. Each of those is a handful of API calls against @tigrisdata/storage and @tigrisdata/iam. Agent Kit bundles them into four primitives — forks, workspaces, checkpoints, and coordination — that match how agent systems are built.

Primitives

Forks — give each agent its own isolated, writable copy of a shared dataset using copy-on-write. Instant at any size, zero duplication.
Workspaces — provision a per-agent bucket with optional TTL and scoped credentials. One function, one teardown, no loose keys.
Checkpoints — snapshot a bucket's state and restore into a fresh fork. Inspect what an agent saw at any moment without freezing the original.
Coordination — wire up webhooks on bucket events to trigger the next stage in a multi-agent pipeline. No polling.

Agent Kit composes @tigrisdata/storage for the object storage layer and @tigrisdata/iam for scoped access keys — nothing more.

Installation

To install Agent Kit, use one of the following commands:

npm install @tigrisdata/agent-kit

pnpm add @tigrisdata/agent-kit

yarn add @tigrisdata/agent-kit

Configuration

Every function takes an optional config parameter. Omit it and the underlying SDKs read credentials from the environment. Storage and IAM share the same access-key env vars:

# Required
TIGRIS_STORAGE_ACCESS_KEY_ID=tid_...
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_...

# Optional override
TIGRIS_STORAGE_ENDPOINT=https://t3.storage.dev

Or pass a config object inline:

import { createWorkspace } from "@tigrisdata/agent-kit";

const { data, error } = await createWorkspace("agent-run-42", {
  config: {
    accessKeyId: "tid_...",
    secretAccessKey: "tsec_...",
  },
});

Every function returns a TigrisResponse<T> — a discriminated union of { data: T } on success or { error: Error } on failure. No exceptions are thrown; check result.error before reading result.data.

Forks API

Create Forks

createForks snapshots the source bucket once, then provisions N forks from that snapshot. Each fork is a new bucket, optionally paired with a scoped access key.

import { createForks } from "@tigrisdata/agent-kit";

const { data: forkSet, error } = await createForks("training-data", 5, {
  prefix: "eval-run-42", // optional
  credentials: { role: "Editor" }, // optional
});

Without a prefix, fork bucket names default to ${sourceBucket}-fork-${timestamp}-${i}.

Workspaces API

Create a Workspace

import { createWorkspace } from "@tigrisdata/agent-kit";

const { data: workspace, error } = await createWorkspace("agent-run-abc", {
  ttl: { days: 1 }, // auto-expire objects after 1 day
  enableSnapshots: true, // opt in to snapshots
  credentials: { role: "Editor" }, // scoped access key
  access: "private", // default is private
});

Checkpoints API

Take a Checkpoint

import { checkpoint } from "@tigrisdata/agent-kit";

const { data: ckpt, error } = await checkpoint("training-data", {
  name: "epoch-50", // optional label
});

Coordination API

Configure Notifications

import { setupCoordination } from "@tigrisdata/agent-kit";

const { error } = await setupCoordination("pipeline-bucket", {
  webhookUrl: "https://my-service.com/webhook",
  filter: 'WHERE `key` REGEXP "^results/"', // optional
  auth: { token: process.env.WEBHOOK_SECRET }, // optional
});

Troubleshooting

"Snapshots are not enabled on bucket …" from createForks or checkpoint. Enable via tigris buckets create <name> --enable-snapshots, or the Tigris Console.

createForks returns fewer forks than requested. Bucket creation stopped partway through — common issues include a naming collision or a project-level bucket quota.