Цю сторінку ще не перекладено.

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)
Node kinds by what they do.

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:

A workflow block
:::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.

FieldWhat it does
budgetWhat the step may spend, within the run's limits.
cacheResponse caching. Not with detach; a cached call never skips a required approval or credential decision.
depends_onThe sibling steps this one waits for, by name. Only a done or skipped step satisfies a dependency.
descriptionWhat the step is for, for people reading the workflow.
idempotentWhether running the step again has no further effect, so a host may replay it.
kindThe node kind: one of the kinds below, or a declared extension's alias:node. Required on every step.
on_errorfail (the default), continue, or goto:<step>, a sibling step to route to.
on_replayAfter a crash, what to do with work that may have run: retry (the default), skip or fail.
otelTracing attributes for the step's span.
output_schemaA JSON Schema the step's output must satisfy.
retryretry.max retries after the first attempt (0 to the limit below); retry.backoff is the first exponential delay.
skillsSkills the step may use.
timeoutBounds one attempt, or the node's own wait.
whenA 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

LimitValueWhat it boundsDiagnostic
steps512Steps in one scopelimit-exceeded
body_depth4Levels of nested bodies and brancheslimit-exceeded
retry_max20The largest retry.maxlimit-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 name of 1 to 64 letters, digits, _ and -, starting with a letter or _. It has a nonempty steps mapping and no unknown field (x-* is allowed). It has a key when its concurrency.scope is key.
  • Each step. It has a valid name and a kind this registry has, or a declared alias:node. It has its kind's required fields and no field that is neither its kind's nor a common one. Its depends_on is a list of distinct sibling names. Its retry.max is a whole number from 0 to 20. Its on_error is fail, continue or goto:<step>.
  • Scoping steps. foreach, batch, iterate and subgraph have a body that is {steps: …}. parallel and race have branches, a mapping of names to {steps: …}.
  • Special kinds. A schedule sets exactly one of cron, every and at. A correlate has a window. A switch case 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 and finish appear 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.

KindWhat it doesRequiredOther fields
a2aAccept an authenticated command with declared roles and an input contract.—command, roles, inputs, schema, into
correlateJoin related stream events in a bounded time window; expose missing members in partial results.stream, onby, window, on_incomplete, filter, max_pending, inputs
eventFire on an allowed host event, with a payload filter.onfilter, inputs
loopRe-enter after a prior run, with pacing, backoff and termination bounds.—interval, delay, until, max_iterations, backoff, inputs
manualAdmit a run only after an explicit operator or authorized caller request.—inputs
onceFire when the activated definition is armed; an ensure policy avoids a duplicate live run.—policy, inputs
scheduleFire from one UTC cron, interval or absolute-time declaration.—cron, every, at, inputs
signalFire on an edge-triggered named signal; no implicit retained backlog.namefilter, inputs
streamConsume persisted events with subject selection, durable offsets, batching and rate controls.streamsubject, filter, from, rate, batch, inputs
subscribeRead an MCP resource after notifications, with filtering, debounce and bounded sampling.server, uridebounce_ms, filter, window, inputs
webhookAccept a bound, authenticated HTTP event with filtering, admission and response policy.pathmethods, auth, parallelism, on_overflow, rate, idempotency, respond, filter, inputs, signal, into
Two triggers: by hand or on weekday mornings
:::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.

KindWhat it doesRequiredOther fields
assertFail unless its expression holds, recording the assertion message.conditionmessage
batchRun a scoped body per group, with grouping, size, parallelism and collection policy.over, bodyby, size, parallel, rate, collect, on_error
checkpointRequest an explicit durable checkpoint in the execution record.—name
failEnd the run as a failure with an optional code and message.—message, code
finishEnd the run with a declared terminal status, output and reason.—status, output, reason
foreachRun a scoped body per item under explicit batching and parallelism bounds.over, bodybatch, collect, on_error, as
iterateRepeat a scoped body while/until a condition, bounded by a maximum iteration count.bodywhile, until, max_iterations, collect
joinAwait child/subagent handles, with a deadline and minimum/partial-result policy.handlestimeout, min, partials
noopComplete without an effect; useful as a join or routing point.——
parallelRun named scoped branches concurrently and combine their terminal results.brancheson_error, min_success
raceRun named branches and accept the first qualifying result; cancel the losers.branchestimeout
sleepSuspend on a durable timer for the declared duration.duration—
subgraphEvaluate an inline scoped dependency graph and return its sink outputs.body—
switchSelect one string-valued routing target; prune the unchosen routes.on, casesdefault, on_no_match
waitSuspend on a declared resource, event, task, run, signal or other supported wait condition.onserver, uri, condition, signal, run, subagent, conversation, from, webhook, stream, subject, subscribe, match, task, timeout, on_timeout
A body per ticket, then an assertion
:::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.

