Workflow nodes
This page is for developers who write :::workflow blocks or build a host that runs them. It lists all 74 node kinds of the instruction/workflow dialect (revision 1), grouped by what they do, with each kind's required and optional fields. It also covers the fields every step shares, the registry's limits, what the check refuses, and which hosts run the nodes.
Find a node by category
Triggers (11) · Flow control (15) · Data (11) · Model steps (7) · Agents and child workflows (6) · Tools, MCP and HTTP (4) · Search and knowledge (4) · Memory (7) · Artifacts (3) · People and messages (3) · Agent to agent (A2A) (3)Each kind's row has its own anchor, #kind- and the kind with dots as dashes: #kind-mcp-tool is mcp.tool.
Where a workflow goes
A workflow is the structured body of a :::workflow block whose dialect is instruction/workflow. The body is YAML or JSON with a name and a steps mapping. Each step names its kind, one of the kinds on this page:
:::workflow{id=approval dialect="instruction/workflow"}
name: refund-approval
steps:
start:
kind: manual
ask:
kind: human
depends_on: [start]
question: "Approve a refund of {{ inputs.amount }} for order {{ inputs.order }}?"
schema: { type: string, enum: [approve, decline] }
timeout: 24h
route:
kind: switch
depends_on: [ask]
on: "{{ steps.ask.output }}"
cases: { approve: tell, decline: declined }
tell:
kind: message
depends_on: [route]
to: support
text: "Refund approved for order {{ inputs.order }}."
approved:
kind: finish
depends_on: [tell]
declined:
kind: finish
depends_on: [route]
status: cancelled
reason: The approver declined.
::: The body is literal. Markdown directives and ${parameter} substitutions don't apply inside it; the workflow's own {{ … }} templates do, when a host runs it. Opening, checking, delivering or drawing an instruction never arms a trigger or starts a run. A host activates a workflow on purpose, after it validates it.
instruction.md checks a workflow and draws it in the editor and on the instruction's page. It doesn't run workflows. A host that runs them, such as agentd, receives the block with the instruction. See Host support.
The language itself (definition fields, templates, branching, run and step states, durability) is explained in Workflows, explained and specified in the first edition.
Fields every step shares
Every step may set these besides its kind's own fields. A field that is neither a common field nor one of its kind's is an error, except x-* fields, which carry extension data.
| Field | What it does |
|---|---|
budget | What the step may spend, within the run's limits. |
cache | Response caching. Not with detach; a cached call never skips a required approval or credential decision. |
depends_on | The sibling steps this one waits for, by name. Only a done or skipped step satisfies a dependency. |
description | What the step is for, for people reading the workflow. |
idempotent | Whether running the step again has no further effect, so a host may replay it. |
kind | The node kind: one of the kinds below, or a declared extension's alias:node. Required on every step. |
on_error | fail (the default), continue, or goto:<step>, a sibling step to route to. |
on_replay | After a crash, what to do with work that may have run: retry (the default), skip or fail. |
otel | Tracing attributes for the step's span. |
output_schema | A JSON Schema the step's output must satisfy. |
retry | retry.max retries after the first attempt (0 to the limit below); retry.backoff is the first exponential delay. |
skills | Skills the step may use. |
timeout | Bounds one attempt, or the node's own wait. |
when | A guard: a template, a CEL: … expression, or {noul: …} for a model-backed decision. False prunes the step at the top level and skips it inside a body. |
Three more controls are fields of some network kinds, not common fields: http, mcp.tool, a2a.send and a2a.delegate take breaker: {failures, cooldown}, rate and idempotency; webhook takes rate and idempotency; batch and stream take rate. A retry handles one failed attempt; a breaker shares outage state across runs; a rate postpones work without spending an attempt; an idempotency key makes a repeated delivery recognizable. They are separate controls.
Limits
| Limit | Value | What it bounds | Diagnostic |
|---|---|---|---|
steps | 512 | Steps in one scope | limit-exceeded |
body_depth | 4 | Levels of nested bodies and branches | limit-exceeded |
retry_max | 20 | The largest retry.max | limit-exceeded |
A host can set lower limits of its own, and records them in the run's execution profile.
What the check refuses
The check runs on every :::workflow block with dialect="instruction/workflow", wherever an instruction is checked: the editor, instruction validate, spec_validate, instructions_validate and every release. Each finding is an error, so a release refuses a workflow that has one. The codes are invalid-workflow, limit-exceeded and, for a custom node whose alias isn't declared, extension-unavailable.
- The definition. It has a
nameof 1 to 64 letters, digits,_and-, starting with a letter or_. It has a nonemptystepsmapping and no unknown field (x-*is allowed). It has akeywhen itsconcurrency.scopeiskey. - Each step. It has a valid name and a
kindthis registry has, or a declaredalias:node. It has its kind's required fields and no field that is neither its kind's nor a common one. Itsdepends_onis a list of distinct sibling names. Itsretry.maxis a whole number from 0 to 20. Itson_errorisfail,continueorgoto:<step>. - Scoping steps.
foreach,batch,iterateandsubgraphhave abodythat is{steps: …}.parallelandracehavebranches, a mapping of names to{steps: …}. - Special kinds. A
schedulesets exactly one ofcron,everyandat. Acorrelatehas awindow. Aswitchcase names one step, as a string. - Each scope. It has at most 512 steps and nests no deeper than 4 levels. Its dependencies have no cycle. Its routes (switch cases and
default,goto:,on_timeout) name a sibling that isn't a trigger. Triggers andfinishappear only at the top level, and a trigger depends on nothing. - The top level. A step that depends on nothing starts the run, so it must be a trigger. There is at least one trigger and one
finish. Every step is reached from a trigger.
What a host decides is not checked: which events it emits, its node providers, expressions, credentials and a remote tool's arguments. A host validates those again before it activates the workflow. The codes and their quick fixes are on Diagnostics and fixes.
Triggers
A trigger starts a run. Its payload becomes its step's output. Only top-level steps can be triggers, and a trigger depends on nothing. A run fires exactly one trigger, and its sibling triggers become skipped, which satisfies a dependency. schedule's cron is five fields in UTC.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
a2a | Accept an authenticated command with declared roles and an input contract. | — | command, roles, inputs, schema, into |
correlate | Join related stream events in a bounded time window; expose missing members in partial results. | stream, on | by, window, on_incomplete, filter, max_pending, inputs |
event | Fire on an allowed host event, with a payload filter. | on | filter, inputs |
loop | Re-enter after a prior run, with pacing, backoff and termination bounds. | — | interval, delay, until, max_iterations, backoff, inputs |
manual | Admit a run only after an explicit operator or authorized caller request. | — | inputs |
once | Fire when the activated definition is armed; an ensure policy avoids a duplicate live run. | — | policy, inputs |
schedule | Fire from one UTC cron, interval or absolute-time declaration. | — | cron, every, at, inputs |
signal | Fire on an edge-triggered named signal; no implicit retained backlog. | name | filter, inputs |
stream | Consume persisted events with subject selection, durable offsets, batching and rate controls. | stream | subject, filter, from, rate, batch, inputs |
subscribe | Read an MCP resource after notifications, with filtering, debounce and bounded sampling. | server, uri | debounce_ms, filter, window, inputs |
webhook | Accept a bound, authenticated HTTP event with filtering, admission and response policy. | path | methods, auth, parallelism, on_overflow, rate, idempotency, respond, filter, inputs, signal, into |
:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
by_hand:
kind: manual
weekdays:
kind: schedule
cron: "0 7 * * 1-5"
brief:
kind: summarize
depends_on: [by_hand, weekdays]
input: "{{ inputs.notes }}"
length: short
done:
kind: finish
depends_on: [brief]
output: "{{ steps.brief.output }}"
::: Flow control
Route, branch, repeat, wait and end. foreach, batch, iterate and subgraph hold a body: {steps: …}; parallel and race hold named branches, each with its own steps. Inside a body, dependencies name siblings, and the body's result is its last steps' outputs. A false when at the top level prunes a step, and inside a body it skips it.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
assert | Fail unless its expression holds, recording the assertion message. | condition | message |
batch | Run a scoped body per group, with grouping, size, parallelism and collection policy. | over, body | by, size, parallel, rate, collect, on_error |
checkpoint | Request an explicit durable checkpoint in the execution record. | — | name |
fail | End the run as a failure with an optional code and message. | — | message, code |
finish | End the run with a declared terminal status, output and reason. | — | status, output, reason |
foreach | Run a scoped body per item under explicit batching and parallelism bounds. | over, body | batch, collect, on_error, as |
iterate | Repeat a scoped body while/until a condition, bounded by a maximum iteration count. | body | while, until, max_iterations, collect |
join | Await child/subagent handles, with a deadline and minimum/partial-result policy. | handles | timeout, min, partials |
noop | Complete without an effect; useful as a join or routing point. | — | — |
parallel | Run named scoped branches concurrently and combine their terminal results. | branches | on_error, min_success |
race | Run named branches and accept the first qualifying result; cancel the losers. | branches | timeout |
sleep | Suspend on a durable timer for the declared duration. | duration | — |
subgraph | Evaluate an inline scoped dependency graph and return its sink outputs. | body | — |
switch | Select one string-valued routing target; prune the unchosen routes. | on, cases | default, on_no_match |
wait | Suspend on a declared resource, event, task, run, signal or other supported wait condition. | on | server, uri, condition, signal, run, subagent, conversation, from, webhook, stream, subject, subscribe, match, task, timeout, on_timeout |
:::workflow{id=triage dialect="instruction/workflow"}
name: triage-tickets
steps:
start:
kind: manual
each:
kind: foreach
depends_on: [start]
over: "{{ inputs.tickets }}"
body:
steps:
label:
kind: classify
input: "{{ item.text }}"
classes: [bug, billing, question]
some:
kind: assert
depends_on: [each]
condition: "CEL: size(steps.each.output) > 0"
message: No ticket was labelled.
done:
kind: finish
depends_on: [some]
output: "{{ steps.each.output }}"
::: Data
Shape values without a model or a network call. map, filter and reduce take an expression (expr) evaluated per item.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
assign | Write a rendered value into a run variable using its reducer and schema. | value | writes, mode |
chunk | Split a value into bounded pieces with optional overlap. | value, size | by, overlap |
dedupe | Remove duplicate collection members while retaining the first matching member. | over | by |
filter | Keep array members whose expression evaluates to true. | over, expr | as |
map | Apply an expression to each item and return the resulting array. | over, expr | as |
parse | Parse text using a declared data format. | text | format |
reduce | Fold an array from an initial accumulator with a declared expression. | over, expr | initial, as, acc |
sort | Order an array by a selected value/path and direction. | over | by, order |
template | Render text or a typed value from the current run context. | — | text, value |
transform | The assign operation, named for data transformation. | value | writes, mode |
validate | Return a value only if it conforms to the supplied schema. | value, schema | — |
:::workflow{id=orders dialect="instruction/workflow"}
name: open-orders
steps:
start:
kind: manual
open:
kind: filter
depends_on: [start]
over: "{{ inputs.orders }}"
expr: "CEL: item.status == 'open'"
newest:
kind: sort
depends_on: [open]
over: "{{ steps.open.output }}"
by: created_at
order: desc
total:
kind: reduce
depends_on: [open]
over: "{{ steps.open.output }}"
initial: 0
expr: "CEL: acc + item.amount"
done:
kind: finish
depends_on: [newest, total]
output:
orders: "{{ steps.newest.output }}"
total: "{{ steps.total.output }}"
::: Model steps
Each is one model request with no tools, under a declared contract. model, prompt and skills choose what is asked and how. classify, judge, route and decide take a confidence threshold and an on_unsure policy.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
classify | Choose among declared classes, preserving confidence and uncertainty policy. | input, classes | prompt, skills, model, confidence, on_unsure |
decide | Answer declared decision questions about a state with confidence controls. | state, questions | model, confidence, on_unsure |
extract | Extract structured content that must satisfy an output schema. | input, output_schema | prompt, skills, model |
judge | Evaluate input against a rubric and optional discrete levels. | input, rubric | levels, prompt, skills, model, confidence, on_unsure |
route | Use a model to choose among declared routes, with uncertainty handling. | input, choices | prompt, skills, model, confidence, on_unsure |
summarize | Produce a model summary using declared length, context and model settings. | input | length, prompt, skills, model |
think | Make a tool-free model request for structured reasoning/output under a declared contract. | prompt | output_schema, reads, check, retries, skills, system, model, effort |
:::workflow{id=refunds dialect="instruction/workflow"}
name: refund-intake
steps:
start:
kind: manual
topic:
kind: classify
depends_on: [start]
input: "{{ inputs.message }}"
classes: [refund, complaint, other]
facts:
kind: extract
depends_on: [start]
input: "{{ inputs.message }}"
output_schema:
type: object
properties:
order_id: { type: string }
amount: { type: number }
required: [order_id]
done:
kind: finish
depends_on: [topic, facts]
output:
topic: "{{ steps.topic.output }}"
facts: "{{ steps.facts.output }}"
::: think.check and think.retries come from the imported catalog and carry no checking or retry of their own. Use output_schema, a validate step and the common retry instead.
Agents and child workflows
Hand bounded work to a tool-using agent, a child agent or another workflow. A child never gets more authority than its caller. workflow runs a child sync, async (it returns a handle) or detached; join and workflow.wait wait for handles; cascade decides whether cancelling the caller cancels the child.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
agent | Run a bounded tool-using model turn with explicitly narrowed capabilities. | instruction | output_contract, output_schema, tools, servers, limits, context, skills, system, model, effort |
subagent | Delegate bounded work to a child agent with explicit tools, context and budgets. | — | instruction, template, params, mode, tools, servers, limits, priority, context, output_contract, output_schema, skills, durable |
workflow | Invoke a named child workflow synchronously, asynchronously or detached, with explicit cancellation propagation. | name | inputs, mode, start, version, cascade |
workflow.cancel | Request cancellation of an authorized target run. | run | reason |
workflow.signal | Signal an existing waiter or an explicitly selected run. | name | payload, run |
workflow.wait | Await a child or referenced run with an optional deadline. | run | timeout |
:::workflow{id=report dialect="instruction/workflow"}
name: weekly-incidents
steps:
start:
kind: manual
research:
kind: subagent
depends_on: [start]
instruction: Collect this week's closed incidents and their causes.
tools: [incidents_search]
limits: { steps: 20 }
publish:
kind: workflow
depends_on: [research]
name: publish-report
mode: sync
inputs: { body: "{{ steps.research.output }}" }
done:
kind: finish
depends_on: [publish]
::: Tools, MCP and HTTP
Call a granted tool, an MCP server or an HTTP endpoint. tool calls a tool by its name in the host's registry; mcp.tool names the server and the tool.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
http | Make an authorized HTTP request with response, credential, retry and idempotency policy. | url | method, headers, query, body, json, timeout, expect, allow_private, sign, idempotency, breaker, rate, auth, payment |
mcp.resource | Read/list resources, use a prompt, or request completion through a declared MCP server. | server, op | uri, name, arguments, reference, argument |
mcp.tool | Call a named tool on a declared MCP server, with task, elicitation and resilience options. | server, tool | args, idempotency, breaker, rate, detach, input, payment |
tool | Call an explicitly granted tool by its host registry name. | name | args, detach, input |
:::workflow{id=sync dialect="instruction/workflow"}
name: ticket-to-issue
steps:
start:
kind: manual
issue:
kind: mcp.tool
depends_on: [start]
server: github
tool: create_issue
args:
title: "{{ inputs.title }}"
body: "{{ inputs.body }}"
retry: { max: 3, backoff: 2s }
notify:
kind: http
depends_on: [issue]
url: https://hooks.example.com/tickets
method: POST
json: { issue: "{{ steps.issue.output }}" }
timeout: 10s
done:
kind: finish
depends_on: [notify]
::: mcp.resource'sopchooses a resource read or list, a prompt, or a completion.mcp.toolcan receive an MCP task. A plain call follows the task to its end;detachreturns a handle a laterwaituses;inputdescribes the human input the task may ask for. A detached call can't be cached.payment,auth,auth_toandsignare proposals the host's operator policy constrains. The document's text alone never authorizes a payment, a credential or a delegated identity.
Search and knowledge
Query a configured search or knowledge provider, and fetch what it found. search.fetch reads at most max_bytes.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
knowledge.get | Retrieve a selected knowledge item and its content metadata. | — | id, uri |
knowledge.search | Search a configured knowledge provider and return ranked hits. | query | top_k, filters |
search.fetch | Retrieve a selected page/resource within a byte bound. | url | max_bytes |
search.query | Query a configured search provider with explicit result and freshness bounds. | query | limit, freshness |
:::workflow{id=answer dialect="instruction/workflow"}
name: answer-with-sources
steps:
start:
kind: manual
docs:
kind: knowledge.search
depends_on: [start]
query: "{{ inputs.question }}"
top_k: 5
web:
kind: search.query
depends_on: [start]
query: "{{ inputs.question }}"
limit: 5
freshness: 7d
answer:
kind: think
depends_on: [docs, web]
prompt: "Answer {{ inputs.question }} from these sources only: {{ steps.docs.output }} {{ steps.web.output }}"
done:
kind: finish
depends_on: [answer]
output: "{{ steps.answer.output }}"
::: The registry lists kind among search.query's fields, as the imported agentd catalog does for the provider's own search kind. A step's kind always names its node, so that option can't be set on the step; a provider that needs it takes it through its adapter.
Memory
Durable keys a workflow is explicitly bound to, kept between runs. memory.list takes a prefix and a limit; memory.set takes an optional ttl.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
memory.delete | Delete an accessible durable memory key. | key | — |
memory.get | Read an explicitly bound durable memory key. | key | — |
memory.list | List accessible memory keys with prefix and result bounds. | — | prefix, limit |
memory.pop | Remove and return the final member of a durable memory collection. | key | — |
memory.push | Append a value to a durable memory collection. | key, value | — |
memory.set | Write a durable memory key, optionally with a time-to-live. | key, value | ttl |
memory.shift | Remove and return the first member of a durable memory collection. | key | — |
:::workflow{id=watch dialect="instruction/workflow"}
name: hourly-check
steps:
start:
kind: schedule
every: 1h
last:
kind: memory.get
depends_on: [start]
key: last_seen
save:
kind: memory.set
depends_on: [last]
key: last_seen
value: "{{ steps.start.output }}"
ttl: 30d
done:
kind: finish
depends_on: [save]
output: "{{ steps.last.output }}"
::: Artifacts
Stored outputs with a media type and a sensitive flag, read and deleted under the host's access policy. A sensitive artifact is never copied into an instruction bundle.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
artifact.create | Store content as an artifact with media type and sensitivity metadata. | name | mime, content, from_step, sensitive |
artifact.delete | Delete an artifact the active principal may manage. | id | — |
artifact.get | Read an artifact under the host access policy. | id | — |
:::workflow{id=draft dialect="instruction/workflow"}
name: store-draft
steps:
start:
kind: manual
draft:
kind: think
depends_on: [start]
prompt: "Draft release notes from {{ inputs.changes }}."
file:
kind: artifact.create
depends_on: [draft]
name: release-notes.md
mime: text/markdown
from_step: draft
sensitive: false
done:
kind: finish
depends_on: [file]
output: "{{ steps.file.output }}"
::: People and messages
Ask a person, send a message, or record an event. A human step suspends the run until an authorized person answers. Its answer is checked against schema, and a switch can route on it. human.reply_uri is kept from the imported catalog, but the first compatibility host doesn't support it for activation, and an adapter must refuse a workflow that sets it. The check accepts it.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
emit | Record a value/audit note or append an event to a declared stream. | — | note, audit, value, stream, subject, data, correlation, forward |
human | Suspend for an authorized person to answer a question under an optional schema. | question | schema, to, timeout, reply_uri |
message | Deliver a message through an authorized channel, optionally awaiting a reply. | to | text, parts, wait, timeout, on_timeout |
:::workflow{id=approval dialect="instruction/workflow"}
name: refund-approval
steps:
start:
kind: manual
ask:
kind: human
depends_on: [start]
question: "Approve a refund of {{ inputs.amount }} for order {{ inputs.order }}?"
schema: { type: string, enum: [approve, decline] }
timeout: 24h
route:
kind: switch
depends_on: [ask]
on: "{{ steps.ask.output }}"
cases: { approve: tell, decline: declined }
tell:
kind: message
depends_on: [route]
to: support
text: "Refund approved for order {{ inputs.order }}."
approved:
kind: finish
depends_on: [tell]
declined:
kind: finish
depends_on: [route]
status: cancelled
reason: The approver declined.
::: Agent to agent (A2A)
Send to, delegate to and wait for an authorized peer agent. The a2a trigger, which accepts a peer's command, is under Triggers.
| Kind | What it does | Required | Other fields |
|---|---|---|---|
a2a.delegate | Delegate an objective and output contract to an authorized peer. | peer | objective, command, args, output_contract, timeout, idempotency, breaker, rate, auth_to, auth_timeout, payment |
a2a.send | Send an authenticated message or command to a named destination. | to | parts, command, args, context, timeout, idempotency, breaker, rate, payment |
a2a.wait | Wait for a matching conversation response from an expected peer. | from | conversation, timeout |
:::workflow{id=billing dialect="instruction/workflow"}
name: ask-billing
steps:
start:
kind: manual
delegate:
kind: a2a.delegate
depends_on: [start]
peer: billing
objective: "Find why invoice {{ inputs.invoice }} was charged twice."
timeout: 10m
done:
kind: finish
depends_on: [delegate]
output: "{{ steps.delegate.output }}"
::: Custom nodes
A node of your own is kind: alias:node. The alias is declared in the front matter's extensions, and the extension's manifest lists the node under provides.workflow_nodes with its role (trigger or step), its schema, its semantics and the capabilities it requires. The check accepts the step when its alias is declared, and doesn't check its fields. A host activates it only with that exact manifest version and an installed provider; the document never installs code.
---
spec: "1"
extensions:
acme: { id: com.example/ops, version: "1.0.0" }
---
:::workflow{id=ops dialect="instruction/workflow"}
name: page-on-call
steps:
start:
kind: manual
page:
kind: acme:page
depends_on: [start]
x-acme-severity: high
done:
kind: finish
depends_on: [page]
::: Host support
A host publishes which node kinds, expression features, limits, credentials and durability it supports. A kind in this registry is part of the language, not a promise that every host implements it. A host refuses a workflow that needs a kind it doesn't run; it never runs an approximation.
- instruction.md checks workflows and draws them. It runs none.
- agentd runs workflows. The registry was imported from agentd's workflow schema snapshot (SHA-256
40f1d4a06967af70705d1b6aa508ebcc7defc7693ad3e8d8570eb02637ac5f23, kept as/specification/1/workflow-origin.json), and that snapshot marks 74 of the 74 kinds as implemented. agentd applies the workflows an instruction declares when it receives a new version; see agentd.agentd/workflowremains a compatibility dialect name for agentd; new blocks useinstruction/workflow.
The snapshot describes agentd's schema, not a test of agentd itself. Before you rely on a node, check it against the agentd version you run.
Where this list comes from
The tables are built from workflow-registry.json (format instruction-workflow-registry/1), the registry the check uses. It is published with the specification at /specification/1/workflow-registry.json, beside the workflow schema (https://instruction.md/specification/1/schemas/workflow.schema.json). The groups are this page's. A kind added to the registry appears here at the next build, and the build stops until the kind has a group.