@cursor/bdk 0.2.1

package/dist/docs/reference/agent-config.md

@@ -0,0 +1,188 @@
+# Agent config
+
+`bot/agent.ts` default-exports `defineAgent(config)`: which model runs
+the agent and its local harness defaults.
+Everything is optional on the root agent.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/docs/index.md#bdk-package-availability).
+
+```ts
+import { defineAgent } from "@cursor/bdk";
+
+export default defineAgent({
+  model: {
+    id: "grok-4.5",
+    params: [
+      { id: "effort", value: "high" },
+      { id: "fast", value: "true" },
+    ],
+  }, // optional; this is the default
+});
+```
+
+## Agent fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | string or `{ id, params }` | Cursor model for turns. Defaults to `grok-4.5` with `effort=high`, `fast=true` on the root agent. Subagents omit it to inherit. |
+| `name` | string | Display name override. Defaults to the package name or directory name. |
+| `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
+| `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
+| `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults. See [Local options](#local-options). |
+| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `bdk deploy`: the pod's egress allowlist and the secret names the agent expects. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
+| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
+
+## Model
+
+`model` is a Cursor model id string, or `{ id, params }`. Effort and
+speed are params, not id suffixes. The SDK rejects suffix-style ids
+like `grok-4.5-fast`:
+
+```ts
+model: {
+  id: "grok-4.5",
+  params: [
+    { id: "effort", value: "high" },
+    { id: "fast", value: "true" },
+  ],
+}
+```
+
+A plain string works when you don't need params:
+
+```ts
+model: "composer-2.5",
+```
+
+## Local options
+
+`local` sets local-harness defaults.
+
+`local.workspaceDir` points every session at one shared harness cwd,
+for agents that work inside an existing checkout. It takes precedence
+over `cwd`, and a per-send `workspaceDir` still wins over both.
+Sessions share a working tree, so a file one turn writes is visible to
+the next.
+
+`local.sandbox` runs the harness inside Cursor's local sandbox. It's
+off by default: shell then auto-approves and inherits the serve process
+environment, including any credentials the host holds. Turn it on for
+agents whose turns read untrusted input (webhook payloads, PR diffs,
+inbound chat); it's a tool boundary, not a prompt-level one.
+
+### Local cwd
+
+`local.cwd` sets the parent directory for local harness workspaces. Each
+session uses `<cwd>/<sessionId>` unless a per-send `workspaceDir` overrides
+it.
+
+Session workspaces are real Cursor project directories. The harness loads
+`AGENTS.md` and `.cursor` config from ancestor directories. An agent nested
+in another git repo (a monorepo package) defaults to a per-project
+cache directory under `~/.cache` when you omit `cwd`, so the enclosing checkout
+does not leak rules, skills, or MCP servers into the turn. A standalone git
+root keeps the in-project session workspace. Point `cwd` at a checkout only
+when the agent should inherit that tree.
+
+## Harness tools
+
+Use `tools` to limit which built-in Cursor harness tools the model can
+call. Omit it to keep the standard toolset. When you set it, the model
+gets only the tools you list. An empty list disables all native
+built-in tools. New platform tools stay disabled until you add them.
+
+```ts
+export default defineAgent({
+  model: "composer-2.5",
+  // Read-only triage agent: search and read only.
+  // No shell, no edits, no subagents.
+  tools: ["read", "grep", "glob", "ls"],
+});
+```
+
+BDK always adds `"mcp"` to a configured allowlist, because
+authored server tools in `bot/tools/` reach the model over MCP. MCP
+can also expose declared connections and servers from the harness
+directory's ambient `.cursor` config. To exclude a checkout's MCP
+servers, point `local.cwd` outside the checkout. See
+[Local cwd](#local-cwd). `local.sandbox` makes MCP tool calls fail
+closed.
+
+Use the SDK's public tool names, including `"shell"`, `"read"`,
+`"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
+fail the turn with a `ConfigurationError`.
+
+Two names have broader effects:
+
+- `"shell"` also grants shell input. Tools with
+  `execution: "agent"` need it to run their scripts. Discovery warns
+  when your allowlist would prevent those tools from running.
+- `"task"` lets the root agent start subagents. Each subagent keeps
+  its own curated toolset.
+
+The allowlist controls which tools the model can call. It does not
+isolate the serve host. For agents that process untrusted input, also
+set `local: { sandbox: true }`.
+
+## Concurrency
+
+`concurrency.maxRunningTurns` caps how many model turns run at once
+across all of the agent's sessions (positive integer, hard cap 200).
+When every slot is busy, newly admitted turns queue FIFO instead of
+failing: the stream records a durable `turn.queued` event with the
+queue position, `GET /v1/sessions` reports `queued: true`, and each
+queued turn starts as soon as a slot frees. A queued turn still counts
+as running for busy semantics: follow-ups preempt it, and direct
+write-effect tool calls get `409 session_busy`. Omit for unlimited.
+
+```ts
+export default defineAgent({
+  concurrency: { maxRunningTurns: 3 },
+});
+```
+
+## Built-in tools
+
+`builtinTools` opts into framework-provided model-facing tools. Each
+enabled capability shows up as ordinary server tools, so turns, direct
+calls, `info`, and the playground treat them like authored tools. Authored tools with the same name win, with a
+warning, and like all server tools they run on the local runtime.
+
+`builtinTools: { reminders: true }` adds three tools bound to the
+current conversation over `host.reminders`: `reminders_create`,
+`reminders_list`, and `reminders_cancel`. Sessions without a
+continuation key can't arm reminders. See
+[Schedules and reminders](/docs/reference/schedules.md#reminders).
+
+## Serve programmatically
+
+`serve(dirOrProject, options)` embeds the server in your own process:
+
+```ts
+import { serve } from "@cursor/bdk";
+
+const handle = await serve("./my-agent", {
+  port: 3000,
+  apiKey: process.env.CURSOR_API_KEY,
+});
+console.log(`listening on ${handle.url}`);
+// handle.callTool(...), handle.dispatchSchedule("heartbeat"),
+// handle.createReminder(...), handle.project, await handle.close()
+```
+
+Host settings match the documented [CLI](/docs/reference/cli.md) `serve` flags.
+`serve()` also accepts `discovery` (project-loading options) and
+`mode: "single" | "multi"`. Pass `apiKey` or use the same Cursor
+credential as the CLI: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, or `bdk login`.
+
+## Related
+
+- [Instructions](/docs/reference/instructions.md): the required half of a minimal
+  agent
+- [CLI](/docs/reference/cli.md): the `serve` flags `serve()` accepts
+- [Sessions](/docs/reference/sessions.md): workspaces, identifiers, and turn admission
+- [Schedules](/docs/reference/schedules.md): reminder tools opted in here

package/dist/docs/reference/artifacts.html

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en-US" dir="ltr">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>Artifacts | Grok Bot Development Kit (BDK)</title>
+    <meta name="description" content="Declare, tag, list, stream, and download durable agent outputs.">
+    <meta name="generator" content="VitePress v1.6.4">
+    <link rel="preload stylesheet" href="/docs/assets/style.C130MVnH.css" as="style">
+    <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
+    
+    <script type="module" src="/docs/assets/app.JVQvbRO-.js"></script>
+    <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
+    <link rel="modulepreload" href="/docs/assets/chunks/framework.BNw1pucY.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/theme.zK3OJa_C.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/katex.DkKDou_j.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/dagre-KV5264BT.DMGGa3uA.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/cose-bilkent-S5V4N54A.Buf3seya.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/c4Diagram-AHTNJAMY.D0AsQFSX.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/flowDiagram-DWJPFMVM.6_Aky-ut.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/erDiagram-SMLLAGMA.DQT1Hnwf.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/gitGraphDiagram-UUTBAWPF.CGd_eJbn.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/ganttDiagram-T4ZO3ILL.DHIwqnqN.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/infoDiagram-42DDH7IO.Cd4gMyAz.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/pieDiagram-DEJITSTG.DfAl9sy4.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/quadrantDiagram-34T5L4WZ.CNuqFRBj.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/xychartDiagram-5P7HB3ND.e8BPicch.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/requirementDiagram-MS252O5E.DJ5CmTCl.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/sequenceDiagram-FGHM5R23.BRn9WcrR.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-6PBFFD2Q.NPiy3Hz7.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-v2-HSJHXN6E.NPiy3Hz7.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-FHFEXIEX.F12urmm7.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2._auCa3fR.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/journeyDiagram-VCZTEJTY.AWLXtelc.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/timeline-definition-GMOUNBTQ.B7GiQBeC.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/mindmap-definition-QFDTVHPH.By_RAMaP.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/kanban-definition-6JOO6SKY.CagPhAn5.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/sankeyDiagram-XADWPNL6.D-T_AKJj.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-TYMM5635.Dw8W9BTk.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-MMDJMWI5.DRvQV16Z.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/blockDiagram-DXYQGD6D.CQXAOmqd.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-5BDNPKRD.DDjnwRmY.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/architectureDiagram-Q4EWVU46.CAY_TPVz.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/ishikawaDiagram-UXIWVN3A.D1uw7MXq.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/vennDiagram-DHZGUBPP.D0niwuY_.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-G4DWMVQ6.RwyrIr8Q.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/wardleyDiagram-NUSXRM2D.DKaqpT7K.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/virtual_mermaid-config.DDnGl6nM.js">
+    <link rel="modulepreload" href="/docs/assets/reference_artifacts.md.IFFC5Zln.lean.js">
+    <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
+    <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
+    <link rel="alternate" type="text/plain" href="/docs/llms.txt">
+    <link rel="alternate" type="text/markdown" href="/docs/reference/artifacts.md">
+  </head>
+  <body>
+    <div id="app"><div class="Layout" data-v-76086e96><!--[--><!--]--><!--[--><span tabindex="-1" data-v-97fb5898></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-97fb5898>Skip to content</a><!--]--><!----><header class="VPNav" data-v-76086e96 data-v-781b1279><div class="VPNavBar" data-v-781b1279 data-v-b33015df><div class="wrapper" data-v-b33015df><div class="container" data-v-b33015df><div class="title" data-v-b33015df><div class="VPNavBarTitle has-sidebar" data-v-b33015df data-v-a0c466dc><a class="title" href="/docs/" data-v-a0c466dc><!--[--><!--]--><!----><span data-v-a0c466dc>Grok Bot Development Kit (BDK)</span><!--[--><!--[--><!--[--><!--[--><span class="bdk-version" title="BDK 0.2.1 (@cursor/bdk package)" data-v-d89e5038>0.2.1</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-b33015df><div class="content-body" data-v-b33015df><!--[--><!--]--><div class="VPNavBarSearch search" data-v-b33015df><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-b33015df data-v-8906c751><span id="main-nav-aria-label" class="visually-hidden" data-v-8906c751> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/mcp-oauth.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/github.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Integrations</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/security-reviewer.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-b33015df data-v-959ed110><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-959ed110 data-v-79ad6d7f data-v-0a895de9><span class="check" data-v-0a895de9><span class="icon" data-v-0a895de9><!--[--><span class="vpi-sun sun" data-v-79ad6d7f></span><span class="vpi-moon moon" data-v-79ad6d7f></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-b33015df data-v-a713f501 data-v-1d7aa189><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-1d7aa189><span class="vpi-more-horizontal icon" data-v-1d7aa189></span></button><div class="menu" data-v-1d7aa189><div class="VPMenu" data-v-1d7aa189 data-v-e34b7e14><!----><!--[--><!--[--><!----><div class="group" data-v-a713f501><div class="item appearance" data-v-a713f501><p class="label" data-v-a713f501>Appearance</p><div class="appearance-action" data-v-a713f501><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-a713f501 data-v-79ad6d7f data-v-0a895de9><span class="check" data-v-0a895de9><span class="icon" data-v-0a895de9><!--[--><span class="vpi-sun sun" data-v-79ad6d7f></span><span class="vpi-moon moon" data-v-79ad6d7f></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-b33015df data-v-cb5d0edb><span class="container" data-v-cb5d0edb><span class="top" data-v-cb5d0edb></span><span class="middle" data-v-cb5d0edb></span><span class="bottom" data-v-cb5d0edb></span></span></button></div></div></div></div><div class="divider" data-v-b33015df><div class="divider-line" data-v-b33015df></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-76086e96 data-v-6f794310><div class="container" data-v-6f794310><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-6f794310><span class="vpi-align-left menu-icon" data-v-6f794310></span><span class="menu-text" data-v-6f794310>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-6f794310 data-v-bab84d9c><button data-v-bab84d9c>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-76086e96 data-v-4daa293d><div class="curtain" data-v-4daa293d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-4daa293d><span class="visually-hidden" id="sidebar-aria-label" data-v-4daa293d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Getting started</h2><!----></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Building your first agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Integrations</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Webhooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Cursor Automations</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>OpenTelemetry</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/gitlab.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>GitLab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/bitbucket.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Bitbucket</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Extensions</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/grokbot-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/improve.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Self-improvement</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/jev.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Jev</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Guides</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>MCP</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/hooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Peer agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/deployment.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/evals.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hillclimbing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Build with a coding agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Troubleshooting</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Templates</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/thermo-review.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Thermo review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/thermo-quality-review.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Thermo quality review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Agentic Approver</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible has-active" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/evals.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-76086e96 data-v-258cbba4><div class="VPDoc has-sidebar has-aside" data-v-258cbba4 data-v-afe580da><!--[--><!--]--><div class="container" data-v-afe580da><div class="aside" data-v-afe580da><div class="aside-curtain" data-v-afe580da></div><div class="aside-container" data-v-afe580da><div class="aside-content" data-v-afe580da><div class="VPDocAside" data-v-afe580da data-v-fb5275a4><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-fb5275a4 data-v-b3783f18><div class="content" data-v-b3783f18><div class="outline-marker" data-v-b3783f18></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b3783f18>On this page</div><ul class="VPDocOutlineItem root" data-v-b3783f18 data-v-72702c6e><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-fb5275a4></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-afe580da><div class="content-container" data-v-afe580da><!--[--><!--]--><main class="main" data-v-afe580da><div style="position:relative;" class="vp-doc _docs_reference_artifacts" data-v-afe580da><div><h1 id="artifacts" tabindex="-1">Artifacts <a class="header-anchor" href="#artifacts" aria-label="Permalink to &quot;Artifacts&quot;">​</a></h1><p>Artifacts are durable outputs such as reviewed pull requests, reports, or decision records. An artifact kind defines the data it accepts, and the artifacts API tags or updates records by key. Records persist across sessions and can be listed, streamed, or downloaded.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="artifact-kinds" tabindex="-1">Artifact kinds <a class="header-anchor" href="#artifact-kinds" aria-label="Permalink to &quot;Artifact kinds&quot;">​</a></h2><p>Author <code>bot/artifacts.ts</code> with <code>defineArtifacts</code> from <code>@cursor/bdk/artifacts</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineArtifacts } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/artifacts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineArtifacts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  kinds: {</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;reviewed-pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;A pull request this agent reviewed.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      schema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ url: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), verdict: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    report: { description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;A generated report.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agentTool: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>kinds</code></td><td>Map of accepted kind names to a non-empty <code>description</code> and optional Zod <code>schema</code></td></tr><tr><td><code>agentTool</code></td><td>Expose <code>tag_artifact</code> to the model; requires at least one declared kind</td></tr><tr><td><code>max</code></td><td>Positive retention cap; defaults to <code>1000</code> and evicts the oldest-updated record</td></tr></tbody></table><p>With declared kinds, <code>tag</code> rejects any other kind. With no registry, it accepts free-form kind names and defaults an omitted kind to <code>&quot;artifact&quot;</code>. A kind&#39;s schema validates <code>data</code>, and the parsed value is stored, including schema defaults and coercions.</p><h2 id="tag-artifacts-from-host-code" tabindex="-1">Tag artifacts from host code <a class="header-anchor" href="#tag-artifacts-from-host-code" aria-label="Permalink to &quot;Tag artifacts from host code&quot;">​</a></h2><p>Tools, hooks, channel handlers, channel <code>onStart</code>, schedules, and reminders receive an <code>ArtifactsApi</code> with <code>tag</code> and <code>list</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.artifacts.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">tag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;reviewed-pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  key: prUrl,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`Reviewed ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  data: { url: prUrl, verdict: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;approve&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Tag field</th><th>Contract</th></tr></thead><tbody><tr><td><code>data</code></td><td>Required JSON data, validated when the kind has a schema</td></tr><tr><td><code>kind</code></td><td>Declared or free-form kind</td></tr><tr><td><code>key</code></td><td>Agent-wide upsert key; the same key updates one record across kinds</td></tr><tr><td><code>title</code></td><td>Optional display title</td></tr><tr><td><code>contents</code></td><td>String or bytes served by the content route</td></tr><tr><td><code>contentType</code></td><td>MIME type for <code>contents</code></td></tr><tr><td><code>sessionId</code>, <code>turnId</code></td><td>Attribute the artifact to a session or turn</td></tr><tr><td><code>source</code></td><td><code>&quot;host&quot;</code> or <code>&quot;model&quot;</code>; defaults to <code>&quot;host&quot;</code></td></tr></tbody></table><p>Tool, hook, result, and channel-event contexts are session-bound, so they fill <code>sessionId</code> and the current <code>turnId</code>. Channel routes, <code>onStart</code>, schedules, and reminders receive an unbound facade; pass <code>sessionId</code> to attribute an artifact.</p><p>Re-tagging a key without <code>contents</code> keeps its file or blob when the <code>sessionId</code> stays the same. Rebinding the key to another session without new contents removes the previous payload. <code>tag</code> returns the stored <code>ArtifactRecord</code>.</p><table tabindex="0"><thead><tr><th>Record field</th><th>Contract</th></tr></thead><tbody><tr><td><code>id</code></td><td>Stable ID derived from <code>key</code>, or a generated ID when no key is set</td></tr><tr><td><code>kind</code>, <code>data</code></td><td>Validated kind and JSON payload</td></tr><tr><td><code>key</code>, <code>title</code></td><td>Optional upsert key and display title</td></tr><tr><td><code>content</code></td><td>Optional <code>{ size, contentType? }</code> metadata</td></tr><tr><td><code>sessionId</code>, <code>turnId</code></td><td>Optional session attribution</td></tr><tr><td><code>source</code></td><td><code>&quot;host&quot;</code> or <code>&quot;model&quot;</code></td></tr><tr><td><code>createdAt</code>, <code>updatedAt</code></td><td>ISO-8601 timestamps</td></tr></tbody></table><h2 id="expose-tag-artifact-to-the-model" tabindex="-1">Expose <code>tag_artifact</code> to the model <a class="header-anchor" href="#expose-tag-artifact-to-the-model" aria-label="Permalink to &quot;Expose `tag_artifact` to the model&quot;">​</a></h2><p>With <code>agentTool: true</code>, the <code>tag_artifact</code> server tool materializes from the kinds registry. Its input accepts the declared kinds and validates their data with the same schemas as host-side tagging. The kind descriptions tell the model which output each one represents.</p><p>An authored tool named <code>tag_artifact</code> takes precedence over the generated tool.</p><h2 id="list-artifacts" tabindex="-1">List artifacts <a class="header-anchor" href="#list-artifacts" aria-label="Permalink to &quot;List artifacts&quot;">​</a></h2><p><code>list({ kind?, sessionId? })</code> returns matching records newest-updated first. HTTP callers can list records and download content through the <a href="./http-api.html#list-and-download-artifacts">artifact routes</a>.</p><h2 id="stream-artifact-tags" tabindex="-1">Stream artifact tags <a class="header-anchor" href="#stream-artifact-tags" aria-label="Permalink to &quot;Stream artifact tags&quot;">​</a></h2><p>Tagging an artifact with a <code>sessionId</code> emits <code>artifact.tagged</code> on that session. Its event data contains <code>id</code>, <code>kind</code>, <code>key</code>, <code>title</code>, <code>data</code>, and <code>source</code>. See <a href="./sessions.html#stream-events">Stream events</a> for the event envelope.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./sessions.html">Sessions</a></li><li><a href="./tools.html">Tools</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./http-api.html">HTTP API</a></li></ul></div></div></main><footer class="VPDocFooter" data-v-afe580da data-v-feab96e0><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-feab96e0><span class="visually-hidden" id="doc-footer-aria-label" data-v-feab96e0>Pager</span><div class="pager" data-v-feab96e0><a class="VPLink link pager-link prev" href="/docs/reference/evals.html" data-v-feab96e0><!--[--><span class="desc" data-v-feab96e0>Previous page</span><span class="title" data-v-feab96e0>Evals</span><!--]--></a></div><div class="pager" data-v-feab96e0><a class="VPLink link pager-link next" href="/docs/reference/sessions.html" data-v-feab96e0><!--[--><span class="desc" data-v-feab96e0>Next page</span><span class="title" data-v-feab96e0>Sessions & streaming</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"building-with-agents.md\":\"-fcjCmJU\",\"deployment.md\":\"nGo1yIsa\",\"evals.md\":\"CCAtNcuL\",\"guides_agent-to-agent.md\":\"CGkicXeB\",\"guides_bitbucket.md\":\"Cb3LPKt3\",\"guides_cloud-agents.md\":\"BuEkDCwo\",\"guides_convert-automation.md\":\"Ci-Y2iD5\",\"guides_github.md\":\"C2_DSWlE\",\"guides_gitlab.md\":\"BM27P43u\",\"guides_grokbot-agents.md\":\"yxVbSlKA\",\"guides_hooks.md\":\"BWoiNaMq\",\"guides_improve.md\":\"COtL-6ft\",\"guides_jev.md\":\"BNDm14Gy\",\"guides_mcp-oauth.md\":\"Cu6mhZ_3\",\"guides_opentelemetry.md\":\"DLlIB5rv\",\"guides_slack.md\":\"ZbHQETOT\",\"guides_webhooks.md\":\"D0furjw0\",\"hillclimbing.md\":\"Biy0m-Qb\",\"index.md\":\"CVc_oOA3\",\"quickstart.md\":\"wG4shE1f\",\"reference_agent-config.md\":\"DzGI777n\",\"reference_artifacts.md\":\"IFFC5Zln\",\"reference_channels.md\":\"mbNtKCiR\",\"reference_cli.md\":\"BK2QUH67\",\"reference_connections.md\":\"_XpKiOaF\",\"reference_evals.md\":\"DqNyHMA6\",\"reference_extensions.md\":\"CPPrkWlJ\",\"reference_hooks.md\":\"Dg3dEugd\",\"reference_http-api.md\":\"BZOvhCqY\",\"reference_instructions.md\":\"Bdwscs4G\",\"reference_playground.md\":\"BdQzRJc2\",\"reference_project-layout.md\":\"CpLQ9j4K\",\"reference_prompt.md\":\"BQZB4eaV\",\"reference_schedules.md\":\"BVU5EFbz\",\"reference_sessions.md\":\"BtpTjZmh\",\"reference_skills.md\":\"Cy00QMKS\",\"reference_subagents.md\":\"B8oyeXOI\",\"reference_tools.md\":\"hg2Wi5Bq\",\"templates_agentic-owners.md\":\"BykUiZ8j\",\"templates_security-reviewer.md\":\"DXMmKl_o\",\"templates_thermo-quality-review.md\":\"Dg1p1MsG\",\"templates_thermo-review.md\":\"Dlylkowj\",\"templates_triage.md\":\"CvJyx81N\",\"troubleshooting.md\":\"BzZSu1Gz\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Grok Bot Development Kit (BDK)\",\"description\":\"Build and serve bots and agents from versioned Markdown and TypeScript.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.2.1\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Integrations\",\"link\":\"/guides/github\"},{\"text\":\"Templates\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Building your first agent\",\"link\":\"/quickstart\"}]},{\"text\":\"Integrations\",\"collapsed\":false,\"items\":[{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Webhooks\",\"link\":\"/guides/webhooks\"},{\"text\":\"Cursor Automations\",\"link\":\"/guides/convert-automation\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"}]},{\"text\":\"Extensions\",\"collapsed\":false,\"items\":[{\"text\":\"Overview\",\"link\":\"/reference/extensions\"},{\"text\":\"Cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"Jev\",\"link\":\"/guides/jev\"}]},{\"text\":\"Guides\",\"collapsed\":false,\"items\":[{\"text\":\"MCP\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Hooks\",\"link\":\"/guides/hooks\"},{\"text\":\"Peer agents\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"},{\"text\":\"Build with a coding agent\",\"link\":\"/building-with-agents\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Templates\",\"collapsed\":false,\"items\":[{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Thermo review\",\"link\":\"/templates/thermo-review\"},{\"text\":\"Thermo quality review\",\"link\":\"/templates/thermo-quality-review\"},{\"text\":\"Agentic Approver\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Evals\",\"link\":\"/reference/evals\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    
+  </body>
+</html>

package/dist/docs/reference/artifacts.md

@@ -0,0 +1,116 @@
+# Artifacts
+
+Artifacts are durable outputs such as reviewed pull requests, reports,
+or decision records. An artifact kind defines the data it accepts, and
+the artifacts API tags or updates records by key. Records persist across
+sessions and can be listed, streamed, or downloaded.
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/docs/index.md#bdk-package-availability).
+
+## Artifact kinds
+
+Author `bot/artifacts.ts` with `defineArtifacts` from
+`@cursor/bdk/artifacts`:
+
+```ts
+import { z } from "zod";
+import { defineArtifacts } from "@cursor/bdk/artifacts";
+
+export default defineArtifacts({
+  kinds: {
+    "reviewed-pr": {
+      description: "A pull request this agent reviewed.",
+      schema: z.object({ url: z.string(), verdict: z.string() }),
+    },
+    report: { description: "A generated report." },
+  },
+  agentTool: true,
+});
+```
+
+| Option | Contract |
+| --- | --- |
+| `kinds` | Map of accepted kind names to a non-empty `description` and optional Zod `schema` |
+| `agentTool` | Expose `tag_artifact` to the model; requires at least one declared kind |
+| `max` | Positive retention cap; defaults to `1000` and evicts the oldest-updated record |
+
+With declared kinds, `tag` rejects any other kind. With no registry, it
+accepts free-form kind names and defaults an omitted kind to
+`"artifact"`. A kind's schema validates `data`, and the parsed value is
+stored, including schema defaults and coercions.
+
+## Tag artifacts from host code
+
+Tools, hooks, channel handlers, channel `onStart`, schedules, and
+reminders receive 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 field | Contract |
+| --- | --- |
+| `data` | Required JSON data, validated when the kind has a schema |
+| `kind` | Declared or free-form kind |
+| `key` | Agent-wide upsert key; the same key updates one record across kinds |
+| `title` | Optional display title |
+| `contents` | String or bytes served by the content route |
+| `contentType` | MIME type for `contents` |
+| `sessionId`, `turnId` | Attribute the artifact to a session or turn |
+| `source` | `"host"` or `"model"`; defaults to `"host"` |
+
+Tool, hook, result, and channel-event contexts are session-bound, so
+they fill `sessionId` and the current `turnId`. Channel routes,
+`onStart`, schedules, and reminders receive an unbound facade; pass
+`sessionId` to attribute an artifact.
+
+Re-tagging a key without `contents` keeps its file or blob when the
+`sessionId` stays the same. Rebinding the key to another session without
+new contents removes the previous payload. `tag` returns the stored
+`ArtifactRecord`.
+
+| Record field | Contract |
+| --- | --- |
+| `id` | Stable ID derived from `key`, or a generated ID when no key is set |
+| `kind`, `data` | Validated kind and JSON payload |
+| `key`, `title` | Optional upsert key and display title |
+| `content` | Optional `{ size, contentType? }` metadata |
+| `sessionId`, `turnId` | Optional session attribution |
+| `source` | `"host"` or `"model"` |
+| `createdAt`, `updatedAt` | ISO-8601 timestamps |
+
+## Expose `tag_artifact` to the model
+
+With `agentTool: true`, the `tag_artifact` server tool materializes from
+the kinds registry. Its input accepts the declared kinds and validates
+their data with the same schemas as host-side tagging. The kind
+descriptions tell the model which output each one represents.
+
+An authored tool named `tag_artifact` takes precedence over the generated
+tool.
+
+## List artifacts
+
+`list({ kind?, sessionId? })` returns matching records newest-updated
+first. HTTP callers can list records and download content through the
+[artifact routes](/docs/reference/http-api.md#list-and-download-artifacts).
+
+## Stream artifact tags
+
+Tagging an artifact with a `sessionId` emits `artifact.tagged` on that
+session. Its event data contains `id`, `kind`, `key`, `title`, `data`,
+and `source`. See [Stream events](/docs/reference/sessions.md#stream-events) for the
+event envelope.
+
+## Related
+
+- [Sessions](/docs/reference/sessions.md)
+- [Tools](/docs/reference/tools.md)
+- [Evals](/docs/reference/evals.md)
+- [HTTP API](/docs/reference/http-api.md)