workflows

A workflow is a short JS/TS script you author that runs in a sandbox and fans work out across many short-lived leaf agents, orchestrated deterministically. Launch one with run_workflow (inline script OR saved name, exactly one). It returns a runId immediately; the run is asynchronous and you are notified in this conversation when it completes — do NOT poll.

Reach for one when a job is too big, too parallel, or too important for one inline pass. That is more than batch/map-reduce over many items — it also covers exhaustively sweeping or auditing a large surface, researching across many sources and synthesizing, and generating several independent attempts to judge or adversarially verify before trusting the result. For a single task or a quick lookup, do it inline.

The script model

These are the load-bearing invariants. Get them wrong and the run misbehaves silently.

Scripts are SYNCHRONOUS — never await

Host functions block and return their result directly. Write straight-line code.

const r = agent("Summarize this thread."); // r is the result, right here

Do not write await agent(...), and do not make the script async. An async script deadlocks on its second host call — the sandbox can suspend the main evaluation stack but not a promise continuation.

Every script begins with a literal meta

The first statement must be a pure-literal export — no computed values, template strings, or concatenation:

export const meta = {
  name: "triage-inbox",
  description: "Triage and label inbox messages",
};

meta is extracted statically, without executing the script, so it must be a plain object literal with string name and description. The name is how a saved workflow is referenced by workflow(name) and the scheduler.

You must return the result

The script body runs as a function. Its result is whatever it returns at the top level — a bare trailing expression (e.g. result;) is discarded and the run finishes with no result. Always return the value you want surfaced.