Workflows
Source: studio_guide("workflows") (GET /api/studio/v1/guide/workflows) rendered at origin/platform (1afd83f), synced 2026-09-28. Do not edit this page here; change the source and run yarn sync:studio.
A workflow is a small graph of steps Studio runs in the background: on a schedule, when a person presses Run, or when an app, agent or MCP client calls it by ref. Every step reads and writes artifacts; every save is a numbered revision; publishing makes one revision the one that manual and scheduled runs use.
Spec: bicycle.workflow/v1. What this deployment runs: workflow_kinds. A second version of workflows (tasks,
calls, loops, connectors) is designed, not shipped: nothing on this page depends on it.
Work with the person (studio_guide("protocol")): they confirm a try run's numbers before any send is set up, and
they publish.
When to use one
Use a workflow when work must happen without a person at the keyboard, more than once, and leave a record: a weekly digest, a daily exceptions list, a scoring run, a retrain. Use a function for one computation, an agent for judgement, an app schedule to email one view as it is, and an app for a screen.
The loop
workflow_kinds: the step kinds and which ones run here.workflow_create(title, document, files?, model?, timezone?): always saved as revision 1, valid or not.modelis the semantic model itsqueriesrun against;timezonedrives cron and dates (UTC if empty).workflow_patch_preview, thenworkflow_patch(workflow_id, expected_revision, ops): JSON Patch plus typed ops.workflow_put_filewrites one file (sql/,prompts/,schemas/,data/). Every error has afixop you can send back as is. Someone saved first: 409revision_conflict; re-read withworkflow_get, re-apply, and tell the person.workflow_validate, thenworkflow_plan: what would run or reuse the cache, the cost, the sends, the gated changes, and whether a try run and a publish would start.workflow_run(workflow_id, revision=<draft>): a try run. Versions are written, nothing serves, sends only dry-run, and function steps may pin tested draft versions of functions you can edit. Read it withworkflow_run_describeandworkflow_artifact, and show the person the numbers.- Publish.
workflow_publishrefuses gated changes (a send, its approval, a new query, model or Use, AI text underauto, a higher compute budget) with 403gated_change_needs_personor 409human_publish_required, and a draft function pin withfunction_unpublished. A person reviews them (workflow_revision_review) and publishes in Studio. Never work around a gate.
Other tools: workflow_list, workflow_revisions, workflow_artifacts, workflow_approvals (sends waiting for a person),
workflow_settings (who may call it; widening to agents or MCP and on_success: send are a person's),
workflow_update (title, timezone), workflow_trigger_pause / workflow_trigger_resume, workflow_unpublish,
workflow_dependents, then workflow_disable / workflow_enable (soft delete).
Steps
Every step has kind, config, inputs (slot -> artifact) and outputs (slot -> artifact). when is a CEL guard
(inputs.summary.rows > 0): false skips the step and the steps that need it. params take ${run.logical_date}
(with offsets such as ${run.logical_date - P7D}) and ${partition.<dim>}, never the clock.
| Kind | Does |
|---|---|
query | one query from the document's queries block, on the workflow's model; columns take the SELECT's aliases (a sql step quotes a dotted name: "Hotel.CountryCode") |
sql | DuckDB over its input tables: SELECT only, no clock, files or network |
function | a function pinned fn:<tenant>/<name>@<n>, shared with the tenant and exposed to workflows; output slot value is its whole answer. An agent is a function step on an agent function; guard it with when |
llm | one model call per input (or per rows_per_call rows) with a strict output schema; builtin:message gives {subject, body} for a send; effort is the only model control |
classify | rows into a fixed label set; rows below threshold stay unlabelled |
snapshot | a PNG of an app tab. The app must be shared with the whole workspace (snapshot_app_not_shared); a failed screenshot sends nothing |
action | a send: the payload input once per idempotency_key |
python, input, source, detect and explain validate but do not run.
Mapped steps (backtests). A document may declare partitions (for example a static list of origins from
data/origins.json); a step with "map": {"over": {"partition": "origin"}, "max_width": 16, "concurrency": 4}
runs once per partition value, and a downstream sql step with a collect input reduces them. See
studio_guide("example-backtest").
Sends
"send": {"kind": "action",
"config": {"to": {"channel": "email", "recipients": ["<email>"]},
"payload": "digest", "idempotency_key": "digest-${run.logical_date}",
"approval": {"mode": "manual", "approvers": {"roles": ["workflow_owner"]}, "timeout": "P1D"}},
"inputs": {"digest": "digest", "summary": "summary"}, "outputs": {"receipt": "digest_receipt"}}
tois email recipients (1 to 50) or a tenant action ({channel: "action", action_id, variables?};workflow_actions_list).approval: manualholds the send until a person approves the exact payload.autosends as the step runs (never on a try run); an action may run on its own only when a tenant admin allowed it (action_requires_approval).- Mail policy:
workflow_mail_policy. On preview only the deployment allowlist (BSA_WORKFLOW_MAIL_ALLOWLIST) is mailed; other addresses fail at save (recipient_not_allowed). - A key that was sent is never sent again.
max_sends_per_run(default 1, up to 500) fails the step withsend_cap_run; a tenant mails at most 500 recipients a day (send_cap_daily).per: "row"validates but is refused at plan (per_row_not_supported): send one message that lists the rows. - Outcome notices are record settings:
workflow_settings(workflow_id, notify={...}).on_success: send(a person sets it) sends a manual step without asking when every step upstream succeeded.
Triggers
"triggers": {"weekly": {"type": "cron", "cron": "0 8 * * 1", "targets": ["digest_receipt"]},
"manual": {"type": "manual"}}
Cron fires in the workflow's time zone. Adding or changing a trigger is a new revision and a publish; pausing one
is not (workflow_trigger_pause). A run for a logical_date that already has an active run joins it. Targets name
what a run must produce; it runs whatever is stale upstream.
What persists
- Artifacts: every output is a version; a passing production run moves the serving pointer
(
retention.keep_versionsdefaults to 5). - Cache: a step whose inputs, config, files and refs did not change is reused at no cost (
queryalways runs). - Workflow blobs: files a function writes at
{tenant}/workflows/{wf}/store/{name}, declared inblobs. Put the date in the name and keep a small pointer file. A try run has its own empty store. - Send ledger and run history (a root
inv_...with a child per step).
Call it from an app, an agent, MCP or REST
A published workflow is callable by its pinned ref wf:<tenant>/<slug>@<n>. Input: {logical_date?, targets?}.
The call is always a production run as the caller.
{
"functions": {
"my_workflow": {
"ref": "wf:<tenant>/<slug>@<n>"
}
}
}
// A workflow always runs in the background: start it, follow it, allow Cancel.
const started = await bda.fn.call("my_workflow", {}, { wait: false });
// input (optional): { logical_date: "YYYY-MM-DD", targets: ["<artifact>"] }
cancelButton.onclick = () => bda.fn.cancel(started.invocation_id);
const watch = bda.fn.watch(started.invocation_id, batch => showProgress(batch.items));
// batch.items: plain-word lines, e.g. "fetch succeeded · 812 rows · 1.2 s"
const final = await watch.done; // the root invocation: status, output, error, usage
const out = bda.fn.outputOf(final) as {
status: string; partial?: boolean; failed?: string[];
artifacts: Record<string, { version_id: string; rows: number | null; data?: unknown }>;
receipts: { node: string; state: string; approval_id?: string | null }[];
}; // outputOf throws a BdaError in words if the run failed or was cancelled
if (out.partial) showNote(`Some steps did not finish: ${(out.failed ?? []).join(", ")}`);
What comes back (outputOf(final)):
{
"run_id": "run_…",
"status": "succeeded",
"logical_date": "2026-09-21",
"artifacts": {
"<artifact>": {"version_id": "av_…", "rows": 8, "published": true, "data": {"columns": [{"name": "…", "type": "…"}], "rows": [["…"]]}}
},
"receipts": [
{"node": "<send step>", "destination": "email:…", "state": "awaiting_approval", "approval_id": "apr_…", "idempotency_key": "…"}
]
}
// "status": "partial" adds "partial": true and "failed": [steps] (the invocation itself says succeeded).
// artifacts[name].data is inlined for the run's targets while the output stays under 1 MiB; read the rest by
// version_id (GET /api/studio/v1/workflows/{wf}/artifacts/{name}/versions/{version_id}).
// A receipt's state follows the send: awaiting_approval, then sent (or rejected, expired, failed).
Agent. Add wf:<tenant>/<slug>@<n> to the agent's functions (grants.functions) and switch on "Chat and agents" (expose.agents; a person does that in Studio). The agent then has a tool wf_<slug> that starts a run and streams its progress. A data app's chat lists the app's workflow imports as fn_<local>. An agent or app can start a workflow, never approve its sends.
MCP. With expose.mcp on, the workflow is a tool wf_<slug> that starts a run and streams its progress.
REST.
# $STUDIO = https://app.bicycle.ai (preview: https://preview.bicycle.ai); $TOKEN = a Bicycle API token
curl -s -X POST "$STUDIO/api/studio/v1/functions/wf:<tenant>/<slug>@<n>:submit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"input": {"logical_date": "2026-09-21"}}'
# 202 {"invocation_id": "inv_…", "kind": "workflow", "status": "queued", ...} (the run's root invocation)
curl -s "$STUDIO/api/studio/v1/invocations/inv_…?wait_s=25" -H "Authorization: Bearer $TOKEN" # poll: status, output
curl -s "$STUDIO/api/studio/v1/invocations/inv_…/events?after=0&wait_s=25" -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$STUDIO/api/studio/v1/invocations/inv_…:cancel" -H "Authorization: Bearer $TOKEN"
:invoke answers 422 kind_requires_async. Record changes over REST: POST /workflows/{wf}:disable,
POST /workflows/{wf}/triggers/{trigger}:pause.
Limits
At most 50 recipients a step, 500 sends a run, 500 recipients a tenant a day; approvals wait up to 14 days. An llm
step costs at most $25 and a run estimated over $25 is refused. workflow.json up to 256 KiB, a file up to 1 MiB,
32 blobs, 32 targets. The functions a workflow calls share a daily compute budget; "limits": {"compute_units_per_day": N} raises it, and raising it is a gated change.
Mistakes we have seen
function_unpublishedat publish: pin a published version; only try runs may pin tested drafts.recipient_not_allowed: on preview, use an allowlisted address.- A query step returned fewer rows than expected: the row cap drops the rest silently; aggregate in SQL.
workflow_artifactsays there is no serving version: a try run serves nothing; pass itsversion_idfromworkflow_run_describe.
Worked example
A weekly digest (query, sql, llm, an email a person approves): studio_guide("example-weekly-email"). Train and
predict with blobs: example-train-predict. A mapped backtest: example-backtest.
The live node-kind table (what this deployment can run): workflow_kinds.
guide_version bb2461328de4