Workflows

A Workflow is a visual graph of nodes executed in a fixed order. Unlike Agents, Workflows produce the same output for the same input — they are predictable, auditable, and inspectable.

Use Workflows when a process has clear branches, explicit approvals, and must work the same way every time it runs.

Workflow vs. Agent — the key distinction#

A good rule: if a regulator, finance team, or auditor would care about the result, you probably want a Workflow. If you want craft, judgment, or voice, you want an Agent.

You can mix them: a Workflow can run an Agent as one of its nodes. An Agent can trigger a Workflow as one of its tools.

Where you build them#

Open Automations → Workflows to launch the WorkflowCanvas — a multiplayer ReactFlow canvas backed by a Y.Doc. Multiple users (and the AI) can design the same Workflow simultaneously, in real time.

Drag nodes from the palette, connect them with wires, configure each node's inputs, and run.

How a Workflow runs#

1. A trigger fires (manual, schedule, webhook, or event).
2. River starts a workflow.run Job.
3. Nodes execute in topological order; each one produces typed output.
4. Branches (if, switch, filter_items) route data through the right path.
5. Approval gates (wait_for_approval) pause until a human acts.
6. Outputs are written back as entities and the Job completes.

You can watch a run live, replay a past run with the same inputs, or fork a Workflow to test changes without touching the production version.

When to use a Workflow#

Reach for a Workflow when:

• The process has explicit branches and conditions
• A human approval is required somewhere mid-flow
• You need deterministic behavior every run
• The result is auditable (compliance, finance, ops)
• The process integrates 3+ external services in a fixed order

When all of that is true, a Workflow is the right tool. When it isn't — when judgment matters more than predictability — use an Agent.

What's inside a Workflow#

13 built-in node types span four categories. See Node Types for the full reference.

• Trigger — manual_trigger, schedule_trigger, webhook_trigger
• Data & Control — http_request, set_fields, filter_items, if_condition, switch
• River-native — tool_call (any River tool), run_agent
• Human-in-the-Loop — wait_for_approval
• LLM-in-the-Loop — llm_router, llm_transform

Examples#

• New customer onboarding — Stripe webhook → set fields → create Contact → create welcome Doc → send email → wait for first reply → notify owner.
• Contract review — file upload → PDF extract → LLM router (length, type) → human approval gate → write approved Contract entity → notify legal.
• Refund decision — support ticket → llm_router (small / medium / large) → small auto-approves; large pauses for manager approval.

Tips#

• Build the happy path first. Add branches and approvals only when the simple version works.
• Use set_fields early in the graph to canonicalize inputs — it makes everything downstream easier to debug.
• Approval gates are great for high-trust automation: the AI proposes, the human confirms.
• AI agents can build Workflows for you with the workflow_create, workflow_node_add, and workflow_connect tools — describe what you want and let River wire it up.