Workflow Authoring

Workflow authoring reference

Everything below is about writing the script. Whether a workflow may run at all is decided by the Workflow tool's own opt-in rule — this reference does not authorize a run.

Reach for one to be comprehensive (decompose the work and cover every part in parallel), to be confident (independent perspectives and adversarial checks before an answer is committed to), or to take on scale a single context cannot hold — migrations, audits, broad sweeps. The script is where that structure is encoded: what fans out, what verifies, what synthesizes. Parallelism on its own is not a reason; work that is already one short sequence of edits belongs in the main loop.

Scout first, then orchestrate

The strongest pattern is hybrid: discover the work list in the main loop (list the files, scope the diff, read the failing test), then hand that list to a workflow. You do not need to know the shape of the work before the task — only before the orchestration step. When the work has distinct phases, run several small workflows across turns and read each result before choosing the next, rather than authoring one large script that runs unattended.

Common single-phase shapes: understand (parallel readers over subsystems, merged into one map), design (independent approaches, judged, then synthesized), review (dimensions, find, verify each finding), research (broad sweep, deep read, synthesis), migrate (discover sites, transform each under isolation: 'worktree', verify).

Script contract

The source is wrapped as an async IIFE, so top-level await and a top-level return are both legal — and a trailing expression is not a return value. End every successful path with an explicit return.

It is plain JavaScript, not TypeScript, and it cannot import anything. A script with a dynamic import() anywhere in it — even in a branch that never runs — is refused before it starts, so none of its agents runs first; do file, network, and package work inside an agent instead.

The script may start with a literal export const meta = {...} declaration with name, description, and optionally whenToUse and phases: [{ title, detail? }]. It must be a pure literal — no variables, calls, or interpolation — and it is stripped before execution, so nothing in the script body can read it. Fields outside that list are dropped. The approval dialog prints the name, the description, and each phase title with its detail as a one-line explanation beside it: give every phase a detail, because for a run that may dispatch hundreds of agents it is what the user reads before approving. In a workflow an extension ships, whenToUse also lists the workflow for the model to start when a request matches it; leave it out and the workflow runs only when someone asks for it by name.

Injected globals, and nothing else:

• phase(title) — open a phase. Everything dispatched afterwards is attributed to it in the live phase tree, until the next phase opens.
• log(msg) — one line into the run log the user watches.
• agent(prompt, opts?) — dispatch one subagent. See agent() options.
• parallel(thunks) — run thunks through the shared concurrency window, resolving to a position-aligned array. parallel() itself rejects on invalid arguments.
• pipeline(items, ...stages) — run each item through the stages independently. See Default to pipeline().
• workflow(nameOrRef, args?, { stepId }?) — run a saved workflow inline. See Saved workflows and workflow().
• args — the structured value the caller passed, or undefined.
• budget — { total, spent(), remaining() }. See Scaling to the token budget.

Pass THUNKS to parallel(), not eager calls: parallel([() => agent(...)]), not parallel([agent(...)]). The eager form is refused outright: a non-function element rejects the whole batch, and by then every agent() in it has already been admitted, counted against the caps, and spent — with its result discarded.

Each list a single call takes — the thunks of parallel(), and the items and the stages of pipeline() — holds at most 4096 entries. A longer list rejects the whole call before any of its thunks or stages runs; it is never truncated. Like any invalid argument, that rejection can be caught, and inside an outer parallel()/pipeline() it becomes that slot's null. The limit is per call, not per run: split a larger input into batches of thunks and await each in turn. Batching does not lift the agent cap or the token budget.

const thunks = files.map((file) => () => agent(`Summarize ${file}`));
let summaries = [];
for (let i = 0; i < thunks.length; i += 4096) {
  summaries = summaries.concat(await parallel(thunks.slice(i, i + 4096)));
}

A script must be deterministic so a resume replays the same call sequence. Math.random() throws, and so does all of Date — Date(), new Date(), Date.now(), Date.parse() and Date.UTC() alike. Pass timestamps in via args, or stamp the result after the workflow returns. A script that calls any of them is refused before it starts, so none of its agents runs first.

Scripts run in a node:vm sandbox with no filesystem, shell, network, or environment access. All I/O happens through the prompts you give the agents, so say explicitly what each one should read and whether it may edit files.

agent() options

agent(prompt, { stepId?, label?, phase?, schema?, model?, effort?, agentType?, isolation?, workingDir?, stallMs?, disallowedTools?, tools? })

