# 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`](https://www.npmjs.com/package/@tigrisdata/storage) for the object storage layer and [`@tigrisdata/iam`](https://www.npmjs.com/package/@tigrisdata/iam) for scoped access keys — nothing more.

## Installation

To install Agent Kit, use one of the following commands:
```bash
npm install @tigrisdata/agent-kit
```
```bash
pnpm add @tigrisdata/agent-kit
```
```bash
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:
```bash
# 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:
```typescript
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.
```typescript
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
```typescript
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
```typescript
import { checkpoint } from "@tigrisdata/agent-kit";

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

### Coordination API
#### Configure Notifications
```typescript
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.

## Resources
- [Snapshots and forks](/content/docs/buckets/snapshots-and-forks/index.html)
- [Object notifications](/content/docs/buckets/object-notifications/index.html)  
- [`@tigrisdata/storage`](https://www.npmjs.com/package/@tigrisdata/storage)  
- [`@tigrisdata/iam`](https://www.npmjs.com/package/@tigrisdata/iam)
- [Tigris on GitHub](https://github.com/tigrisdata/storage)