workflow

Some jobs are one thing an agent does. Others have a shape: a decision, then several pieces built at once because they do not touch each other, then somebody looking at the result and saying whether it holds. Written as instructions, that shape becomes a list an agent has to carry in its head, and by the last step the first is gone. Written as a workflow, the shape is code — it runs in the engine, it decides its own phases and branches and fan-out, and nothing that answers it is told what comes next.

The shape on disk

<name>.workflow/
  workflow.js     the program — the primary file, and where all the decisions live
  workflow.yaml   what it is, when to reach for it, the phases it moves through
  README.md
  .metadata

The program

workflow.js is JavaScript, run in the engine. Six things are given to it:

phase(name)              name the stage the run is in
log(text)                say something as it goes
agent(prompt, opts)      ask for one agent's whole job; parks until answered
parallel(thunks)         several asks that do not depend on each other
pipeline(items, ...)     each item through every stage, independently
args                     whatever the run was started with

agent() is the only call that leaves the engine. It parks the run, puts the request where whoever holds credentials can see it, and resumes with the answer. Everything else — the loop that built those prompts, the branch on what came back, the decision to fan out — is the program's, and stays in the engine.

Running one

local run = asset.resolve("<name>", "workflow"):start({ ... })

or through the workflow toolbox, which is what an agent uses: workflow.start, then workflow.next / workflow.answer until it is finished. A run that is waiting announces itself on tool responses until it is answered.

What a run is

A run lives in the engine, not in a session. Whoever started it can close the tab, lose the connection or hand over to somebody else; the run stays parked exactly where it was, and the next agent to ask gets the request that was waiting. Each request is one subagent's whole job — the point is that no single context has to hold the entire run.