The workflow tool

DataMind Oda can run a written plan that spreads many small tasks across helper agents: a workflow. The tool behind it takes a JavaScript script, runs it, and returns the script's final value to the chat. Oda uses it only when you explicitly ask for a workflow or for large multi-agent orchestration.

What the workflow tool does

One script, many helpers. Oda writes a small JavaScript script; the script starts the helper agents that do the work, coordinates them, and the run hands the script's final value back to the chat.
Only on an explicit ask. The tool is reserved for an explicit workflow or large-orchestration request, such as an audit over many files, a migration or multi-angle research. For one or two delegations, Oda uses plain helper calls (Delegating work to subagents).
A card in the chat. A call appears as a card titled workflow: <name>, named from the call's meta block (Tool calls in the chat).
A companion loop. A separate tool runs fixed fresh-agent iteration loops, the Ralph tool; it is covered on The Ralph tool.

The call's fields

Field	What it carries
`script`	The script body: plain JavaScript, not TypeScript. Top-level `await` is allowed, and the body ends with `return` of the value to hand back.
`meta`	The run's identity: its name and description, plus optional `whenToUse` and `phases` (described below).
`args`	Optional input for the script, as plain JSON data; the script reads it as `args`.
`run_in_background`	Optional. Starts the run as a background job and answers with a job id at once, instead of holding the turn until the script finishes.

The script and its hooks

The script coordinates; the helpers do the work. The tool hands the script a small set of hooks and nothing else: no filesystem, network, timer or Node.js APIs are provided.

agent(prompt, options?) starts one helper and resolves with its result.
parallel(thunks) runs zero-argument functions together and collects their results.
pipeline(items, ...stages) runs each item through its stages independently, with no barrier between items.
phase(title) opens a progress phase; log(message) writes a progress note.
args reads the call's input.

const summaries = await parallel([
  () => agent('Summarise report A'),
  () => agent('Summarise report B'),
]);
return { summaries };

An ordinary failure becomes null. A helper that fails for its own reasons resolves null, and a stage that throws drops its item to null; the script decides what to do next.
Misused hooks are fatal. Bad arguments, unknown options, an unsupported schema or a tripped cap always kill the script; they never dissolve into a per-item null.
Helper options are a closed set. agent() accepts a label, a phase, a schema for a structured result (within a supported subset of schemas), and provider and model overrides. Options outside the set are refused, and the message names the supported ones.

The meta block

name and description are required. The name is short and kebab-case and titles the call's card; the description says what the run does.
whenToUse (optional) tells the model when this kind of run fits.
phases (optional) names the progress stages, each with a title and optionally a detail, provider and model. Phases label progress only; they say nothing about how the run executes.
The set is closed. A field outside it is refused and named, and all violations are reported in one message; nothing is accepted and ignored.
The block is data. It rides the call's meta field and reaches the run as plain data, never as code; the script body carries code only.

Follow and stop a run

A foreground run holds the turn. The call returns when the whole script finishes; the chat shows the card while it works.
A background run becomes a job. With run_in_background, the call is accepted at once with a job id, and the run registers as a job of the chat. While it runs, the job streams its phases and one line for each helper start or end.
Early reads are status only. Before the run settles, a read of the job reports its status; the return value arrives when the run settles. Background runs and jobs covers the job list, its lines and the stop controls.
In the app. The run appears in Activity as a Workflow row whose member lines are its helper agents; a failed run waits with Review until it is opened (Activity rows and actions).
Stopping. Stop the run's job from the chat, or ask Oda to stop it; a foreground run stops with the turn's Stop (Stopping Oda and queued messages). A stopped run ends as cancelled.
Background runs can be switched off. Where that is the case, the run_in_background field is not offered, and a call that still asks for one is refused with run_in_background is disabled for this tool. A background run also needs the app's jobs surface; without it, the call is refused, saying background jobs are unavailable.

How a run ends

A run settles once: it completes, is cancelled, or fails.

