# Blueprint Dsl

# Agent Blueprint DSL — v1.0.0 reference

A blueprint is a declarative recipe for an agent workflow. The DSL is platform-defined; tenants author blueprints by writing valid `content_json` for the `agent_blueprint` artifact type. This page documents every field of the v1.0.0 schema, generated directly from the canonical Zod schema, which is the source of truth.

A blueprint is a recipe an LLM reads and walks itself. Two execution paths coexist. On the MCP tool surface there is no one-shot run-blueprint tool: an agent (Claude on the other side of MCP, or an Anthropic-side profile like the copilot) reads the recipe via `agent_blueprint://<id>` (or the `blueprints` coarse tool `get` action), then performs each step with its own primitive tools (`artifacts.*`, `data.*`, `knowledge_base.*`, `external_search.*`, `context.*`) — that agent IS the runner. Separately, a headless server-side SDK runner can drive a saved blueprint to completion for unattended runs (manual "Run now" via REST, schedule / event / webhook triggers, replay, backtest sweeps); a one-shot `run_blueprint` op exists on REST and the Anthropic tool surface (intentionally off MCP), and schedule CRUD (`create_schedule` / `update_schedule` / `delete_schedule`) IS on MCP. See `docs/blueprint-runner-sdk.md`. Everything declared below is AUTHORING METADATA and GUIDANCE the reading agent should respect; the API key scope grammar is the real safety boundary.

## Top-level shape

A blueprint's `content_json` is a strict object with the following fields. Strict means tenants cannot smuggle extra top-level keys; forward-compat happens via `schema_version` bumps.

| Field | Required | Notes |
|---|---|---|
| `schema_version` | yes | Pinned to `1.0.0` for v1. |
| `identity` | yes | See §Identity below. |
| `inputs` | yes (may be empty) | Array of input declarations. May be empty. See §Inputs. |
| `outputs` | yes (may be empty) | Array of output declarations. Empty = pure side-effect blueprint. See §Outputs. |
| `policy` | yes | See §Policy. |
| `trigger` | yes | See §Triggers. |
| `steps` | yes | Array of step declarations; must be non-empty. See §Steps. |
| `outputs_mapping` | yes (may be empty) | Required iff `outputs` is non-empty. See §Outputs mapping. |
| `metadata` | optional | — |

## Identity

The blueprint's metadata block. Required at write time; surfaced in marketplace UIs + tool catalogs.

Fields: `slug`, `name`, `description`, `version`, `category`, `tags`, `icon`, `estimated_runtime_seconds`, `estimated_cost_cents`, `authored_by`

- `slug` — tenant-scoped friendly handle (`/^[a-z0-9-]{3,60}$/`). Pair with `business_id` is unique.
- `name` (≤80 chars) + `description` (30-500 chars) — displayed in marketplace + Library UI.
- `version` — semver-shaped. Independent of `schema_version`. Bumps when blueprint logic changes; `schema_version` bumps when the DSL itself changes.
- `category` / `tags` / `icon` — UI hints for marketplace filtering + presentation.
- `estimated_runtime_seconds` / `estimated_cost_cents` — advisory authoring hints shown in marketplace + Library UI to set expectations before an agent walks the recipe. Never enforced anywhere, on either the interactive MCP path or the headless SDK runner.
- `authored_by` — origin marker (`platform` | `tenant` | `agent`). Set automatically by `artifactService.createArtifact` based on the caller; tenants do not author this directly.

## Inputs

Each input declaration is a strict object with a `type` discriminator. The declared type + any `validate.*` constraints describe what a valid supplied value looks like; the reading agent gathers the inputs and substitutes them as it walks the steps.

Supported types (10): `artifact_ref`, `artifact_ref_list`, `boolean`, `date`, `datetime`, `enum`, `integer`, `json`, `number`, `string`.

Common fields on every input declaration: `name` (`/^[a-z][a-z0-9_]{0,30}$/`), `required` (boolean, optional), `description` (free-text), `ui` (component hints — `label`, `component`, `placeholder`, `helper`).

Per-type validate blocks:

