Praecise Harness v1.1.0 Get started

Documentation · Building

Workflows

Steps run in order. Any {{name}} is replaced before the step runs, and can reference an input or an earlier step.

ts
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:

ts
{ 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.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.