Step Reference
Quick Answer
Use this page as the step hub: compare step families here, then jump to the
detailed step page you need. For the broader docs map, use
Reference Index. For the full CLI surface, use
CLI Commands.
Built-in step families use unqualified keywords like :http and :files.
Flow-local packaged steps defined under top-level :steps use qualified
keywords like :github/open-pr and are invoked through the same flow/step
surface. Flow-local agent definitions under top-level :agents use qualified
keywords like :review/security and are also invoked through flow/step.
Step Families At A Glance
| Step type | Core fields | Notes |
|---|---|---|
:http | :connection or :url, :path, :method, :query, :headers, :json, :body, :response-as, :client-opts, :persist, :auto-search-index?, :retry | Large and binary bodies should use :persist; safe page GETs can be auto-indexed for workspace search. |
:llm | :connection, :model, :messages or :prompt, :template, :data | Use templates for long prompts. Multipart messages can include uploaded image resources for vision-capable models. |
:agent | :objective, :inputs, :connection, :tools/:available-steps, :memory, :cost, :approval, :trace, :output-persist | Agent with memory, approval, tracing, and bounded tools. Expose narrow built-ins directly; wrap broad side effects in packaged :steps. |
:mcp | :adapter, :tool, optional :arguments | Deterministic outbound Streamable HTTP MCP tool call through a top-level :mcp adapter. Use :tools {:mcp [...]} on :llm/:agent when the model should choose the call. |
:db | :database, :connection, backend-specific fields | SQL/BigQuery use :sql/:template + params; Firestore uses :collection/:where. |
:wait | :key, :notify, :timeout | Supports human/webhook resume patterns. |
:function | :code or :ref, :input, :load, :persist | Map-oriented transforms; persist large or table-shaped outputs. |
:job | :op, plus :job-type, :job-id, or :batch-id depending on op | External jobs control plane submit/get/await surface. |
:notify | :channels (:http), optional :template, :data | External delivery channels only. |
:kv | :operation, :key, operation-specific fields (:value, :ttl, :prefix) | Useful for state handoff/cache patterns. |
:table | :op, :table, op-specific fields (:where, :sort, :group-by, :metrics, :column) | Bounded table-resource query, aggregate, export, authored-column, and derived-table surface; creation happens through :persist {:type :table ...}. |
:files | :op, :source, op-specific fields (:query, :paths, :path-prefix, :changeset, :edit, :branch, :commit-message, :title) | Source-tree read/search/edit/materialize/capture with persistent changeset-ref overlays; supports publish/change-request flows. Direct flow/step :files calls are valid in orchestration; agent tool exposure only supports the safe subset directly, and broad repo/session ops such as :resolve-source, :materialize, :capture, :heartbeat, :status, :release, :publish, and :open-change-request need packaged :steps wrappers. |
:fanout | :items, optional :max-concurrency, :on-error, :transform | Async only for one child-workflow mode at a time: all :call-flow items or all named :agent items. Legacy non-child items run on the sequential compatibility path. |
:sleep | one of :seconds, :millis, or :duration | Deterministic delay boundary. |
:ssh | :connection, :command, :env, :workdir, :timeout | Remote exec over SSH; for agents use :ssh kickoff + :wait callback. |
:search | :query, optional :mode, :targets, :limit, :hydrate, storage filters | Workspace search across :resources, :flows, :runs, and :connections; resource search defaults to hybrid retrieval and can opt into strict lexical or semantic-only retrieval. |
:breyta | :op, :allow, optional :args, optional :mutations, optional :require-approval | Workspace-scoped control-plane operations for agents, including flows, runs, docs, resources, and explicitly granted mutations. |
Common Step Options
| Option | Meaning | Typical use |
|---|---|---|
:title | Readable step label | Improves timeline readability. |
:timeout | Step timeout seconds | Bound slow external operations. |
:retry | Retry policy | Handle transient external failures. |
:on-error | Error policy (:fail, :skip, :checkpoint) | Control failure handling behavior. |
:persist | Store outputs as refs | Keep large outputs out of inline payloads. |
:metering | Advisory per-step cost estimate | Add fixed API/tool costs to creator-facing run cost breakdowns. |
:review / :confirm | Human checkpoints | Add explicit approval/verification points. |
For packaged steps, these common options still live on the outer flow/step
wrapper. The packaged definition itself should focus on the simplified
input/output contract for the wrapped built-in step.
Detailed References
| Reference | Scope |
|---|---|
| Step HTTP | HTTP request/response and persistence behavior |
| Step LLM | LLM message/prompt and tool usage |
| Step Agent | Objective/input-oriented wrapper over the LLM tool loop |
| Step MCP | Deterministic outbound MCP tool calls through flow-level adapters |
| Step Breyta | Native workspace-scoped Breyta control-plane operations for agents |
| Step DB | Shared DB step concepts and backend split |
| Step DB SQL | SQL backends (:postgres, :mysql, :clickhouse) |
| Step DB BigQuery | BigQuery-specific DB behavior |
| Step DB Firestore | Firestore-specific DB behavior |
| Step Wait | Wait/signal/timeout and approval flows |
| Step Function | :function step and deterministic transforms |
| Step Job | Jobs control plane submit/get/await step surface |
| Step Notify | Notification channel delivery |
| Step KV | KV read/write/list operations |
| Step Table | Table-resource query, aggregate, column-authoring, export, and bounded mutation operations |
| Step Files | Source-tree resolution plus persistent changeset-ref overlays for read/search/edit/materialize/capture/diff, then branch publish and pull-request operations over that same logical state |
| Step Fanout | Bounded child-workflow fanout and legacy compatibility behavior |
| Step Sleep | Sleep timing semantics |
| Step SSH | Remote exec and agent kickoff patterns |
| Step Search | Workspace search step behavior and limits |
| Packaged Steps | Flow-local qualified-keyword step wrappers with schema, direct invocation, and agent tool publication |
| Persisted Results And Resource Refs | Working with persisted refs/resources |
| Run Cost Estimates | :metering, token pricing, and run cost breakdowns |