- `string` — `regex`, `min_length`, `max_length`
- `integer` / `number` — `min`, `max`
- `enum` — `values` (required, ≥1)
- `artifact_ref` — `artifact_type` (required)
- `artifact_ref_list` — `artifact_type` (required), `min`, `max`
- `boolean` / `date` / `datetime` / `json` — no validate fields beyond the common set.

## Outputs

Output declarations describe what the blueprint produces when complete. Three kinds of output coexist; a blueprint can mix them freely.

Supported kinds: `artifact`, `data`, `side_effect`.

- `artifact` — produces an artifact of `artifact_type` with `cardinality: 'one' | 'many'`. Optional `preferred_renderer` for UI.
- `data` — returns structured JSON matching a JSON-Schema-subset `schema`.
- `side_effect` — performs a side effect. Categories (6): `audit_log_entry`, `email_sent`, `external_api_call`, `notification`, `slack_message`, `webhook_call`.

A blueprint with `outputs: []` is a pure-side-effect (or pure-write) blueprint and skips the `outputs_mapping` block.

## Steps

Steps are the recipe's body. The `steps` array MUST be non-empty. Step kinds form a discriminated union; loop / branch / parallel / blueprint kinds nest inner steps recursively.

The 8 step kinds (8): `assert`, `blueprint`, `branch`, `llm`, `loop`, `parallel`, `tool`, `transform`.

