Workflows

Workflows (/app/workflows) cover two models in one sidebar entry: (1) legacy linked-agent workflow records with a React Flow orchestration canvas, and (2) workflow chains — lightweight primitive-based orchestrations edited at /app/workflows/chains/{slug}/edit. Sidebar badge counts both. Nothing is auto-seeded.

Landing page

• Orchestrations header with primitives legend (trigger, assistant, agent, decide, webhook, schedule, notify, human).
• chain them! design cue for composing chains.
• Chain cards — GET /v1/workflow-chains: status, summary, when_label, primary_steps preview, branch previews, run stats.
• Legacy workflow cards — open full workflow shell with flow canvas.
• New chain — POST /v1/workflow-chains and open the primitive form editor.
• New graph workflow — dialog creates a legacy React Flow orchestration (PUT graph after create).

Access control

Workflow APIs use capability-based RBAC (mapped to workspace roles). Chain and graph routes no longer rely on coarse role checks alone.

Workflow chains

Chains are edited in a dedicated form editor (not the React Flow canvas). PATCH /v1/workflow-chains/{slug} persists all fields. Run history is available per chain via GET /v1/workflow-chains/{slug}/runs and GET .../runs/{run_id}.

Chain primitives

• trigger — entry condition label
• assistant — invoke a published Assistant by label/slug match
• agent — invoke an AI Agent (playground runtime) by label
• decide — branch on a condition label (substring match on running output)
• webhook — outbound HTTP POST (url, secret, retries in step config); secret also used for inbound HMAC verification
• human — pauses run as awaiting_human until POST .../runs/{run_id}/resume
• schedule — records deferred-execution intent (external scheduler)
• notify — email via Resend/SMTP/console to email_to in config

Chain run & ingress

• POST /v1/workflow-chains/{slug}/run — studio test run (runtime.simulate, rate-limited)
• POST /v1/workflow-chains/{slug}/runs/{run_id}/resume — continue awaiting_human runs
• POST /v1/workflow-chains/{slug}/ingress — authenticated inbound webhook (HMAC + runtime.simulate)
• POST /v1/public/workflow-chains/{workspace_slug}/{chain_slug}/ingress — public inbound webhook (HMAC only, no cookie)
• Sign the raw JSON body with HMAC-SHA256 using the webhook step config.secret; send header X-Chain-Signature (hex or sha256=<hex>). Body: {"message": "..."}.

Legacy workflow graph

Opening a workflow at /app/workflows/{id} shows the workflow shell rail. The Flow tab is a React Flow canvas. Draft graphs are saved with PUT /v1/workflows/{id}/graph (creates a new draft version). Publishing promotes the latest draft to a live version.

Workflow shell rail

Publish & versions

• POST /v1/workflows/{id}/validate-publish — schema + runtime publish rules (Studio calls this before Publish)
• POST /v1/workflows/{id}/publish — promotes latest draft (workflow.publish)
• GET /v1/workflows/{id}/versions — list versions with limit/offset
• POST /v1/workflows/{id}/versions/{version_id}/restore — copy an older graph into a new draft
• Blocked node types at publish: script, datastore, set, human, parallel, wait
• Router/decision nodes must have at least one outgoing edge with condition.expr

Rate limits

Workspace Agent ops setting rpm_cap_per_agent applies per workflow id and per chain id for simulator starts, workflow turns, and chain run/resume/ingress (Redis-backed when Redis is available; 0 = unlimited). Additional slowapi limits apply on graph save, publish, restore, and chain endpoints.

Workflow vs single Assistant

API (summary)

# Workflow chains
GET/POST              /v1/workflow-chains
GET/PATCH/DELETE      /v1/workflow-chains/{slug}
POST                  /v1/workflow-chains/{slug}/run
GET                   /v1/workflow-chains/{slug}/runs
GET                   /v1/workflow-chains/{slug}/runs/{run_id}
POST                  /v1/workflow-chains/{slug}/runs/{run_id}/resume
POST                  /v1/workflow-chains/{slug}/ingress
POST                  /v1/public/workflow-chains/{workspace_slug}/{chain_slug}/ingress

# Legacy graph workflows
GET/POST              /v1/workflows
GET/PATCH/DELETE      /v1/workflows/{id}
PUT                   /v1/workflows/{id}/graph
POST                  /v1/workflows/{id}/validate-publish
POST                  /v1/workflows/{id}/publish
GET                   /v1/workflows/{id}/versions
POST                  /v1/workflows/{id}/versions/{version_id}/restore

# Workflow simulator & history
POST                  /v1/runtime/workflows/{id}/sessions
POST                  /v1/runtime/workflows/sessions/{session_id}/turns
GET                   /v1/runtime/workflows/{id}/sessions?limit=&offset=

See Workflow canvas and Chain editor pages for node types, edge routing, and simulator behavior. Public workflow channel traffic uses deployment tokens via /v1/public/runtime/* (see Channels & deploy).