• stepId (string, ≤128 chars) — optional caller node ID; does not affect caching. Also accepted in workflow() options.
• label (string) — display name in run views and failures. Make it unique per dispatch to distinguish failures.
• phase (string) — opens a named phase at this call, exactly as phase(title) would: this dispatch and every dispatch issued after it are attributed to that phase. It is not scoped to the one call, so in a fan-out open phases with phase() between groups rather than per dispatch.
• schema (JSON Schema object) — the subagent must deliver its result by calling structured_output with arguments matching the schema; agent() resolves to the validated object. A schema that does not compile, or that requires a property its own object forbids, makes agent() resolve to null without starting the agent. Each failed submission hands its error back to the agent, and the third failed submission stops it. With no valid result agent() resolves to null and the failure states how many submissions failed and the last error; check for null.
• agentType (string) — resolves against the declarative-agents registry (.qwen/agents/<name>.md, project then user then built-in). Unresolved names make the admitted agent() resolve to null and record "agent({agentType}): agent type 'X' not found"; check for null.
• model (string) — per-call model override; routes provider correctly via the subagent runtime view.
• effort ('low' | 'medium' | 'high' | 'xhigh' | 'max') — the reasoning effort for this one agent. It is limited to the tiers /effort offers for the agent's model or, for a model whose settings declare none, to the tiers its provider's built-in table accepts: a tier the model does not offer becomes the next stronger tier it does offer, or its strongest tier when none is stronger. A model that offers no tiers, or thinking turned off for the session or the model, leaves the agent with the effort it would have had without the option. The session's own effort is never changed, and an explicit tier replaces any thinking budget the agent would otherwise inherit; a thinking setting fixed in the provider settings (such as extra_body or samplingParams) still takes precedence over the tier, as it does over /effort. Omitting effort inherits the session's effort only while the agent stays on the session's provider: a model override that switches provider starts from that model's own reasoning settings, so pass effort there. Aliases such as 'med' and 'x-high' are accepted; any other value rejects the call. Use 'low' for cheap mechanical stages and the higher tiers only for the hardest verify or judge stages. A different effort is a different resume cache key.
• isolation — 'worktree' provisions a fresh git worktree under <projectRoot>/.qwen/worktrees/agent-<7hex>; the worktree is auto-removed if no changes, otherwise the path and branch are returned alongside the result. 'remote' makes the admitted agent() resolve to null and records "agent({isolation:'remote'}) is not available in this build". A 'worktree' dispatch is also refused — it resolves to null with the reason recorded — when the session is already inside a worktree (nested isolation worktrees are not supported; to run agents in that worktree, pass it as workingDir), when git is not available or the directory is not a git repository, when the parent working tree has uncommitted changes (the subagent would see a stale HEAD), or when the worktree cannot be created. The nested case refuses every dispatch, so rule it out before a large isolation: 'worktree' fan-out.
• workingDir (string) — pin the subagent to an EXISTING git worktree of this repository that the caller owns; nothing is created and nothing is removed. Use it when the directory the agent must work in already exists and its uncommitted state is the point (a review worktree, a checkout a previous step provisioned) — exactly the case isolation cannot serve. Mutually exclusive with isolation. The path must be a linked worktree of this repository registered via git worktree add (it may live anywhere on disk) — the main checkout is not eligible.
• stallMs (number, ms) — a no-progress stall watchdog, not a wall-clock cap. The dispatch is aborted and retried (up to 3 attempts total) after this many milliseconds with no observable subagent progress — including before the first response arrives; the timer is suspended while a tool is in flight, so a legitimately slow tool is not a stall. Default 180000 (override via QWEN_CODE_WORKFLOW_STALL_SECONDS, whole seconds); 0 disables the watchdog. Wall time per attempt is bounded separately.
• disallowedTools (string[]) — tools this agent may not call, on top of the floor below; it can only narrow the agent's tools, never re-enable one. Name a tool by its tool name (run_shell_command, write_file, edit) or its display name (Shell, WriteFile, Edit), or deny MCP tools with mcp__<server> (every tool of that server), mcp__<server>__*, or mcp__<server>__<tool>. An entry that names no built-in or registered tool and is not an mcp__ pattern, such as 'Bash', resolves the call to null with the reason recorded rather than silently denying nothing. Entries must be non-empty strings without surrounding whitespace, or the call is rejected. A schema agent whose denies, from this call or from its agentType, include structured_output resolves to null with the reason recorded, because it would have no way to return its result. The resume cache key depends on which tools are denied, not on their order or duplicates, and not on whether a built-in tool is named by its tool name or its display name.
• tools (string[]) — the only tools this agent may be given; it narrows and never brings back a tool the floor below or a deny takes away. Name tools exactly: a built-in by tool or display name, an MCP tool by the name the model sees (mcp__<server>__<tool>). Patterns ('*', mcp__<server>, mcp__<server>__*), exec and an empty list reject the call; in code mode the agent keeps exec, which can call only the listed tools. An entry that names no tool, such as 'Bash', resolves the call to null with the reason recorded, and so does a list that shares no tool with the agentType's own allowlist or whose every tool is denied. A schema agent is also given structured_output. A correctly named tool this session does not have, or one no subagent may use (such as todo_write), is simply not given, as with an agentType allowlist. Built-in spellings, order and duplicates do not change the resume key; other spellings do.

Workflow subagents can never use AskUserQuestion, SendMessage, Monitor, EnterPlanMode, ExitPlanMode, or the Agent tool, whatever their agentType or their tools. A subagent therefore cannot fan out further and cannot ask anyone anything: the script owns all fan-out, and every ambiguity has to be resolved in the prompt it is given. Never ask a subagent to spawn its own verifiers — dispatch them from the script.

What agent() returns

A subagent's final text, or the validated object under schema.

agent() resolves to null when that admitted agent fails on its own — including turn/time caps, model or setup errors, missing structured output, and exhausted stall retries — and it does so for a bare await agent() exactly as it does inside parallel()/pipeline(), so check for null wherever you read a result. Call-shape validation failures — such as an empty prompt, an unsupported option combination, or an invalid option value — reject a bare call; inside parallel()/pipeline(), the surrounding ordinary thunk or stage rejection becomes a position-aligned null. Run-level rejections no later call could survive — the token budget, the 1000-agent cap, and cancellation — throw and end a parallel()/pipeline() batch. An admitted agent that fails and settles to null still counts as dispatched and is named, with its error, in the run's failures list; a null returned by an ordinary thunk or stage is not an agent dispatch.

A pipeline() stage that returns null — or throws — drops that item: its remaining stages are skipped and its slot in the result is null. So a null check belongs in the stage that dispatched the agent, never in a later stage, which will not run for that item.

A result must be JSON-serializable to survive the sandbox boundary and the resume journal. A thunk that resolves to something that is not becomes null at its index.