Workflows

A workflow in Sophon is a multi-step automation: a trigger plus a DAG of nodes that run when the trigger fires. You can draw workflows in the visual builder or describe them to the agent and have it generate one. Every workflow change is versioned, every agent-authored workflow needs your approval, and every run is tracked in the task ledger.

Workflows are different from plans. Plans are generated on the fly for a single request; workflows are saved, named, scheduled, and reusable.

Building a workflow

Open Workflows in the Dashboard. Click New to start from scratch, or pick a template.

In the builder:

1. Drop a trigger node (cron, webhook, channel message, email, file change, calendar, manual, agent request).
2. Drop action / logic / data nodes and wire them up.
3. Configure each node (parameters, credentials, output mapping).
4. Save. If any step is ≥ Medium risk, you'll be prompted to approve before activation.
5. Activate — the workflow is now live and will fire on its trigger.

Node types

Triggers

One trigger per workflow. Decides when it runs.

Actions

Do work.

• Run skill — invoke any tool from any enabled skill
• LLM prompt — send a templated prompt to a model (pick primary / fallback)
• Send message — deliver to any connected channel
• Execute code — Python or C# in the sandbox (gVisor-isolated)
• API call — HTTP request with headers, body, query params
• Create / update file — write to ~/.sophon/ or a mounted document store
• Database query — read / write against a configured SQL connection

Logic

Control flow.

• If / else — branch on an expression
• Switch — multi-way branch
• Loop — iterate over an array, batch, or range
• Wait — pause for a duration or until an expression is true
• Parallel — run branches concurrently, merge results
• Error handler — catch node failures and route to a recovery branch

Data

Shape values between nodes.

• Transform — JSONPath / JMESPath-style projection
• Filter — drop items matching a predicate
• Aggregate — count, sum, group-by
• Set variable — bind a value to $vars.<name> for the rest of the run

Approval

Human-in-the-loop.

• Approval gate — pauses and requests user approval; routes to approve / reject branches. See Approval Gates.
• Info request — asks the user a question and binds the answer to a variable, optionally with predefined choices.

Sub-workflow

A node that invokes another workflow. Inputs become the child's $vars; the child's output becomes the node's output. Good for reusable building blocks.

Expressions

Anywhere a node accepts a value, you can use mustache-style expressions to reference data from prior nodes or workflow variables:

{{ $node["FetchOrders"].output.items }}
{{ $node["LookupUser"].output.email }}
{{ $vars.threshold }}
{{ $trigger.body.userId }}

Supported forms:

• {{ $node["<id>"].output.<path> }} — reference another node's output
• {{ $vars.<name> }} — reference a workflow variable
• {{ $trigger.<path> }} — reference the trigger payload (webhook body, message text, etc.)
• {{ $env.<name> }} — environment variable (sandbox-scoped, not host)
• Arithmetic and comparison in If nodes: {{ $vars.count > 10 }}, {{ $node["n1"].output.status == "ok" }}

Complex JavaScript is not supported — keep logic in Execute code nodes if you need it.

AI-authored workflows

Ask the agent to build one:

"Create a workflow that checks my Gmail every morning at 8, summarizes any emails from my manager, and sends the summary to Telegram."

The agent:

1. Generates the workflow JSON.
2. Shows you an Approval dialog with a plain-language summary, the node count, estimated risk, and required credentials.
3. You can Approve, Edit in Builder (opens the builder with the generated JSON pre-loaded), or Cancel.
4. On approval, the workflow is saved and activated.

Every AI-authored workflow is gated this way — the agent cannot silently create running automations.

Execution

When a trigger fires:

1. The workflow engine resolves parameters and expressions against the trigger payload.
2. Nodes execute in topological order; independent branches run in parallel (Task.WhenAll).
3. Each node's output is captured and made available to downstream nodes.
4. Failures route to error-handler branches if defined; otherwise the run fails.
5. A run row is written to the task ledger with status, duration, and per-node outcomes.

Open Workflows → Runs to see execution history. Each run is drillable — you can see every node's inputs, outputs, timing, and errors.

Live debug

While a workflow runs in the builder, you can watch it step through in real time — each node highlights as it executes, and you can inspect data flowing through edges.

Versioning

Every save creates a new version. Older versions stay queryable; you can:

• View a diff between two versions
• Roll back to a previous version (one click)
• Fork an old version into a new workflow

Shared workflows (Pro / Enterprise)

Team members in the same tenant can share workflows. Sharing exposes the definition, not the credentials — each member uses their own connected services. A shared workflow shows an owner and a list of collaborators in the Dashboard.

Templates

The Dashboard ships with a template library. Pick one, tweak it, activate. Current templates include:

• Morning briefing — calendar + weather + news + top emails
• Email digest — daily summary of important inbox items
• Data pipeline — ETL between two services
• Approval flow — multi-step chain with escalation

Managing workflows

From agent tools:

workflow.list           # enumerate workflows
workflow.describe       # details of one workflow
workflow.create         # create (triggers approval dialog)
workflow.edit           # modify (triggers approval if risk changes)
workflow.trigger        # run a manual / agent-triggered workflow
workflow.pause          # stop responding to triggers
workflow.resume         # re-enable
workflow.clone          # duplicate as a new workflow
workflow.delete         # remove (needs approval)

From the CLI:

sophon workflows list
sophon workflows describe <id>
sophon workflows trigger <id>
sophon workflows pause <id>
sophon workflows history <id>
sophon workflows export <id> > backup.json
sophon workflows import < backup.json

Limits and gotchas

• DAGs must be acyclic — the builder validates on save and refuses cycles.
• Expressions don't support arbitrary JavaScript; drop into an Execute code node for complex logic.
• A workflow can call a sub-workflow, but sub-workflow depth is capped at 5.
• Workflow credentials are referenced by connection ID, not embedded — changing a credential doesn't require re-approving the workflow.
• AI-authored workflows always go through the approval gate, even if you trust the agent.

Where to go next

• Workflow JSON Reference — full schema
• Approval Gates — what triggers approval on creation or execution
• Skills — tools you can call from workflow nodes
• Connections — configure the services workflows call