Flow Features And Config Toggles
Breyta feature matrix for authoring and operating advanced flows.
Goal
Provide one checklist of core flow fields, step capabilities, and operational toggles.
Quick Answer
Use this page to verify that your flow covers triggers, templates, waits, notifications, persistence, and bindings with canonical config shapes.
As complexity grows, keep :flow orchestration-focused and move shaping/body content into top-level :functions and :templates.
Treat :persist as a common default for data-heavy steps, not a niche option.
Flow Definition Surface
| Field | Purpose | Common options |
|---|---|---|
:slug, :name, :description | Identify and describe the flow. | Stable slug + editable human label. |
:concurrency | Control overlap/version handoff. | :singleton, :keyed, :on-new-version. |
:triggers | Define run entry points. | :manual, :schedule, :event with :source :webhook. |
:requires | Declare connection/secret/form requirements. | Configured through flows configure (or install-specific paths). |
:templates | Store reusable HTTP/LLM/DB/notify payloads. | Referenced via :template + :data. |
:functions | Store reusable Clojure transforms. | Called via flow/step :function and :ref. |
:flow | Orchestrate deterministic control logic and step calls. | Keep orchestration-focused, not transform-heavy. |
For detailed overlap/version behavior choices, see Run Concurrency.
Trigger Choice By Target
| Target | Practical trigger preference | Notes |
|---|---|---|
draft | Prefer :manual while authoring. | You can still test webhook paths through the draft-event API route for webhook-specific validation. |
live | Prefer :schedule for unattended automation, plus installation/live webhooks when needed. | Treat live trigger surfaces as stable runtime entrypoints. |
Step Capabilities And Toggles
| Step / toggle | Core shape | Use |
|---|---|---|
:http | :connection, :method, :path, :template, :data, :retry | External API calls with optional retries and templating. |
:llm / :db | Template-backed prompt/query composition | Keep prompt/query bodies reusable and reviewable. |
:wait | :key, :timeout, :on-timeout, :notify, optional :webhook | Human/webhook callback orchestration with bounded waits. |
:notify | :channels (:http), optional :template | Outbound notifications and delivery hooks. |
:persist | {:type :blob} or {:type :kv} | Store large outputs/state handoff as refs. |
:kv | :operation (:get, :set, :append, etc.) | Durable keyed state between steps/runs. |
Orchestration Primitives (Non-Step)
| Primitive | Purpose | Notes |
|---|---|---|
flow/call-flow | Explicit child-flow orchestration | Reuse focused subflows instead of copying complex branches. |
Flow forms (let, do, if, cond, for, loop, etc.) | Deterministic control flow | Keep transforms in top-level :functions. |
flow/poll | Bounded status polling | Built on deterministic loop + sleep semantics. |
Metadata labels (^{:label ...}) | Timeline readability | if/if-not support :yes/:no; loop supports :max-iterations. |
flow/input | Run input entry | Call once near top and pass narrowed maps downstream. |
Use flow/call-flow when one branch grows into a separate lifecycle (for example: ingress flow -> routing flow -> apply flow). Keep parent flow responsible for orchestration and move shaping into top-level :functions.
'(let [input (flow/input)
normalized (flow/step :function :normalize {:ref :normalize :input input})
routed (flow/call-flow :billing-route (:route-input normalized))
result ^{:label "Apply routed action?"
:yes "Call apply flow"
:no "Skip apply"}
(if (:should-apply routed)
(flow/call-flow :billing-apply (:apply-input routed))
{:skipped true})]
{:routed routed
:result result})
See construct metadata and polling details:
Loop pattern for bounded item processing with explicit persistence:
'(let [input (flow/input)
items (:items input)
batch (reduce (fn [acc item]
(let [item-result (flow/step :http :process-item
{:connection :api
:method :post
:path "/process"
:json {:id (:id item)}
:persist {:type :blob}})]
(conj acc item-result)))
[]
items)
summary (flow/step :function :summarize
{:ref :summarize
:input batch})]
summary)
Security And Runtime Controls
| Control | Guidance |
|---|---|
| Webhook auth | Declare explicit :auth {:type ...} on webhook triggers. |
| Secret handling | Store secret material in bindings, never in flow files. |
| Retry policy | Use :retry {:max-attempts ... :backoff-ms ...} for transient failures. |
| Runtime limits | Payload/output limits are enforced at runtime. |
| Persistence posture | Plan refs/:persist early because inline limits are reached quickly. |
High-Impact Limits
| Limit | Value | Notes |
|---|---|---|
| Flow payload (core definition map) | 150 KB | Excludes template/function body content. |
| Effective package budget with templates/functions | ~2.1 MB | Externalize large prompt/request/query content into templates/functions. |
| Max step result | 1 MB | Hard per-step output cap. |
| Inline result threshold | 256 KB | Exceeding this usually requires :persist. |
| Webhook payload max | 50 MB (signed multipart: 5 MB) | See webhook transport and signing mode details. |
Platform-managed LLM :max-tokens clamp | 10000 per call | Applies to platform-managed keys. |
| Wait timeout | Default 24h, max 30 days | Set explicit bounded timeout in wait configs. |
See full list: Limits And Recovery
CLI Commands That Surface These Features
| Command group | Use |
|---|---|
breyta flows pull/push/configure/configure check/validate | Authoring and configuration lifecycle. |
breyta flows release / breyta flows installations ... | Advanced rollout and installation targeting. |
breyta flows run <slug> --wait | Runtime verification after changes. |
breyta resources search / breyta resources workflow list / breyta resources read | Find and inspect persisted run artifacts and refs. |