Steps & Gates

Every workflow is built from two building blocks: steps (the work that gets done) and gates (the checkpoints that control flow). This guide covers all available step types, gate configurations, and how steps connect to each other through transitions.

Step types

Each step in a workflow has a type that determines its behaviour. Choose the type that matches what you need the step to do.

Action

Action steps are the most common type. An assigned agent performs a task based on the instructions you provide.

When to use: Any time you need an agent to do something — send an email, look up data, draft a document, update a record.

Configuration:

• Agent — Select which agent handles this step. You can assign a specific agent, or resolve one at runtime by tag or by company role.
• Instructions — Tell the agent exactly what to do. Be specific and include any context the agent needs.
• Gate — Choose what happens after the step completes (auto, review, approval, or decision)
• Timeout (optional) — How long the step may run before timing out, in minutes. Default 15, maximum 60.
• Output schema (optional) — Declare the exact shape of the data this step should produce. Downstream steps can rely on typed fields instead of parsing free-text output. See Typed outputs below.

Example: “Using the Gmail integration, send a welcome email to the new employee. Include the start date and office address from the workflow input.”

Condition

Condition steps add if/else branching logic. The workflow evaluates a condition and follows one of two paths depending on the result.

When to use: When the next step depends on the outcome of a previous step. For example, “If the refund amount is over $500, route to the senior manager for approval. Otherwise, auto-approve.”

Configuration:

• Condition — A field, an operator, and a value. The field is a dot-path into the execution context: outputs of earlier steps live under the step’s ID (for example classify.score), and the trigger payload lives under trigger. (for example trigger.amount).
• Operator — One of: equals, not equal, contains, greater than, greater or equal, less than, less or equal, exists, or a regular-expression match.
• If true — The step to run when the condition is met
• If false — The step to run when the condition is not met

Example: A condition step after an order lookup that checks whether the order is within the return window. If yes, proceed to the refund step. If no, send a polite decline message.

Fork

Fork steps split the workflow into parallel branches. Each branch is an independent path of steps, and the workflow does not continue past the branches until every one of them has finished.

When to use: When you have independent tasks that do not depend on each other. For example, during employee onboarding you might want to create an email account, order a laptop, and schedule orientation as separate branches.

Configuration:

• Branches — Define two or more outgoing transitions, one per branch. Each branch contains one or more steps and runs down to the workflow’s join step.

Example: Fork into three branches: (1) IT agent creates email account, (2) Procurement agent orders equipment, (3) HR agent schedules orientation meeting.

Join

Join steps merge parallel branches back into a single path. The workflow waits until all incoming branches have completed before moving forward.

When to use: After a fork step, when you need all parallel tasks to finish before proceeding. For example, wait for all onboarding tasks to complete before sending the final confirmation email to the new hire.

Configuration: A join step has no configuration of its own — it is a marker that collects every branch of the preceding fork. Every fork must have a matching join (validation enforces this), and the join always waits for all branches.

Example: After the onboarding fork, a join step waits for IT setup, equipment order, and orientation scheduling to all finish, then triggers a final notification.

Pipe

Pipe steps move data from a source to a destination — optionally through a transform — with no AI involved. They run deterministically, so they are ideal for bulk data movement where you do not want an agent interpreting anything.

When to use: Syncing records from an integration into a search index, pushing data to an external API, or importing data on a schedule.

Configuration:

• Source — Where the data comes from: a connected integration, a Sprigr search index, or a raw HTTP endpoint.
• Transform (optional) — A JavaScript or Python code snippet that reshapes the data between source and destination.
• Destination — Where the data goes: a Sprigr search index, website data, an integration, or a raw HTTP endpoint.

Example: Every night, pull the day’s jobs from your job management system (source), map them to a slim summary shape (transform), and write them into a Sprigr index your agents search at answer time (destination).

Code

Code steps run a JavaScript function in a sandbox, deterministically and without a model call — the step costs nothing in AI usage and always behaves the same way for the same input.

