A workflow run is the runtime counterpart of the canvas design: it takes a versioned graph, walks it node by node, dispatches tasks to agents, and drives execution from the start node to a terminal state. Each run is observable, budget-bounded, and recoverable — you can watch it progress, pause or cancel it mid-flight, and retry it if something goes wrong.
From trigger to start node
A run begins when a trigger fires — a cron schedule, an incoming signed webhook, or an internal platform event. When you start a run manually from the editor, you can also supply an initial input payload and an optional budget cap for that specific run before it launches.
At start time, the platform creates a run record and dispatches the first agent task from the start node of the workflow graph. Everything that happens after that is driven by the execution engine: as each task completes, it reads the graph, evaluates any outgoing condition edges, and dispatches the appropriate successor nodes.
You can also request a cost forecast before starting. The forecast gives you a confidence-rated estimate of expected spend based on the agents and connections in the graph, so you can set an informed budget cap rather than guessing. The broader strategy for controlling agent spend is covered in budgets and quotas: preventing runaway agent costs.
Graph traversal: how execution moves through nodes
The execution engine traverses the workflow graph outward from the start node. When an agent task finishes, the engine examines the outgoing edges from that node and determines which successors are ready to run.
Condition nodes are evaluated at traversal time. Each condition compares values in the accumulated run context — data collected across all completed nodes — against a configured expression. Supported operators include equality, inequality, numeric comparisons, substring containment, and existence checks. Only the branch whose condition evaluates true is followed; the others are pruned.
Each node's output is merged into a shared run context that accumulates as execution progresses. Successor nodes can reference values from earlier nodes through this context, which is how agents in a chain can act on each other's results without manual wiring.
Per-run budget caps and auto-pause
Every run tracks its actual spend in real time as agent tasks complete and costs are attributed. If a run was started with a budget cap, the engine checks spend against that cap after each task. When actual spend reaches the limit, the run transitions to a paused state.
A paused run does not lose its state. The accumulated context and the position in the graph are preserved. You can review what ran, how much was spent, and then decide whether to cancel the run or resume it — either as-is or after adjusting the workflow for efficiency.
This budget gate is per-run, not per-workflow. A single workflow definition can be run with different caps depending on context: a test invocation with a tight limit, a production run with a higher allowance. The cap travels with the run record, not the template.
Human-in-the-loop approval nodes
Approval nodes are first-class participants in the execution graph. When traversal reaches an approval node, the engine creates an approval record and suspends that branch. The run status does not change to failed — it waits. For guidance on when and how to design these gates, see human-in-the-loop approvals for high-risk agent actions.
A designated approver sees the pending approval in the platform, along with the context accumulated up to that point. They can approve, which releases the branch and continues execution from that node, or reject, which marks the branch as failed and terminates downstream nodes on that path.
Approvals have configurable timeouts. If no decision is made within the timeout window, the engine treats the branch as rejected and continues accordingly. This prevents approval nodes from leaving runs suspended indefinitely when approvers are unavailable.
Observing a run in progress
Each run exposes its current state through a dedicated API endpoint. The run record includes status, the current context JSON, per-node task references, actual spend to date, and the auto-pause flag. The editor surfaces this as a live view: you can see which nodes have completed, which are in progress, and which are pending.
Real-time updates are pushed to connected clients as each node completes or the run status changes, so the run view in the editor updates without you having to refresh or poll manually.
The run history for a workflow is also queryable: you can list all runs for a workflow, filter by status, and inspect any historical run's final context and spend. This makes post-incident investigation straightforward — pick the run, read the context, see exactly what each agent received and produced. For a broader look at observability across your AI estate, see observability for AI agents: logs, metrics, and traces.
Cancelling and retrying runs
You can cancel a run that is in a running or paused state. Cancellation stops further node dispatch and records a terminal status on the run. In-flight agent tasks that were already dispatched complete normally, but no new successors are triggered after the cancel signal is processed.
Failed and cancelled runs can be retried. A retry creates a new run record using the same initial input that was supplied when the original run started. The new run begins from the start node, so it traverses the full graph fresh rather than resuming from the point of failure. This makes retry behaviour predictable: the graph does not need to handle partial-state recovery, and you always get a complete execution record for the retried run. For how workflow versioning and rollback interact with run history, see Versioning and Rollback for AI Agents.
Praesidia's run management endpoints cover the full lifecycle: start, list, get, cancel, retry, and approval actions. All of them are organization-scoped and require the appropriate role, so the same access controls that govern who can author a workflow also govern who can trigger and manage its runs.
Common questions
What happens to a paused run if I do not resume it? A paused run stays in a paused state indefinitely until you take action. No further nodes are dispatched and no additional spend accrues. You can inspect the run, cancel it, or — if the workflow was adjusted to be more efficient — start a fresh run instead. The paused run's context and history remain available for reference.
Can I give different runs of the same workflow different budget limits? Yes. The budget cap is supplied at run start time, not stored on the workflow definition itself. This lets you run the same workflow with a conservative cap in a test environment and a larger one in production, or vary the cap based on the importance of a particular invocation.
How do I know which node caused a run to fail? The run record includes task references for each dispatched node. When a task fails, its status is reflected in the run record and the run transitions to a failed state. Inspecting the run via the API or the editor's run view shows which node's task encountered the error, giving you a starting point for diagnosis without trawling through unstructured logs.
Putting it together
Execution and observability are two sides of the same capability. A workflow run that you cannot watch is a black box; a run you can watch but not control is a liability. The combination — durable graph traversal, real-time status, per-run budget caps, approval gates, and a clean cancel-and-retry model — gives your team a runtime environment you can operate with confidence.
See designing AI workflows on a visual canvas to understand how the canvas design feeds into execution, triggering workflows: scheduled, webhook, and event for the full trigger reference, or advanced analytics for AI operations to understand how run data feeds into longer-term operational reporting.