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"
  }
}