When to use: Calculations, data validation, calling tools with exact arguments, or any logic that must be exact rather than interpreted by an agent. Scripts created in the code-first Scripts editor are workflows with a single code step — they run through the same engine, triggers, versioning, and gates.

Configuration:

• Code — An async JavaScript function body. It reads earlier step outputs and the trigger payload from the execution context, can call the assigned agent’s tools, and finishes by completing (or failing) the step with typed outputs.
• Agent — The step still needs an assigned agent: the code runs inside that agent’s tool context, so it can only use tools and integrations that agent has.

Example: A code step that takes the quote total from an earlier step, applies the correct tax rate, and emits { total_inc_tax, tax_amount } for the invoice step to use.

Gate types

Gates sit between steps and control the transition from one step to the next. Every action and code step carries a gate that determines what happens around it; when you do not set one, the gate is auto.

Auto

Auto gates let the workflow continue immediately. No human interaction is needed.

When to use: For steps where you trust the agent’s output and do not need anyone to check it before moving on. Most internal data-gathering and notification steps use auto gates.

Behaviour: As soon as the step completes successfully, the workflow automatically advances to the next step.

Review

Review gates pause the workflow so a team member can inspect the agent’s work before it continues.

When to use: When you want a quality check but do not need formal approval. For example, reviewing a drafted email before it gets sent, or checking data accuracy before it is used in the next step.

Behaviour:

1. The step completes and the workflow pauses
2. A notification is sent to the designated reviewer
3. The reviewer sees the step’s output and the surrounding context
4. The reviewer clicks Approve to advance the workflow, or Reject with a reason to stop it. A rejected execution can be retried later.

Notifications: Reviewers receive a notification in the portal and on their connected channels (for example Slack or WhatsApp).

Approval

Approval gates require explicit sign-off from an authorised person before the workflow can proceed.

When to use: For steps with real business impact — financial decisions, publishing content, granting access, or any action that cannot be easily undone.

Behaviour:

1. The step reaches the gate and the workflow pauses
2. A notification is sent to the designated approvers with full context (see Approval context below)
3. An approver reviews the context and clicks Approve or Reject (a rejection requires a reason)
4. If approved, the workflow continues to the next step
5. If rejected, the step and the execution are marked rejected (not failed) and the execution ends. The rejection reason is recorded, and the execution can be retried later if circumstances change.

Who can approve: A gate can name a specific agent, an agent resolved by tag, a company role, specific users, or the members of a team. These stack — whoever acts first resolves the gate.

Approval tracking: Every decision is logged with the acting user, timestamp, and the reason they provided. This creates an audit trail for compliance purposes.

Decision

Decision gates present the approver with a set of named options instead of a binary approve/reject. Each option routes the workflow down a different transition.

When to use: When a person needs to choose between multiple outcomes — “Route to senior tech / Schedule for tomorrow / Mark as non-urgent” — and the choice determines what happens next.

Configuration:

• Options — Two or more named choices. The options are the step’s labelled transitions — each option maps to one transition. Validation blocks a decision gate with fewer than two options.
• Option descriptions (optional) — A short explanation shown next to each option, so the decision-maker understands what each choice leads to.
• Justification template (optional) — Template text rendered with data from prior steps, shown as the headline on the decision card.

Behaviour: The approver sees a card with the options, their descriptions, and a summary of the prior step output. Picking an option advances the workflow down the matching transition.

Example: A triage step presents options: “Emergency dispatch” (routes to on-call technician), “Standard booking” (routes to scheduler), “Customer follow-up” (routes to support agent).

Gate timing — before vs after step execution

Every approval, review, and decision gate has a gateTiming setting that controls when the gate pauses the workflow relative to the step body:

• gateTiming: "after" (default) — The step runs first, then the gate pauses with the step’s output for review. Use this for triage, after-the-fact review, or when the work itself is safe and you only need a quality check on the result.
• gateTiming: "before" — The gate pauses before the step body runs. If the gate rejects, the step body never executes. Use this for any step with real side-effects — sending an email, charging a card, writing to simPRO/Xero, creating a job — so that a rejection truly prevents the action.

