Workflows

A workflow is a saved, versioned plan an agent runs — ordered steps with typed inputs. Reach for one when you want repeatable, defined behavior instead of an open-ended agent loop.

Workflows and actions

• Actions are either built-in (provided, global, read-only) or your own (org-authored).
• A step calls an action, calls an LLM, or emits a result.

Versions and aliases

Saving is immutable — editing a workflow (or action) creates a new version (a content hash). A movable alias points at one version:

pr-review                      ← workflow id
  ├─ <hash-a>  v1 (frozen)
  └─ <hash-b>  v2 (frozen)  ◄── @latest   (alias moves; versions never change)

• @latest auto-advances on each save; pin your own (e.g. @stable) with workflows_aliases_set.
• A run captures the exact version it used, so it's reproducible even after you edit the plan.

How a workflow runs

Two ways to trigger one — both enqueue a run that the agent's runner executes:

routing rule (targets a workflow) ─┐
                                    ├─► queued run ─► agent runs the steps
agent calls workflows_dispatch ────┘

• Routing — a routing rule targets a workflowId + alias and maps fields from the broker event into the workflow's inputs (JSONPath). A match enqueues the run.
• Agent — a connected agent calls workflows_dispatch (e.g. pr-review@latest + inputs). It's fire-and-forget: you get a run id back, not the result.

Tools

workflows_save · workflows_get · workflows_list · workflows_dispatch · workflows_aliases_set
actions_save   · actions_get   · actions_list   · actions_aliases_set