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:

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:

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 to list and download.

Stream artifact tags

Tagging with a sessionId emits artifact.tagged on that session with id, kind, key, title, data, and source.