Patterns (Do/Do Not)
Quick Answer
Use this guide for proven Breyta flow patterns and anti-patterns across bindings, templates, persistence, and orchestration.
Configuration flow
| Pattern | Why |
|---|---|
Declare :requires in the flow definition. | Makes runtime dependencies explicit and bindable. |
Configure required slots/inputs with flows configure. | Binds slots and activation inputs without code edits. |
Use flows release only for explicit rollout/governance. | Keeps authoring and rollout concerns separated. |
Use explicit run targeting only when needed (--target live, --installation-id). | Keeps default authoring runs simple and deterministic. |
Template usage
| Pattern | Why |
|---|---|
Put large payloads in :templates. | Reduces flow payload size and review noise. |
Reference with :template and :data. | Keeps step configs concise and reusable. |
Output sizing
| Pattern | Why |
|---|---|
| Estimate output size before adding data-producing steps. | Avoids late failures from size caps. |
| Keep inline outputs small and predictable. | Maintains stable orchestration payloads. |
Default to :persist for unknown/unbounded size. | Prevents inline overflow for exports/pagination/files. |
Pass refs downstream (:body-from-ref, :from-ref). | Avoids rebuilding large inline payloads repeatedly. |
Cross-flow handoff
| Pattern | Why |
|---|---|
Persist shared state to KV and read with :kv operations. | Supports structured handoff across runs/flows. |
| Use deterministic keys (workspace + period + shard/page). | Keeps retries idempotent and traceable. |
Use flow/call-flow directly for same-app children in a linked public install. | The parent install context carries the source app, selected plan, and binding profile to app children. |
Use an unqualified flow/call-flow from a draft parent for same-workspace author-owned children that need profile-bound requirements. | Child preparation selects the enabled draft profile for the child flow without hardcoding a profile id. |
Pass an explicit :installation-id, :profile-id, or live target when calling children outside the same app/install context. | Prevents missing-runtime-target failures for child :requires. |
| Treat a draft profile id as a child-flow target, not a parent-flow target. | Profile ids are flow-specific; installed public flows need the consumer :installation-id. |
Use :fanout only for bounded child-workflow batches (:call-flow items or named :agent items). | Keeps concurrency enforceable and avoids reopening generic parallel side effects. |
Let an orchestration agent use :tools {:fanout {:agents [...]}} for dynamic specialist fanout. | Keeps agent choice bounded before starting child workflows. See Orchestration Agent Fanout. |
| Keep async child fanout at one orchestration depth. | Prevents recursive child spawning from exhausting shared runtime budgets. |
Polling
| Pattern | Why |
|---|---|
Use flow/poll for external completion checks. | Provides bounded deterministic polling behavior. |
Set :timeout or :max-attempts. | Prevents unbounded polling loops. |
Use :return-on for success and terminal provider outcomes, then branch on the result; use :abort-on for API/transport errors. | Stops polling a finished actor while keeping provider failures from looking like successful flow runs. |
Prefer :backoff over manual interval math. | Centralizes retry interval control. |
Set :id for sleep step stability. | Improves trace/test consistency. |
Treat provider maxPosts/limit fields as provider hints, not Breyta cost caps. | Provider actors may paginate, fan out, or emit more events than the requested item count. |
| Probe external actors with a small query and item budget before scaling target counts. | Reveals actual provider event/cost behavior before a large run. |
| Cancel the remote actor separately when a poll timeout must stop provider work. | A Breyta polling timeout stops status checks; it does not necessarily stop the remote actor. |
| Report requested target count, provider candidate pool, evaluated candidates, and accepted results separately. | A target count is often an output goal, not a guarantee after caps, filtering, deduplication, and provider availability. |
| Preserve explicit ICP and role keywords, or expose the effective inferred terms and an override. | Keyword inference must not silently remove high-signal intent such as owner or decision-maker titles. |
Working copy vs release
| Command | Effect |
|---|---|
flows push | Creates/updates working copy and draft target. |
flows release | Publishes an immutable release and updates live install for the selected workspace by default. |
Do And Do Not
| Do | Do not |
|---|---|
| Keep flow body deterministic. | Hardcode secrets in steps. |
Use :function steps for transforms. | Use map/filter/reduce in flow body. |
| Include a manual interface for discoverability. | Call nondeterministic functions in flow body. |
| Use connection slots for credentials. | Keep large/unpredictable payloads inline instead of :persist. |
Public reusable flows
| Pattern | Why |
|---|---|
| Name reusable/public flows around one clear query intent. | Stronger landing pages and easier discovery in search and AI-search tools. |
| Use outcome-first titles with the main integration when useful. | Helps users understand value quickly. |
Rewrite visible step :title labels into plain-language actions. | Improves public-page quality and operator readability. |
| Keep slug, title, description, and tags aligned around the same use case. | Prevents mixed search signals and thin page positioning. |