Workflows

What is a workflow?

A workflow is a server-side function that orchestrates one or more agent runs and the human steps between them. The runtime persists every checkpoint to durable storage, so the workflow’s identity (its inputs, its retrieval context, its decisions so far) is recoverable across restarts. A 24-hour approval window does not require keeping a process alive — the workflow halts at the checkpoint and resumes when the approval lands.

When to use a workflow

• The job spans multiple agent runs that share state.
• A step waits on a human (approval, scheduled review, manual data entry).
• A step waits on an external event (a webhook, a billing cycle, a cron trigger).
• You need exactly-once semantics for an external write under retries.
• The job needs to survive deploys and crashes without losing position.

Authoring a workflow

Workflows are TypeScript functions that yield to the runtime between steps. The runtime captures every yielded operation as a checkpoint, replays the function from the top on resume, and short-circuits any step whose result is already recorded.

// src/workflows/onboard-customer.ts
import { defineWorkflow, runAgent, awaitApproval } from "@/lib/workflows";

export const onboardCustomer = defineWorkflow({
  name: "onboard.customer",
  input: { customer_id: "string" },
  body: async (ctx) => {
    const research = await runAgent(ctx, "researcher", {
      customer_id: ctx.input.customer_id,
    });

    const approved = await awaitApproval(ctx, {
      summary: research.summary,
      hash: research.payload_sha256,
    });
    if (!approved) return { status: "halted" };

    return runAgent(ctx, "outreach", {
      customer_id: ctx.input.customer_id,
      brief: research.brief,
    });
  },
});

How operators run them

Operators trigger workflows from /dashboard/workflows or by calling the API. Each running workflow shows its live timeline — checkpoint by checkpoint, with the same drill-downs you see on a regular agent run. From the timeline page, an operator can:

• Pause a workflow that is waiting on a slow external dependency.
• Resume a workflow that was halted, optionally overriding the next checkpoint.
• Re-run a single step from a recorded snapshot for incident triage.
• Replay the entire workflow against the same inputs in a sandbox.

Idempotency and retries

External writes from a workflow carry a workflow-scoped idempotency key derived from the step name and the workflow run id. Retries — including retries that span a deploy or a process crash — produce at most one external mutation per logical step. See /docs/run-replay for how the replay sandbox handles idempotency keys at debug time.