Workflows
A workflow orchestrates multiple agents, conditions, and human checkpoints into a repeatable graph you can run on demand or on a schedule. This page covers the builder and its node types, the node limit, scheduling in plain language, runs, blocking handoffs, and how data moves between steps.
What a workflow is
Where chat is conversational and good for up to a few steps, a workflow is a defined pipeline you build once and reuse. It's a graph of nodes connected by edges; when you run it, AlphaAgent executes the nodes in order, branching and pausing as your design dictates. Workflows are versioned — each save creates a new version, and you activate a version to make it the one used by Run Now and any schedules.
Building a workflow
Open the builder from Create Workflow (or by converting a Deep Traversal plan from chat, which deep-links into the builder). The builder is a visual canvas where you add nodes and connect them. Each edge has an inline control to delete it.
[Screenshot: Workflow builder canvas]
Node types
| Node | What it does |
|---|---|
| Task | Runs an agent against a natural-language objective |
| Document analysis | A task that also takes uploaded documents as input |
| Conditional | Evaluates a condition and branches to different downstream nodes |
| Handoff | Pauses the run for a human to respond before continuing |
Task node. Pick an agent, write a plain-language objective and a description of the expected output, mark it as the entry point if it starts the workflow, and set a per-node timeout and retry count. Optionally switch the output from free-form text to structured JSON validated against a JSON Schema, which you edit in a built-in editor with formatting and inline validation.
Document analysis node. A task variant with a file uploader. Files are uploaded when you configure the node and attached as inputs. The same attachment limits as chat apply (5 documents at 4.5 MB each, 20 images at 3.75 MB each), checked as you upload.
Conditional node. Write a condition description and choose an evaluator agent, then map outcomes to downstream branches. As you pick a downstream node, the canvas spotlights the candidate so you can see where the branch leads.
Handoff node. Configures a blocking checkpoint — a handoff type (Approve, Stop Gate, Guidance, or Review), plus the email subject and body that notify the person who needs to respond.
The node limit
A workflow can have at most 12 nodes, counting every node type. Every "add node" control disables once you reach the cap. (At runtime, a workflow can execute up to 100 node steps in total, because conditional branches can revisit nodes in a loop.)
Saving
Before saving, the builder checks that every conditional has a condition description and evaluator and that every handoff is configured, flagging anything missing with a specific message. Saving publishes a new workflow version.
Running a workflow
Open a workflow to see its detail screen, with a versions table, a schedules panel, and the runs for this workflow. Click Run Now to start a run immediately and jump to it.
A workflow can also be started automatically by a connector trigger.
Scheduling in plain language
To run a workflow on a schedule, open Run on Schedule and describe the schedule in plain language, such as "every weekday at 9am." AlphaAgent translates that into a schedule expression (a cron expression) and shows a human-readable summary. You can edit the expression directly before saving if you want precise control. Once saved, the workflow runs automatically on that schedule.
Schedules appear in the schedules panel, where you can enable, disable, or delete each one.
[Screenshot: Schedule a run from a natural-language description]
Run detail
A run's detail screen shows:
- The run's status and a link back to the workflow.
- The workflow graph as it actually ran — runs render the version they executed, so editing the workflow later never changes how past runs are shown.
- A card per node with the agent, status, duration, the node's output, and any workspace files it produced.
Run detail does not live-stream; use Refresh to update an in-progress run. You can also download a run's artifacts.
Blocking handoffs
When a run reaches a handoff node it pauses with status waiting for handoff, and a response form appears on the run detail screen. Choose an action — Approve by default, or provide guidance (which requires you to enter guidance text), or review — and submit. The run resumes from where it paused.
How data moves between steps
Each node runs with its own workspace, so files don't automatically carry from one node to the next. Two mechanisms move data forward:
- Workspace files flow end-to-end. Files produced by earlier nodes are carried through the run, and when the same file path appears in multiple nodes, the latest node's version wins.
- Datasets are loaded on demand. When a node needs a dataset that an earlier node produced, the data is loaded into that node's workspace from shared storage. See Datasets and data flow.
Related pages
- Agents — the agents that power task nodes.
- Chat — convert a Deep Traversal plan into a workflow.
- Data connectors — trigger a workflow from a data condition.