Skip to content
Registry

workflow

v0.1.2

Deterministic, crash-resumable multi-agent workflow orchestrator over harness turns.

license: Apache-2.0automationdurablemulti-agentorchestrationworkflow

Install

bash
iii trigger compose::add worker=workflow@0.1.2

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions10

workflow::inject-guidance

Function

Internal pre_generate hook: appends workflow orchestration guidance to the agent system prompt. Bound to harness::hook::pre-generate at worker startup; not called directly.

Request
  • generateobject
    • system_promptstring

      The system prompt assembled so far (base + any prior hook's mutation).

Response
  • mutationsobjectrequired

    The harness applies `system_prompt` only when the key is present (`HookRunner`'s `parse_mutations`), so `None` serializes to an empty object: the safe no-op that preserves the harness's assembled prompt.

    • system_promptstring

      Full replacement system prompt (base + appended guidance). The harness overwrites, it does not merge.

workflow::node-result

Function

Fetch the stored JSON result of one node: `node_uid` is the node id, or '{node_id}#{i}' for a fanout item (workflow::status lists them under `node_results`). Returns {result: null} when nothing is stored.

Request
  • node_uidstringrequired

    The node id, or `"{node_id}#{i}"` for a fanout item (the keys of `workflow::status`'s `node_results`); `uid` is accepted as an alias.

  • run_idstringrequired

    The `run_id` returned by `workflow::start`.

Response
  • resultunknown

    The node's stored JSON result, or null if the node has not completed (or produced no stored result). Always serialized — even when absent it is an explicit `{ "result": null }`, so callers never special-case a missing key.

workflow::on-config-change

Function

Internal: hot-reload workflow config — re-binds the cron sweep on a sweep_expression change and swaps the per-call tuning snapshot otherwise.

Request
  • idstring

    Configuration id that changed.

Response
  • okbooleanrequired

workflow::stamp-reply

Function

Internal pre_trigger hook on workflow::start: stamps the caller's session (and, for `reply_to`, model/provider/policy) into the arguments. Always continues; not called directly.

Request
  • callany of
    any of (2)
    Variant 1
    • argumentsunknown
    • idstring
    Variant 2
    valuenull
  • functionsunknown

    Caller turn's dispatch policy, captured into the stamped `reply_to` so the reply can wake the caller with its own reach.

  • modelstring
  • providerstring
  • session_idstring
  • turn_idstring
Response
  • decisionstringrequired

    Always `"continue"` — this hook never denies or holds a call.

  • mutationsany of
    any of (2)
    Variant 1
    • argumentsunknownrequired

      The call's arguments with the caller identity stamped in.

    Variant 2
    valuenull

workflow::start

Function

Launch a declarative multi-agent DAG (fan-out, barrier/join, durable and crash-resumable) and return its run_id immediately. To get the result set `reply_to: {}` (or `notify`) and END YOUR TURN — it arrives as a separate message when the run finishes; never poll workflow::status in a loop.

Request
  • caller_session_idstring

    Orchestrator session, stamped by the `workflow::stamp-reply` hook from the caller's turn; never trusted from the agent.

  • definitionall ofrequired

    The workflow DAG to run (`workflow` is accepted as an alias key).

    all of (1)
    Variant 1
    • default_functionsunknown

      Dispatch policy inherited by every node that omits `agent.functions` (same shape); when unset those nodes get `["*"]`, everything.

    • nodesobjectrequired

      Nodes keyed by node id; an id must not contain `#`, `.`, or `/`, and the `depends_on` graph must be acyclic.

    • outputall ofrequired

      Which node's result the whole run returns.

      Show 1 nested
      all of (1)
      Variant 1
      • fromstringrequired

        `"node:<id>"` of an existing node; for a fanout group the result is the array of its children's results, in order.

    • versioninteger· uint32min 0

      Schema version; only `1` is supported.

  • idempotency_keystring

    Dedupe key; a repeated key returns the original `run_id` instead of launching a duplicate run.

  • inputunknown

    Any JSON value; read by nodes whose `input.from` is `"run_input"`.

  • notifyany of

    Completion callback triggered once when the run reaches a terminal state, instead of polling `workflow::status`.

    any of (2)
    Variant 1
    • function_idstringrequired

      Function id to trigger on terminal state, e.g. `"myworker::wf-done"`.

    • queuestring

      Queue for durable delivery; defaults to `"default"`.

    Variant 2
    valuenull
  • reply_toany of

    Deliver the outcome into your session as a new message: send `{}` (optionally `template`), then end your turn — it arrives when the run finishes.

    any of (2)
    Variant 1
    • functionsunknown

      Caller turn's dispatch policy (`{allow, deny}`), auto-stamped so the reply can wake an idle caller with its original reach.

    • modelstring

      Model for the reply turn; auto-stamped from the caller's turn.

    • providerstring

      Provider override; auto-stamped from the caller's turn.

    • session_idstring

      Target session; auto-stamped from the caller's turn.

    • templatestring

      Text prepended to the formatted outcome.

    Variant 2
    valuenull
Response
  • run_idstringrequired

workflow::status

Function

Return a snapshot of a workflow run (status, per-node state, node_errors, node_results, result, result_error), or null if not found. Each call costs a turn: do not poll in a loop; pass `reply_to`/`notify` to workflow::start to be pushed the outcome.

Request
  • run_idstringrequired

    The `run_id` returned by `workflow::start`.

Response
any of (2)
Variant 1
  • node_errorsobject

    Errors for nodes that failed, keyed by node uid — e.g. "no provider registered for model …". Present so a caller can diagnose a `failed` run without digging into stored state. Omitted when no node carries an error.

  • node_resultsobject

    Nodes that have a stored result: node uid → result_ref (its key in state). Fetch the value with `workflow::node-result { run_id, node_uid }`. Lets a caller recover partial work from a run that failed partway (the run-level `result` is only set on a Completed run). Omitted when empty.

  • nodesobjectrequired

    Per-node state keyed by node uid.

  • resultunknown
  • result_errorstring

    Run-level failure summary (set when `status == failed`).

  • run_idstringrequired
  • statusstringrequiredenum running, awaiting_nodes, completed, failed, cancelled
Variant 2
valuenull

workflow::stop

Function

Cooperatively cancel a workflow run and cascade harness::stop to each live node session.

Request
  • run_idstringrequired
Response
  • stoppingbooleanrequired

workflow::sweep

Function

Internal cron sweep: reconcile AwaitingNodes runs and time out nodes past their deadline. Not called directly.

Request
  • scheduled_atinteger· int64
Response
  • okbooleanrequired
  • sweptinteger· uint64requiredmin 0

    Number of runs touched (reconciled and/or timed out) this sweep.

workflow::tick

Function

Internal durable workflow step.

Request
  • run_idstringrequired
  • stepinteger· uint64min 0
Response
  • skippedbooleanrequired

workflow::wake

Function

Internal: on a harness turn-completed event, wake the owning run with a tick. Best-effort latency optimization; the cron sweep is the durable backstop. Not called directly.

Request
  • session_idstring
Response
  • wokebooleanrequired

Triggers0

No triggers registered

Search the registry

Find workers, kits and executables, or jump to a page.