Breyta Docs
Docs
Build

Flow Authoring

Breyta flow authoring guide for production workflows: structure definitions, publish safely, configure runtime requirements, and promote releases.

Quick Answer

Author in a strict sequence: define shape, push updates, configure + check runtime requirements, optionally validate, release an immutable version, then run.
Keep orchestration thin in :flow and move shaping logic/content into :functions and :templates as complexity grows.

Do This Now

Design your flow in this order:

  1. define :slug and :name
  2. set :concurrency
  3. declare setup in :requires
  4. declare per-run input in :invocations
  5. expose manual/client ingress in :interfaces and time automation in :schedules
  6. define the final output contract
  7. implement :flow with deterministic logic

For public/end-user flows, define the output contract as a human presentation surface before release. Default to one readable Markdown artifact; use a curated table or dedicated media viewer only when that viewer is clearly better for the user. When a Markdown report needs real Breyta tables, charts, downloads, images, video, nested Markdown, or JSON resources, embed them with fenced breyta-resource blocks so they render in the document flow. Keep raw structured/debug payloads out of the final public result unless they are explicitly the intended output.

What This Does

  • keeps flow behavior predictable
  • separates runtime bindings from authoring
  • reduces replay and debugging issues

For the exact command lifecycle (push/validate/release/configure/run), use CLI Workflow.

When To Use

Use this once your first flow works and you need production-ready structure.

Advanced Options

  • keyed concurrency
  • multi-interface and scheduled flows
  • reusable requirements/bindings
  • templates for prompts, request bodies, and SQL
  • function refs for reusable deterministic transforms
  • :persist refs for data-heavy step outputs: inline results should stay
    under 512 KB, 1 MB is the hard step/DB/code/notify payload cap, and persisted
    blob writes cap at 50 MB retained or 4 GB ephemeral
  • :metering on steps with known API/tool costs, so creator-facing run cost estimates have readable line items
  • child-flow orchestration with flow/call-flow for complex branches
  • bounded child-workflow batch spawn/collect with :fanout when every item is {:type :call-flow ...}

Production Pattern: Parent + Child Flows

When a single :flow starts mixing ingress logic, routing, and domain application behavior, split it:

  1. parent flow does ingress + normalization
  2. parent delegates specialized branches with flow/call-flow
  3. parent uses :fanout only for bounded sibling child-workflow batches when spawn/collect semantics are needed
  4. each child flow owns one domain concern (routing, apply/update, reporting)

This keeps orchestration readable and reduces duplicate branching logic across flows.

Common Anti-Patterns

  • adding bindings commands before push succeeds
  • hiding side effects in non-step code
  • changing many steps at once without isolation checks
  • using unclear step ids that make timelines hard to read
  • returning internal tables, res:// refs, or raw debug maps as public manual-run output
  • pasting EDN/JSON maps into Markdown paragraphs instead of using a raw viewer, JSON resource embed, or fenced code block

Go Deeper

As of May 20, 2026