Skip to main content

Workflows, when to use one

A workflow is a small set of steps that Studio runs in the background: on a schedule, when a person presses Run, or when an app, an agent or a coding agent calls it. Steps read data, compute, ask AI, take a screenshot of an app and send the result. Each run keeps its outputs, and every send goes through a ledger and, when the step asks for it, a person's approval.

When to use one, and when not​

You need toUseWhy not a workflow
Show numbers, trends and breakdowns in an appa declared query in the appnothing runs later or sends
Compute one answer from one input, on demanda functionone input, one output, no memory between calls
Investigate: pick the evidence, follow leads, explain whyan agentjudgement over messy evidence; call it from a workflow step only when it must run on a schedule
Email people a picture of an app view on a cadencean app scheduleno steps: one saved view, delivered as is
"What changed, and why" on a metric, ad hocDetect and Explainalready built; the workflow detect and explain steps do not run yet
Several steps on a schedule, results kept between runs, a send after a checka workflow
Train a model on a cadence and use it latera workflow with function steps and workflow files
Change something in another system (email, Slack, a ticket)a workflow send step, with approval where a person should look firstnever an agent tool, never app code

A workflow is always asynchronous: a caller starts a run and follows it; the run outlives the caller.

What a workflow is made of​

  • Queries: the semantic SQL the workflow may run, declared once, against the workflow's data model.
  • Artifacts: named outputs (a table, a JSON document, a message, a screenshot, a send receipt). Every step writes to one.
  • Steps (called nodes): query, sql, llm, classify, function, snapshot, action. Each names its inputs and outputs and may carry a when guard so it runs only when a condition holds ("only if there were failures").
  • Triggers: a cron schedule in the workflow's time zone, and manual.
  • Files: SQL, prompts, schemas, small data files.

Details of each step: Steps.

The loop: create, change, publish, run​

  1. Read the guide and the kinds. A coding agent calls workflow_guide and workflow_kinds; they say which steps this deployment runs.
  2. Create (workflow_create with a title, the document, files, the model and the time zone). Saved as revision 1, valid or not.
  3. Change with workflow_patch (small edits, with dry_run: true first: the answer lists every error with a one-line fix you can send back as is) and workflow_put_file. Every save is the next revision; you pass the revision you read as expected_revision, and if someone saved first you get revision_conflict with who and when.
  4. Validate and plan (workflow_validate, workflow_plan): what would run, what is cached, the estimated cost, the sends it would open, and the gated changes a person must publish.
  5. Try run the draft (workflow_run with the draft revision): outputs are written, nothing is served, and sends only dry-run. Use try runs while you build.
  6. Publish (workflow_publish). Manual and scheduled runs use the published revision. A revision with gated changes is refused with the list; a person publishes it in Studio.
  7. Run and watch (workflow_run, workflow_run_describe, workflow_runs, workflow_run_cancel).

In Studio the same loop is the workflow page: the canvas, Check and plan, Run now, the Runs, Versions and Files tabs, and Use (how to call it).

Gated changes need a person​

workflow_publish refuses a revision with gated changes and lists them. Gated: a new or changed send step (its recipients, its approval), a new query, model or a new "Use" (who may call it), anything upstream of a send that needs no approval, and AI-written text going out under automatic approval. A person reviews and publishes those on the workflow's page. A coding agent gives you the link and stops; approving a send is never a tool.

Disable, enable, unpublish​

Deleting a workflow is disabling it: its schedules are deleted, pending approvals and queued runs are cancelled (running ones finish), and new runs, edits and publishes are refused with workflow_disabled. Apps and agents that pin it keep resolving the reference, but their calls are refused. Check what uses it first (the workflow's page lists dependents). Enable restores it. There is no hard delete. Unpublish takes it back to draft: schedules deleted, pending approvals cancelled.

These are done on the workflow's page in Studio, or over REST (POST /api/studio/v1/workflows/<id>:disable, :enable, /unpublish, GET .../dependents); MCP tools for them are landing.

Who may call it​

The workflow's settings say who may start it: apps (on by default), agents and chat, MCP. Switching on agents or MCP takes a person. See Call a workflow from an app.

Where a run shows up​

A workflow run is one root run with one child per step, and a function step's own run under its child. Read it on the workflow's Runs tab, on the Runs page, or with workflow_run_describe.

Next​