Workflows

Unlike a free-form agent conversation, you decide the path. Most routing is deterministic — If / Else, Switch and Loop steps evaluate expressions, with no model involved. Where you do want a model to choose, an Evaluator step picks among routes you define.

The screens, step by step: Workflows, in the Guides.

Core concepts

Shared state

Every run has a shared state — a key-value store that passes through all steps. Each step reads the values it needs from state (its input keys) and writes its result back (its output key). A run starts with the text it was given stored as both user_input and user_query.

Initial state: { "user_input": "What is SynapseOrch?", "user_query": "What is SynapseOrch?" }

Step 1 — Research Agent
  reads:  ["user_input"]
  writes: "research_output"

Step 2 — Writer Agent
  reads:  ["research_output"]
  writes: "article"

Final state: { "user_input": "...", "user_query": "...", "research_output": "...", "article": "..." }

This explicit data contract makes workflows easy to debug — the Run Log and the run's record show what each step received and produced.

State schema

State Schema, in the canvas's Workflow settings, declares the keys the workflow uses. Each key has a type — Text, Whole number, Decimal, True or false, List or Object — an optional default and a description.

• Defaults are written to state when a run starts.
• Types are applied to what steps write. Most steps write text, so after each step the text in a typed key is parsed: JSON text becomes a list or an object, "42" becomes a number. If it will not convert, the text is kept and the Run Log shows a warning — or, with Stop on a state type mismatch on (Guardrails, in Workflow settings), the run stops.

The schema does not generate a form: a run from the canvas starts from a single line of input text.

Step types

SynapseOrch has 18 step types. Add step, in the canvas's dock, lists them all; here they are grouped by what each is for:

Each is described in detail in Step Types.

Guardrails

Guardrails bound what a run can consume. Configure them under Guardrails in the canvas's Workflow settings.

Max Total Turns (default 100) — how many steps the run may execute, counting each time a step runs. Steps run inside a Loop or Parallel step are not counted separately; their container is. When the limit is hit, the run fails.

Timeout (minutes) (default 30, or SYNAPSE_ORCH_GLOBAL_TIMEOUT_MINUTES) — the time the run spends working. Waiting for a person is not counted, and a Replay starts the count again. It is checked between steps; a step that runs a workflow, and a Loop or Parallel step, is also stopped when the run's time runs out, while any other step already running is bounded by its own step timeout.

Stop on a state type mismatch — stop the run when a step's text will not convert to the type its state key declares. Off by default. See State schema.

Result — the state key that holds what the run made: its answer in Chat and over the API, what a calling workflow's step receives, and what a judge scores. The default, Last step that produces content, takes the last step's output — a person's answer, an Evaluator's label and an End never count.

Score runs against — a rubric to judge every finished run with a model call. See Evals.

Each step also has its own guardrails — max turns, timeout and max iterations. See Step Types.

Execution model

A run starts at the step marked as the entry point. Each step runs, reads from and writes to state, and routing picks the next step. The run ends when:

• it reaches an End step, a step with no next step, or a route whose target is End workflow — completed
• a step times out or fails, a nested workflow fails (the calling step fails with its reason), a step gives up at its Max iterations, a Switch matches nothing and has no default, or a guardrail is hit — failed
• someone cancels it — cancelled
• a Human step, or an agent's tool call that needs approval, waits for a person — paused until answered

A run reads running while a nested run it started is working, also after an answer. A nested run whose calling run stops ends the same way — failed or cancelled — saying so. A run that did not complete carries an error saying why: the step that failed and its reason, the time budget, the turn limit, a step that does not exist, a restart of the server, or the run that called it stopping.

The run's step history records each step's name, type, status, start and end time, duration, output key and any error. Token usage and cost are on Usage, and each step's full input and output in Runs & Logs.

Triggers

Workflows can be started several ways.

From the canvas — click Run now in the bar at the top; the arrow beside it takes an input for the run. A run uses the last saved version, and won't start while the workflow has validation errors.

On SynapseOrch Cloud, Run on the Workflows list, for a workflow that declares an input or has an Agent step, asks first: Tell it what to work on. Its steps read this as the goal of the run. The Message box must be filled before Run starts it — without one, the run would choose its own subject.

Through the API — POST /api/v1/orchestrations/{orch_id}/run. With scale mode, /api/v2 queues runs for workers instead.

From Chat — an Orchestrator agent runs its workflow when you message it, in Chat, through the chat API or on a messaging channel, and when an agent schedule targets it. See Agent Types.

From another workflow — an Agent step whose agent is an Orchestrator agent runs that workflow as a nested run. Nested runs are listed under the run that started them (Nested runs in its run log), not in the runs list; their cost counts in that run's; the calling run's timeout or cancel stops them too; and a nested run is replayed through the run that called it. See the Agent step.

On a schedule — at an interval or on a cron schedule. See Scheduling.

Synapse AI

Don't want to build the workflow by hand? Click Build with AI in the Workflows header, or Synapse AI in the menu, from any page. Describe the workflow in plain text and the builder plans it, creates the agents it needs and saves the workflow, which you can then refine on the canvas.

See Synapse AI for the full walkthrough.