Workflows
Steps run in order. Any {{name}} is replaced before the step runs, and can
reference an input or an earlier step.
import { workflow } from "@praecise/harness";
export default workflow({
input: { message: "the customer's message" },
steps: [
{ id: "sorted", ask: "{{message}}", agent: "triage" },
{
id: "reply",
when: "{{sorted.category}}",
is: {
refund: [
{ id: "draft", ask: "Draft a refund reply: {{message}}", agent: "support" },
{ id: "approved", approve: "Send this?\n\n{{reply.draft}}" },
],
},
otherwise: [{ id: "draft", ask: "Reply to: {{message}}", agent: "support" }],
},
],
});Eight kinds of step:
ask |
delegate to an agent |
use |
call a service, e.g. use: "ledger.create_invoice" |
approve |
stop and wait for a human |
wait |
stop and wait for an event from outside |
each |
run steps once per item, optionally in parallel |
when |
branch on a value |
repeat |
run steps until a check holds, with a required max |
plan |
let a model lay out the remaining work, then run it as a graph |
An approve step writes the run to disk and returns. It survives a restart, and
resuming replays the recorded outputs rather than re-running the steps before
it — the model is not called twice for work already done.
A wait step stops the same way, for an event instead of a person:
{ id: "paid", wait: "com.acme.payment.received", subject: "{{order}}", timeout: 86400, onTimeout: "continue" }wait is the CloudEvent type awaited. source and subject narrow it, which
is how a run waits for its own event and not the next one of that type. The
event that matches continues the run, once, and is the step's output: type,
source, id, subject, time, data and timedOut. It arrives through
app.signal(event), app.deliver(workflow, event), app.publish(event) or the
event routes. An event that arrives while nothing waits for it is not
kept. timeout is in seconds; running out fails the run, or with
onTimeout: "continue" carries on with { timedOut: true }. A timeout fires
only while a process holds the app, or when app.expire() is called: nothing
wakes a run whose app is not running. A run waits for one event at a time.
A string that is only a reference keeps its type, so with: "{{draft}}" hands
a tool an object rather than [object Object].
Any step may carry after: ["id", ...]. One after anywhere turns the list into a
graph: steps run as soon as what they wait for is done, so independent work goes in
parallel instead of in the order it happened to be written. Without any after, the
steps run in order, which is what a short workflow wants.
Two things about after that are easy to read the wrong way, because both are about
where a step SITS rather than what it says:
A step inside each, when or repeat may wait for a step outside it, and usually
means to. If the block it sits in already waits for that step, the dependency is
satisfied before the block begins — naming it again is redundant rather than wrong,
and nothing is lost. What is reported is the other case: a wait on something nobody
waits for, where the two really could run in either order.
A repeat condition may name the steps inside its own body. until: "{{panel.passed}}"
over a body containing panel is the ordinary way to write "go round again until the
panel agrees", and it works because the condition is evaluated after the body has run.
max is required on repeat because an unbounded loop is a bug, so there is no way
to write one. And a plan is produced once rather than on every step — deciding what
to do next is itself a model call, and paying for it repeatedly is what makes agentic
loops expensive. The plan is recorded as a version rather than overwritten, so a
resume runs the graph that was agreed rather than inventing a fresh one.