KindWhat it doesRequiredOther fields
assignWrite a rendered value into a run variable using its reducer and schema.valuewrites, mode
chunkSplit a value into bounded pieces with optional overlap.value, sizeby, overlap
dedupeRemove duplicate collection members while retaining the first matching member.overby
filterKeep array members whose expression evaluates to true.over, expras
mapApply an expression to each item and return the resulting array.over, expras
parseParse text using a declared data format.textformat
reduceFold an array from an initial accumulator with a declared expression.over, exprinitial, as, acc
sortOrder an array by a selected value/path and direction.overby, order
templateRender text or a typed value from the current run context.—text, value
transformThe assign operation, named for data transformation.valuewrites, mode
validateReturn a value only if it conforms to the supplied schema.value, schema—
Filter, sort and total a list
:::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.

KindWhat it doesRequiredOther fields
classifyChoose among declared classes, preserving confidence and uncertainty policy.input, classesprompt, skills, model, confidence, on_unsure
decideAnswer declared decision questions about a state with confidence controls.state, questionsmodel, confidence, on_unsure
extractExtract structured content that must satisfy an output schema.input, output_schemaprompt, skills, model
judgeEvaluate input against a rubric and optional discrete levels.input, rubriclevels, prompt, skills, model, confidence, on_unsure
routeUse a model to choose among declared routes, with uncertainty handling.input, choicesprompt, skills, model, confidence, on_unsure
summarizeProduce a model summary using declared length, context and model settings.inputlength, prompt, skills, model
thinkMake a tool-free model request for structured reasoning/output under a declared contract.promptoutput_schema, reads, check, retries, skills, system, model, effort
Classify a message and extract its facts
:::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.

KindWhat it doesRequiredOther fields
agentRun a bounded tool-using model turn with explicitly narrowed capabilities.instructionoutput_contract, output_schema, tools, servers, limits, context, skills, system, model, effort
subagentDelegate 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
workflowInvoke a named child workflow synchronously, asynchronously or detached, with explicit cancellation propagation.nameinputs, mode, start, version, cascade
workflow.cancelRequest cancellation of an authorized target run.runreason
workflow.signalSignal an existing waiter or an explicitly selected run.namepayload, run
workflow.waitAwait a child or referenced run with an optional deadline.runtimeout
A child agent's research, published by another workflow
:::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.

KindWhat it doesRequiredOther fields
httpMake an authorized HTTP request with response, credential, retry and idempotency policy.urlmethod, headers, query, body, json, timeout, expect, allow_private, sign, idempotency, breaker, rate, auth, payment
mcp.resourceRead/list resources, use a prompt, or request completion through a declared MCP server.server, opuri, name, arguments, reference, argument
mcp.toolCall a named tool on a declared MCP server, with task, elicitation and resilience options.server, toolargs, idempotency, breaker, rate, detach, input, payment
toolCall an explicitly granted tool by its host registry name.nameargs, detach, input
An MCP tool call with retries, then an HTTP request
:::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's op chooses a resource read or list, a prompt, or a completion.
  • mcp.tool can receive an MCP task. A plain call follows the task to its end; detach returns a handle a later wait uses; input describes the human input the task may ask for. A detached call can't be cached.
  • payment, auth, auth_to and sign are 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.

KindWhat it doesRequiredOther fields
knowledge.getRetrieve a selected knowledge item and its content metadata.—id, uri
Search a configured knowledge provider and return ranked hits.querytop_k, filters
search.fetchRetrieve a selected page/resource within a byte bound.urlmax_bytes
search.queryQuery a configured search provider with explicit result and freshness bounds.querylimit, freshness
Answer from the knowledge base and the web
:::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.

KindWhat it doesRequiredOther fields
memory.deleteDelete an accessible durable memory key.key—
memory.getRead an explicitly bound durable memory key.key—
memory.listList accessible memory keys with prefix and result bounds.—prefix, limit
memory.popRemove and return the final member of a durable memory collection.key—
memory.pushAppend a value to a durable memory collection.key, value—
memory.setWrite a durable memory key, optionally with a time-to-live.key, valuettl
memory.shiftRemove and return the first member of a durable memory collection.key—
Remember what the last run saw
:::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.

KindWhat it doesRequiredOther fields
artifact.createStore content as an artifact with media type and sensitivity metadata.namemime, content, from_step, sensitive
artifact.deleteDelete an artifact the active principal may manage.id—
artifact.getRead an artifact under the host access policy.id—
Store a draft as an artifact
:::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.

KindWhat it doesRequiredOther fields
emitRecord a value/audit note or append an event to a declared stream.—note, audit, value, stream, subject, data, correlation, forward
humanSuspend for an authorized person to answer a question under an optional schema.questionschema, to, timeout, reply_uri
messageDeliver a message through an authorized channel, optionally awaiting a reply.totext, parts, wait, timeout, on_timeout
A person approves, and the team hears about it
:::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.

KindWhat it doesRequiredOther fields
a2a.delegateDelegate an objective and output contract to an authorized peer.peerobjective, command, args, output_contract, timeout, idempotency, breaker, rate, auth_to, auth_timeout, payment
a2a.sendSend an authenticated message or command to a named destination.toparts, command, args, context, timeout, idempotency, breaker, rate, payment
a2a.waitWait for a matching conversation response from an expected peer.fromconversation, timeout
Delegate to a peer agent
:::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.

A custom node
---
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/workflow remains a compatibility dialect name for agentd; new blocks use instruction/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.

Last checked against the product:

Was this page helpful? Report a problem