Use `before` for side-effect steps

If your step creates, updates, or sends anything to an external system, set gateTiming: "before" on its gate. Otherwise a rejection happens after the side-effect has already landed, which can be hard or impossible to undo.

Decision gates also support gateTiming: "before" to act as pure routers — the step body is skipped (the step is marked skipped in the execution) and the workflow simply takes the transition matching the picked option.

Approval context

When an approval, review, or decision gate triggers, Sprigr Teams builds a rich context bundle that is shown to the approver across every channel (portal, Slack, WhatsApp, web push). The context includes:

• Justification — A headline explaining why the approval is needed, built from a template you configure with values from prior steps.
• Prior-step summary — A short summary of what the previous step did and what it produced.
• Context fields — Up to six key fields distilled from earlier step outputs (for example: customer name, order total, requested action).
• Decision options with descriptions — For decision gates, each option and its description.
• Transition hints — What happens next for each choice, so the approver knows the downstream consequence.
• Urgency badge and countdown — If the gate has expiresInMinutes set, a live countdown is shown so the approver knows the deadline.

Approvers can click through to the full approval card from notifications, which takes them directly to the step in the workflow detail view.

Tip

You can mix and match gate types within the same workflow. For example, use auto gates for data gathering steps, a review gate for the draft step, and an approval gate for the final “send to customer” step.

Transitions between steps

Transitions connect steps together and define the order of execution. By default, steps run in sequence from top to bottom. Every step’s output is stored in the execution context under the step’s ID, so agents and conditions downstream can reference earlier results.

When you create a workflow, sequential transitions are added automatically as you add steps; agents building workflows for you can also declare transitions explicitly. Each transition can carry a human-readable label, which is what decision gates present as options.

For condition steps, you define two transitions — one marked for the “true” path and one for the “false” path. For fork steps, you define one transition per branch. Join steps automatically collect all incoming branches and wait for them to complete.

Typed outputs

Action steps can declare an output schema — a typed contract for the data the step produces. Downstream steps then receive validated, typed fields instead of having to parse free-text agent output.

An output schema is a map of field name to type definition:

• Types: boolean, number, string, enum, array, object, or any
• Constraints: required, min / max / integer for numbers, pattern / minLength / maxLength for strings, values for enums, nested schemas for arrays and objects
• Example: a triage step might declare { urgency: { type: "enum", values: ["low", "medium", "high"] }, needs_dispatch: { type: "boolean" } }

When the step completes, Sprigr Teams validates the agent’s output against the schema. Validation behaviour is controlled by the workflow’s strictness setting:

• strict (the default for new workflows) — Reject any output that does not match the schema. The agent sees the validation error as a tool failure and retries with the correct shape. Catches silent bugs like string "true" flowing into a boolean field.
• lenient — Coerce obvious mistakes (for example, "3" becomes 3 for a number field) and log a warning. Hard violations — a missing required field or a value outside an enum — still fail the step.
• off (the default for workflows created before schemas existed) — Validation still runs and logs violations to the audit trail, but never blocks the step.

Use typed outputs on decision-driving steps

Any step whose output feeds a condition step or a downstream gate benefits from a typed schema. Without it, a stray quote or whitespace in the agent’s output can silently route the workflow down the wrong branch.

Best practices

• Keep steps focused — Each step should do one thing well. Instead of one giant step that does everything, break it into smaller, targeted steps. This makes workflows easier to debug and reuse.
• Use gates strategically — Auto gates keep things fast. Add review and approval gates only where the cost of an error justifies the delay.
• Name steps clearly — Use descriptive names like “Look up customer order” instead of “Step 1”. Clear names make the execution view much easier to follow.
• Provide detailed instructions — The more specific your step instructions, the better your agent performs. Include what data to use, what format to output, and what to do if something goes wrong.

Next steps

• Creating Workflows — Build a complete workflow from scratch.
• Workflow Execution — Monitor running workflows, handle failures, and review history.
• Workflows Overview — Return to the overview for a refresher on workflow concepts.