SDK reference

A workflow program imports everything from @boardwalk-labs/workflow (MIT, source). These hooks are facades over the engine running the program, so the same imports work identically under boardwalk dev, self-hosting, and Boardwalk. The package also exports the TypeScript types (WorkflowMeta, AgentOptions, …) and the manifest schema for tooling.

agent()

function agent<T = string>(prompt: string, opts?: AgentOptions): Promise<T>

Runs one model call to completion. Without a schema it resolves to the final text; with one, to a validated object (pass the type: agent<Bug[]>(prompt, { schema })).

interface AgentOptions {
  model?: string;      // omit → the managed Auto lane; or a "<vendor>/<model>" id
  provider?: string;   // default "boardwalk" (managed); name your own for BYO keys
  schema?: JsonSchema; // JSON Schema → structured, validated output
  name?: string;       // a label for this agent in the run log
  tools?: string[];    // built-in tool names this agent may call
}

Model and provider are chosen per call; the workflow declares none. See Inference.

input, output, config

const input: unknown                         // the trigger payload (a value, not a function)
const config: Readonly<Record<string, JsonValue>>  // deploy-time configuration
function output(value: JsonValue): void      // declare the run's result

input is whatever started the run (a webhook body, --input, or a workflows.call argument). output()sets the run's result: what the dashboard, notifications, and a calling parent receive (last call wins). config is a frozen object supplied at deploy time.

secrets.get()

function secrets.get(name: string): Promise<string>

Resolves a secret to its plaintext value, fail-closed against permissions.secrets. The value is redacted from everything the model sees. See Secrets.

sleep()

function sleep(arg: number | { durationMs: number } | { until: string | Date }): Promise<void>

Holds the run; a bare number is milliseconds. It really waits: locals survive and the process simply holds its machine until it wakes. No checkpoint or replay to reason about.

workflows.call() / run()

function workflows.call(slug: string, input: unknown, opts?: CallOptions): Promise<unknown>
function workflows.run(slug: string, input: unknown, opts?: CallOptions): Promise<string>

call starts another workflow as a durable child run, holds for it, and resolves to its output. runis fire-and-forget and resolves to the new run's id. Both are idempotent on (parent, target, input), so a restarted parent re-attaches instead of double-firing.

parallel()

function parallel<T>(thunks: readonly (() => Promise<T>)[]): Promise<T[]>

Runs thunks concurrently and resolves to their results in order: a barrier with standard Promise.all semantics (rejects on the first throw). Pass () => agent(...) thunks to fan a batch of model calls out at once.

phase()

function phase(name: string, opts?: { id?: string }): void

Marks the current section of the run for the live tail and run log. Observability only; it does not checkpoint or skip code on restart.

artifacts.write()

function artifacts.write(
  name: string,
  contentType: string,
  body: string | Uint8Array,
  metadata?: Record<string, unknown>,
): Promise<{ id: string; name: string; url: string }>

Stores a file with the run and resolves to a download URL. Use it for outputs you want to keep and link to: a report, a generated image, a diff.