Completed. The call returns workflow "<name>" completed (<n> agents)., then Return value: and the script's value. The count is how many helper calls the run started.
Cancelled. The call comes back as an error: Error: workflow run was cancelled, with the cancellation reason included when one was given.
Failed. The call comes back as Error: workflow run failed: followed by the failure, or unknown error when nothing was captured.
Long results are truncated. If the result text runs past its cap (50,000 characters by default), it is cut and the notice says how many characters were omitted.
No partial success. A run that does not complete is an error result; whatever it produced on the way is never reported as a success. A script that does not parse, an opening slice that times out, and a value that is not plain JSON each fail the run; the failures that end a run, and their messages, are on Workflow runs: limits and failures.

The environment a script runs in

The calling chat's file policy applies. Read Only stops file changes; Workspace Write keeps changes inside the workspace; Full access applies no file limits (Permission presets).
The script's environment is empty. It sees no credentials, no proxy settings and no other machine environment.
Network access is not restricted by the file policy.
The sandbox is not a security boundary. It governs the files a run may change; it is not a guarantee of isolation.

Behind the tool

Checked before it exists. A start carries the script, the meta block and the args; the meta block and the script are validated first, so a run that fails its checks never starts.
Runs are holder-owned. Once accepted, a run lives on even if the engine is unloaded; unloading only prevents new runs from starting. Disposing a run waits for the script and its helpers to finish.
Events are observe-only. A run publishes its start, its phases and log lines, each helper starting and ending, and one end event when the result settles. Watchers get identity snapshots, never the live run, and a watcher that fails is logged without affecting the run or the others. The end event fires exactly once and carries no result value.
Calls are ordinary calls. A call made from inside a program still goes through the same checks, approvals and recording as a direct call, and follows the same rules for calls that run together.
The name. The tool is registered under its name; where a deployment registers a different one, the model's guidance and the card title follow it.

Questions, answered

How do I start a workflow?

Ask Oda in your own words for a workflow, or for large multi-agent orchestration such as an audit over many files, a migration or multi-angle research. Oda writes the script and calls the tool, and the call appears as a card titled workflow: <name>. For one or two delegations Oda uses plain helper calls instead; see Delegating work to subagents.

What is a workflow script written in?

Plain JavaScript, not TypeScript. It can wait at the top level and ends with return; it coordinates with the hooks (agent(), parallel(), pipeline(), phase(), log()) while the helpers do the work. The tool provides no filesystem, network, timer or Node.js APIs of its own.

Which fields does the `meta` block accept?

name (short kebab-case) and description are required, and whenToUse and phases are optional. A field outside the set is refused and named. The block is data: it travels in the call's meta field, never in the script.

Which options does an `agent()` call take?

label (the name shown for the call in progress lines), phase, schema (for a structured result, within a supported subset of schemas), and provider and model overrides. Anything outside the set is refused, and the message names the supported options.

What happens while a workflow runs in the background?

The call is accepted at once with a job id, and the run registers as a job of the chat. The job streams the run's phases and one line for each helper start or end; before the run settles, a read reports its status only, and the return value arrives when it settles. See Background runs and jobs.

How do I stop a running workflow?

Stop the run's job from the chat, or ask Oda to stop it; a foreground run stops with the turn's Stop (Stopping Oda and queued messages). A stopped run ends as cancelled, and nothing it produced is reported as success.

What does a finished run return?

workflow "<name>" completed (<n> agents). followed by Return value: and the script's value. The count is how many helper calls the run started. If the text runs longer than its cap (50,000 characters by default), it is truncated and the notice says how much was omitted.

Why does the workflow tool not offer `run_in_background`?

Background runs can be switched off for the tool. The field is then not offered on calls, and a call that still asks for one is refused with run_in_background is disabled for this tool. A background run also needs the app's jobs surface; without it, the call is refused, saying background jobs are unavailable.

Can a workflow change my files or read my credentials?

The script's environment is empty: no credentials, no proxy settings and no other machine environment reach it. File changes follow the calling chat's policy: Read Only stops them, Workspace Write keeps them inside the workspace, and Full access applies no file limits (Permission presets). Network access is not restricted by that policy.