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.