Skip to main content

Workflows

Synced from bicycle-studio-api

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​

  1. workflow_kinds: the step kinds and which ones run here.
  2. workflow_create(title, document, files?, model?, timezone?): always saved as revision 1, valid or not. model is the semantic model its queries run against; timezone drives cron and dates (UTC if empty).
  3. workflow_patch_preview, then workflow_patch(workflow_id, expected_revision, ops): JSON Patch plus typed ops. workflow_put_file writes one file (sql/, prompts/, schemas/, data/). Every error has a fix op you can send back as is. Someone saved first: 409 revision_conflict; re-read with workflow_get, re-apply, and tell the person.
  4. workflow_validate, then workflow_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.
  5. 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 with workflow_run_describe and workflow_artifact, and show the person the numbers.
  6. Publish. workflow_publish refuses gated changes (a send, its approval, a new query, model or Use, AI text under auto, a higher compute budget) with 403 gated_change_needs_person or 409 human_publish_required, and a draft function pin with function_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.

KindDoes
queryone 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")
sqlDuckDB over its input tables: SELECT only, no clock, files or network
functiona 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
llmone 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
classifyrows into a fixed label set; rows below threshold stay unlabelled
snapshota PNG of an app tab. The app must be shared with the whole workspace (snapshot_app_not_shared); a failed screenshot sends nothing
actiona 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"}}
  • to is email recipients (1 to 50) or a tenant action ({channel: "action", action_id, variables?}; workflow_actions_list).
  • approval: manual holds the send until a person approves the exact payload. auto sends 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 with send_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_versions defaults to 5).
  • Cache: a step whose inputs, config, files and refs did not change is reused at no cost (query always runs).
  • Workflow blobs: files a function writes at {tenant}/workflows/{wf}/store/{name}, declared in blobs. 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_unpublished at 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_artifact says there is no serving version: a try run serves nothing; pass its version_id from workflow_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