Workflows

Workflows model repeatable execution as graphs. They are useful when a process needs explicit steps, branching, retries, tool calls, approvals, or deterministic orchestration around an agent.

When to use workflows

Use workflows for support-ticket triage, document processing, evaluation pipelines, approval paths, structured extraction, or any process where the control flow should be visible and versioned. If the logic is "the model decides everything", use an agent; if humans need to see and approve the shape of the process, use a workflow.

How workflows execute

Workflow definitions are graphs of typed nodes: model calls, tool calls, retrieval, transforms, conditions, and loops. A tool node whose tool requires approval stops the run until the request is decided.
Node types are extensible — plugins can export new workflow node types into the node registry.
Each node execution emits a run step with status, timings, metrics, and bounded summaries; metered nodes write cost entries.
Agents can invoke workflows as child runs, and the parent run links to them, so a support-ticket answer shows the triage workflow it triggered.
Failures preserve completed node evidence; retries append new steps rather than rewriting history.

Approvals in workflows

When a tool node's tool requires approval, the run stops in waiting_approval before the tool is called. Once the request is decided, the run continues on the server as the member who started it: an approved call runs once, and a rejected, canceled, or expired one fails the node as APPROVAL_REJECTED without calling the tool, outside the node's retry policy. Resuming by hand (POST /api/v1/workflows/{workflow_id}/runs/{run_id}/resume) follows the same rules and answers 409 while the request is pending or once the run is already resuming.

Version and release lifecycle

Workflows follow the same immutable-versioning rules as agents:

Editing creates a new workflow.v1 version; the head pointer advances.
Publishing promotes an existing version to live and writes a release record (GET /api/v1/workflows/{workflow_id}/releases).
Formal execution resolves the published version only; drafts run through explicit preview.
Rollback moves the live pointer with provenance.

How workflows connect

Workflow nodes call Models, Knowledge, and governed tools from Plugins.
Agents invoke workflows as child runs.
Execution lands in Tasks and Runs like every other execution mode.
Evaluation can target workflow paths for regression gates.

API and UI surfaces

API prefix: /api/v1/workflows (definitions, versions, releases, execution)
Runtime prefixes: /api/v1/tasks, /api/v1/runs
Web route: /workflow (DAG design surface)