River
Ctrl K
Open River

Automation

Automation Mental Model

River has multiple automation surfaces. They're easy to confuse. This page is a fast way to pick the right one.

The four levels#

Manual    → SpaceChat (or doing it by hand)
Skill     → A single AI move, called by other things
Agent     → A persistent worker with judgment
Workflow  → A deterministic graph

The right tool is almost always the smallest one that solves your problem.

Use SpaceChat when#

  • The task is one-off
  • You want to think out loud and act in the same place
  • You haven't done it enough times to know if it'll repeat
  • You want to learn whether River can do something at all

The default. If you're not sure, start here.

Use a Skill when#

  • You catch yourself writing the same prompt fragment in multiple Agents
  • A task always returns the same shape (a label, a score, structured fields)
  • Several Agents need to share the same AI move

A Skill is a single, focused LLM call with structured output. It's the smallest reusable unit of AI work.

Use an Agent when#

  • You've done the task three times in SpaceChat
  • It's worth running automatically, on a trigger or schedule
  • The task needs judgment — what to prioritize, what to surface, what tone to use
  • You want a persistent worker your team can rely on

An Agent is a named specialist that runs over time, can adapt to what it finds, and improves with the persona you give it. Most of the autonomous work in River happens in Agents.

Use a Workflow when#

  • The process must run the same way every time
  • There are clear branches and explicit conditions
  • A human approval is required somewhere mid-flow
  • You need it to be inspectable / auditable
  • Compliance, finance, or ops cares about the result

A Workflow is a visual graph of nodes — deterministic, predictable, transparent.

A practical decision flowchart#

Is this happening once? → SpaceChat

Is it a single AI move I'd call from many places? → Skill

Does it need judgment, but no auditable predictability? → Agent

Does it need branches, approvals, and exact repeatability? → Workflow

Should an Agent / Workflow run on a clock? → Add a Schedule

Composing them#

The four don't compete. They compose:

  • A Workflow can run an Agent as one of its nodes (run_agent).
  • An Agent can call Skills as tools.
  • An Agent can be invoked by a Workflow's approval gate.
  • A Schedule can fire an Agent, a Workflow, or a Skill.
  • SpaceChat can build Agents and Workflows for you in plain language.

Promotion rule#

The rule we use:

Start in SpaceChat. Promote to an Agent on the third repetition. Promote to a Workflow only when correctness matters more than craft.

Don't over-engineer too early. A flat manual process plus selective Agents covers 80% of teams.

Tips#

  • Skills and Workflows are easy to under-use. If your Agents share patterns, extract Skills. If something must be auditable, build a Workflow.
  • Workflows that have one node are sometimes really just a Skill. Workflows that have only LLM nodes are sometimes really just an Agent.
  • Don't be precious about it. Migrate between levels as the work changes.