run-workflow

Programmatic Workflows (RunWorkflow)

Use RunWorkflow when a deterministic pipeline should orchestrate multiple subagents — fan-out research then synthesize, classify then act per item, generate then verify. Prefer it over issuing many Task calls yourself when the dispatches are data-driven (one per ticker, per filing, per finding). Do NOT use it for a single subagent (use Task) or for code that dispatches nothing (use ExecuteCode).

The script

You write JavaScript (ES2020). It executes server-side: the script itself cannot touch the workspace filesystem — the subagents it dispatches can. The script must declare a pure object literal first:

export const meta = { name: 'ticker-briefs', description: 'Fan out research, synthesize' }

name (letters, digits, -, _) and description are required; no variables or function calls inside the literal. The rest of the body is free-form async JS — top-level await and return both work, and the return value (JSON-serializable) becomes the run result. Return a synthesis rather than the raw children: a large result is clipped for display, and a clipped object is unparseable.

Built-ins

• await agent(prompt, opts?) — dispatch one subagent, resolve to its result text. The child starts blank: it sees nothing of this conversation, of the script, or of its sibling children, so the prompt must carry everything it needs — and its final text is the whole of what comes back. opts: agentType (default 'general-purpose'; same types as Task), label (display name), phase (progress group), schema (JSON Schema — the child answers as matching JSON and the resolved value is the parsed object, or null if it cannot).
• await pipeline(items, ...stages) — the default for multi-stage work. Each item flows through every stage independently, with NO barrier between stages: item A can be in stage 3 while item B is still in stage 1, so the run costs the slowest single chain rather than the sum of each stage's slowest item. Each stage receives (prevResult, originalItem, index); a throwing stage nulls that item and skips its remaining stages.
• await parallel(thunks) — run an array of () => Promise thunks concurrently, resolving to results in order; already-started promises (parallel([agent(...), ...])) work too. Use it for a single fan-out, or where the next step genuinely needs the whole set at once — dedup across all results, an early exit when the count is zero, one child weighing the others. Needing to map/filter between stages is not such a case: do that inside a pipeline stage.
• phase(title) / log(message) — progress markers streamed live to the user.
• args — the params value passed to RunWorkflow, verbatim.