Workflows Operations
Definitions
Section titled “Definitions”Workflow definitions are loaded per tenant. GET /workflow/config returns what is currently
loaded — worth checking after a deploy, since a definition that failed to load produces no
error at start time, only a failure when something tries to use it.
Execution
Section titled “Execution”Instances execute on a pool of connected agents. Steps carry error handling and retry policy, so a transient failure in one step does not discard the instance’s accumulated state — the step retries, and the instance continues.
That is the important difference from a job: a failed step in a workflow does not mean starting over.
Failure modes
Section titled “Failure modes”An instance is stuck. Usually it is waiting for a signal that nobody sent. Check
/admin/instances for wait state and age before assuming a defect.
A step keeps retrying. A flaky integration inside an otherwise healthy process. The instance is fine; the dependency is not.
Queue depth grows. Not enough agents for the instance start rate.
A definition change lands mid-flight. Running instances continue on the definition they started with. Plan version transitions rather than assuming a deploy migrates in-flight work.
Choosing between the process blocks
Section titled “Choosing between the process blocks”| Use | When |
|---|---|
| Jobs | Fire-and-finish background work, on a schedule or trigger |
| Workflows | Business processes that suspend, wait for humans, and resume |
| Data Pipes | Moving and transforming data in bulk |
| AI Flow | Task DAGs including model calls; harnesses for agentic loops |
What to watch
Section titled “What to watch”| Signal | Why it matters |
|---|---|
| Instances in wait state, by age | Approvals nobody is actioning |
| Queue depth | Not enough agents for the instance rate |
| Cancelled vs completed ratio | Processes users abandon partway |
| Step retry rate | A flaky dependency inside a healthy process |
| Definitions loaded | A failed load is silent until something needs it |
Wait-state age is the signal with business meaning rather than technical meaning. A rising median means your approvers are the bottleneck, which is a staffing answer, not an engineering one.