# 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**.

## When to use[​](#when-to-use "Direct link to When to use")

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"

## Install the skill[​](#install-the-skill "Direct link to Install the skill")

```
npx skills add tigrisdata/skills --skill tigris-agent-kit
```

This page is generated from [`skills/tigris-agent-kit/SKILL.md`](https://github.com/tigrisdata/skills/blob/main/skills/tigris-agent-kit/SKILL.md) in the [tigrisdata/skills](https://github.com/tigrisdata/skills) repository.

## Prerequisites[​](#prerequisites "Direct link to 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[​](#configuration "Direct link to 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[​](#quick-reference "Direct link to 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[​](#when-to-use-which "Direct link to 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[​](#forks--parallel-agent-copies "Direct link to 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[​](#workspaces--per-agent-buckets "Direct link to 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[​](#checkpoints--snapshot-and-restore "Direct link to 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[​](#coordination--event-driven-pipelines "Direct link to 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[​](#api-reference "Direct link to API Reference")

### Forks[​](#forks "Direct link to Forks")

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

### Workspaces[​](#workspaces "Direct link to Workspaces")

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

### Checkpoints[​](#checkpoints "Direct link to 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[​](#coordination "Direct link to Coordination")

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

## Critical Rules[​](#critical-rules "Direct link to 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[​](#common-mistakes "Direct link to 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[​](#related-skills "Direct link to 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[​](#official-documentation "Direct link to Official Documentation")

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