# Artifacts

Artifacts are durable outputs such as reviewed pull requests or
reports. Records persist across sessions, update by key, and can be
listed, streamed, or downloaded.

## Artifact kinds

Declare kinds in `bot/artifacts.ts`:

```ts
import { z } from "zod";
import { defineArtifacts } from "@grok/agent-sdk/artifacts";

export default defineArtifacts({
  kinds: {
    "reviewed-pr": {
      description: "A pull request this agent reviewed.",
      schema: z.object({ url: z.string(), verdict: z.string() }),
    },
  },
  agentTool: true,
});
```

| Option | Contract |
| --- | --- |
| `kinds` | Kind names, each with a non-empty `description` and optional Zod `schema` |
| `agentTool` | Expose `tag_artifact` to the model. Requires at least one declared kind |
| `max` | Retention cap, default `1000`. Only local and self-hosted servers evict, oldest-updated first |

With declared kinds, `tag` rejects any other kind, and without them it accepts any kind name and defaults an omitted kind to `"artifact"`. `tag` stores `data` as the kind's schema parsed it, with defaults and coercions applied.

## Tag artifacts from host code

Host code gets an `ArtifactsApi` with `tag` and `list`:

```ts
await ctx.artifacts.tag({
  kind: "reviewed-pr",
  key: prUrl,
  title: `Reviewed ${prUrl}`,
  data: { url: prUrl, verdict: "approve" },
});
```

`tag` returns an `ArtifactRecord`.

| Field | Contract |
| --- | --- |
| `kind` | Declared or free-form kind |
| `data` | Required JSON data, validated by the kind's schema |
| `key` | Optional upsert key, unique across the agent and all kinds |
| `title` | Optional display title |
| `sessionId`, `turnId` | Optional session or turn attribution |
| `source` | `"host"` or `"model"`. `tag` defaults to `"host"` |
| `contents` | Tag only. String or bytes served by the content route |
| `contentType` | Tag only. MIME type for `contents` |
| `id` | Record only. Stable ID derived from `key`, or a generated ID |
| `content` | Record only. `{ size, contentType? }` metadata |
| `createdAt`, `updatedAt` | Record only. ISO-8601 timestamps |

Tool, hook, and channel-event contexts are session-bound and fill
`sessionId` and the current `turnId`. Channel routes, channel
`onStart`, schedules, and reminders get an unbound API, so pass
`sessionId` to attribute an artifact.

Re-tagging a key without `contents` keeps its payload unless
`sessionId` changes.

## Expose `tag_artifact` to the model

With `agentTool: true`, the model gets a generated `tag_artifact` tool
that accepts the declared kinds and validates data with their schemas.
Kind descriptions tell the model what each kind is for. An authored
`tag_artifact` tool takes precedence.

## List artifacts

`list({ kind?, sessionId? })` returns matching records, newest update
first. HTTP callers use the
[artifact routes](/docs/reference/http-api.md#list-and-download-artifacts) to list
and download.

## Stream artifact tags

Tagging with a `sessionId` emits
[`artifact.tagged`](/docs/reference/sessions.md#stream-events) on that session with
`id`, `kind`, `key`, `title`, `data`, and `source`.