Common fields on every step: `id` (`/^[a-z][a-z0-9_]{0,40}$/`), `output_alias` (optional `$name` to bind the step's result), `description`, `retry` (per-step retry override), `timeout_seconds`.

| Kind | What it does | Key fields |
|---|---|---|
| `tool` | Invoke a registered platform Operation by id. The most common kind. | `tool` (op id), `args` (record of references / literals) |
| `llm` | Run a structured prompt with optional input data + output schema. | `effort` (`fast` / `medium` / `deep` / `research` capability tier — the reading agent picks a model that matches the tier), `temperature`, `prompt`, `prompt_resources` (URIs / refs), `input_data` (refs), `output_schema` (JSON Schema subset) |
| `loop` | Iterate over a referenced collection, run a nested step per item. | `over` (ref), `as` (loop var name), `parallel` (boolean), `step` |
| `branch` | Conditional dispatch. | `condition`, `if_true` (step), `if_false` (optional step) |
| `parallel` | Fan out N child steps concurrently. | `steps` (array, ≥1), `merge` (`object` \| `array`) |
| `blueprint` | Compose another blueprint as a sub-step. | `blueprint` (ref/literal), `args`, `inherit_cost` (authoring hint) |
| `transform` | Pure data transform via JSONata. | `input` (ref), `expression` |
| `assert` | Halt the run if a condition is false. | `condition`, `halt_message` |

## References

Anywhere the schema accepts a `Reference`, write a `$`-prefixed expression. References are literal strings in the recipe; the reading agent substitutes the resolved value (a supplied input, a prior step output, etc.) as it walks the steps.

| Reference | Resolves to |
|---|---|
| `$inputs.NAME` | The supplied value of the declared input `NAME`. |
| `$STEP_ID` | The output of the prior step with id `STEP_ID`. |
| `$STEP_ID.path.to.field` | A nested field on the step's output. |
| `$now` | An ISO-8601 timestamp at the moment the agent resolves it. |
| `$today` | A YYYY-MM-DD date in the agent's timezone. |
| `$random_uuid` | A freshly generated UUIDv4. |
| `$secret.NAME` | The encrypted secret store entry for `NAME`. NEVER inlined into the recipe text; resolved only at the tool that needs it. |
| `$builtin.X` | A platform-managed reference (e.g. `$builtin.draft_piece` for a sub-blueprint id). |

Reference grammar regex: `/^\$[A-Za-z_][\w.[\]@?='"*\-+ /]*$/`. The schema validates the shape only; the resolver registry documents what each prefix means so the reading agent knows how to substitute it.

## Conditions

The condition grammar (used by `branch.condition` and `assert.condition`):

| Op | Form | Notes |
|---|---|---|
| `eq` / `neq` | `{op, left, right}` | Comparators on values or references. |
| `gt` / `gte` / `lt` / `lte` | `{op, left, right}` | Numeric comparators. |
| `is_null` / `is_not_null` | `{op, value}` | Null check on a value or reference. |
| `in` | `{op, value, list}` | Membership in a literal list or referenced array. |
| `and` / `or` | `{op, conditions: [...]}` | At least one nested condition required. |
| `not` | `{op, condition}` | Negation of a single condition. |

Conditions can nest freely via `and` / `or` / `not`.

## Policy

The blueprint's authoring policy. It is GUIDANCE the reading agent should respect, never server-enforced: `policy.tool_allowlist` tells the agent which operations this recipe expects its `tool` steps to call, but the API key's scope grammar is the real safety boundary. Even the headless SDK runner does not enforce these fields; it runs against the same scope-gated MCP surface.

Fields: `tool_allowlist`, `artifact_write_allowlist`, `timeout_seconds`, `parallelism_max`, `retry_policy`, `cost_cap_usd`.

- `tool_allowlist` (required, ≥1) — operation ids the blueprint's `tool` steps SHOULD call. Guidance the reading agent should respect; never server-enforced.
- `artifact_write_allowlist` (optional) — artifact types tool steps that create artifacts SHOULD restrict to. Same guidance status as the tool allowlist.
- `timeout_seconds` (optional) — advisory soft budget for how long walking the recipe should take. Advisory only; neither the interactive MCP path nor the headless SDK runner hard-enforces it.
- `parallelism_max` (optional, default 5) — concurrency cap on `loop` / `parallel` step kinds.
- `retry_policy` (optional) — advisory default retry guidance for every step (per-step retry overrides this) that the reading agent may follow when a step errors. Fields: `max_attempts`, `backoff` (`none` | `linear` | `exponential`), `initial_ms`, `retryable_errors`.

## Triggers

The trigger config declares HOW the blueprint is meant to be picked up. Fields: `manual`, `schedule`, `event`, `webhook`. On the interactive MCP surface a human or agent picks up `manual` recipes and walks them. The headless SDK runner backs `schedule` / `event` / `webhook` triggers for unattended runs (schedule CRUD is itself exposed on MCP via `create_schedule` / `update_schedule` / `delete_schedule`); see `docs/blueprint-runner-sdk.md`.

- `manual` — `{ enabled: boolean }`. A human or agent picks the recipe and walks it; on the MCP surface there is no one-shot run-blueprint tool to invoke, so reach the recipe via `agent_blueprint://<id>` (or the `blueprints` coarse tool `get`) and perform the steps yourself. (Platform "Run now" hands the same blueprint to the headless SDK runner via the REST `run_blueprint` op.)
- `schedule` — `{ cron, enabled }`. Standard 5-field cron. Fired by the headless SDK runner on the declared cadence; not walked on the interactive MCP surface, though schedule CRUD is exposed there via `create_schedule` / `update_schedule` / `delete_schedule`.
- `event` — `{ artifact_type, event_kind, filter, max_runs_per_event, enabled }`. Describes an artifact-lifecycle subscription. Fired by the headless SDK runner when a matching event occurs; not fired on the interactive MCP surface.
- `webhook` — `{ hmac_secret_id, rate_limit_per_minute, enabled }`. Describes an HMAC-signed inbound POST endpoint. Fired by the headless SDK runner on a verified inbound POST; not fired on the interactive MCP surface.

## Outputs mapping

When `outputs` is non-empty, `outputs_mapping` declares which step output corresponds to which declared output by name. Each entry is either a `$`-prefixed reference (string) OR a richer object whose fields are themselves references / literals (used by `side_effect` outputs to bundle category + receipt).

```jsonc
"outputs_mapping": {
  "calendar": "$create_calendar",       // single reference
  "audit_log_entry": {
    "category": "audit_log_entry",
    "receipt": "$emit_audit"
  }
}
```

## See also

- 8 Amdahl-shipped starter blueprints: `bootstrap-workspace`, `draft-piece`, `plan-and-draft-window`, `multi-persona-social-launch`, `research-report`, `gtm-diagnostic`, `substack-thought-leader-newsletter`, `viz-page-from-query` — each documented under `docs/consumer/blueprints/`.
- Tutorial: `docs/consumer/blueprints/tutorial.md` — build your first blueprint by forking a starter.
- Tool catalog: `docs/consumer/api-reference/tool-catalog.md` — every operation a blueprint's `tool` step can name.