Skip to main content
This guide is for the operator authoring a workflow — picking the right node types, wiring typed I/O, choosing validation strategies, and setting capability hints. The thing you are filling in is a graph stored across workflowGraphNodes and workflowGraphEdges; the thing it becomes is a durable, auditable pipeline. This page is about authoring decisions. For the conversational AI authoring path, see Use the Workflow Architect — the right starting point for ~80% of new workflows. For the runtime semantics of nodes and edges, see the The workflow graph. For what happens after publish, see Workflow Execution.

The mental model — graph, not script

A workflow is a directed acyclic graph. Nodes do work; edges carry control and information. When a workflow runs, the durable orchestrator walks the graph, dispatches each ready node, advances when results land, and repeats until the graph is terminal. That’s the entire model. Workflows are how Forge turns “something we want done” into “something we can run, observe, and audit.” They replace ad-hoc scripts with a shape you can inspect, version, and hand off — rows in workflowGraphNodes and workflowGraphEdges keyed polymorphically to a workflowVersions row (published, immutable) or a workflowDrafts row (editable workspace). A run pins a specific versionId (or draftId for test runs) at launch and is frozen for the duration. Publishing a new version never affects in-flight runs. Rolling back is a republish.

Decide first: prescriptive or delegated?

Prescriptive runs walk the graph step by step. No LLM tokens spent on orchestration decisions — the DAG is the plan. Fully auditable, fully restartable, predictable cost. Use this when the process is well-understood, the handoffs are known, and compliance needs a reproducible trail. Most workflows are prescriptive. Delegated runs hand a goal and a bounded set of guardrails (cost cap, duration limit, handoff limit, approval gates) to an agent. The agent decides what to do within authority. Cheaper to set up; harder to audit step-by-step. Use this when adaptive reasoning matters more than a fixed sequence. Both run types share the workflowRuns table — same status machine, same observability, same cost attribution. They fill different fields. The rest of this guide is about prescriptive composition; for delegated runs, the authoring step is the agent definition plus the run-time guardrails, not the graph.

Pick node types

The whole vocabulary: Agent is the shared workflow node for AI and human work. In its properties, choose Assigned to → AI, Human, or Role. The existing API/storage discriminator remains produce; the resolved worker kind determines how the task executes. For each type’s full field surface, see The workflow graph.

A decision table for “which node?”


Wire typed I/O

Every non-terminal node declares inputs and outputs. Types: string, number, integer, boolean, object, array, date, month, file, string[], number[], file[].
  • Inputs wire from upstream: source: { nodeId, output } — pull from another node’s output. Or source: { workflowInput: "key" } — pull from the run’s runtime arguments. Or literal — a constant fixed at authoring time, which may embed {{workflow.<name>}} references.
  • Outputs are the node’s declared contract. Other nodes reference them by key.
  • Files flow as opaque fileId references. Bytes remain behind the Files-and-Bindings service; the bound reference moves between nodes.
A file or file[] output injects putFile at dispatch. The agent binds the file to the declared output key and returns its fileId, not raw content. Validation refuses unbound ids and raw bytes. See Files and bindings. Keys are stable contracts. Renaming an output without updating downstream wires breaks the graph; the validator catches it but the fix is the wire, not the validator.

Ask each question once

A workflow’s input contract has three kinds of entry. Only one of them is a question. The distinction matters because a flat contract quietly turns every encoding a node happens to need into a human question. A monthly close that genuinely decides one thing — which month — ends up asking for the month, its first day, its last day, a display label, and a fiscal-period token, then trusting the operator to keep all five consistent. Four of those are functions of the first. Declare the decision as a parameter and compute the rest:
The dispatch dialog now shows one month picker and a read-only expansion of everything computed from it. The run still persists all five keys, so nodes bind them exactly as before — a node cannot tell a computed value from a typed one, which is the point.

Expressions

Expressions are written in a small closed language: nine functions (startOfMonth, endOfMonth, previousMonth, nextMonth, addMonths, format, fiscalPeriod, fiscalYear, and today — the last available in default expressions only), no operators, no conditionals. It is deliberately not a general expression engine — the contract is meant to be auditable at a glance. Two contexts:
  • derived.expr sees run parameters only. It cannot call today() and cannot reference another derived field, so a replay of a run always computes the same answer it did the first time.
  • defaultExpr additionally sees today() and lastRun.<param>. This is what makes a recurring workflow schedulable with no stored arguments at all: the trigger stores nothing, and previousMonth(today()) fills the period at fire time.
Everything an expression can get wrong is caught when you save the draft — an unknown function, a parameter that does not exist, a return type that does not match the declared type, a format pattern typo, a fiscal calendar nobody configured. That timing is the feature. A close that fires unattended at 6am on the first should never be the thing that discovers a bad expression.

Fiscal calendars

fiscalPeriod(period, "outreach") reads a named calendar from Platform → Fiscal Calendars, which stores the month a fiscal year begins. With a February start, 2026-06 is period 5 of FY2026 (052026) and 2026-01 is period 12 of FY2025 (122025) — January precedes February, so it closes the prior fiscal year. fiscalYear(period, "outreach") returns that year on its own — "2026" for 2026-06, "2025" for 2026-01 — named for the calendar year in which the fiscal year started. It is the YYYY half of the PPYYYY token, exposed separately because the language has no operators and no substring function, so a value fused into a composite return is otherwise unreachable. Both take the calendar as a quoted name — a string literal, not a parameter reference — and an unknown name is rejected at publish. Both are available in derived.expr and defaultExpr. That rollback is the reason this is data rather than prose in an input’s description. It is easy to state, easy to misapply, and a wrong answer is a well-formed string that pulls the wrong GL month without failing anything. The authoring panel evaluates your expression against a sample as you type so you can see the actual token before publishing.

Assets — configuration that happens to be a file

Some inputs are files that change on their own schedule, not the run’s. An entity roster revised twice a year was, until assets existed, a mandatory upload on every single monthly close. That one fact made the workflow unschedulable and Slack launch impractical, because neither a cron nor a slash command can attach a file. Mark the input asset: true (file / file[] only) and bind it once:
The binding lives on the workflow. Every launch surface shows what is currently bound — intercompany_roster.csv · updated May 12 — and anyone with workflows:manage can replace it inline from the run dialog. Replacing it changes what every future run reads without republishing the contract, which is why it carries the same permission as editing the contract itself. Each launch snapshots the concrete file id into the run’s arguments, so “which roster did the June close use?” stays answerable from the June run whatever is bound today — and a Retry of that run reproduces the file it actually used. A required asset with nothing bound refuses the launch, before the run starts, naming the input. That is deliberate: a run that dies mid-flight on a missing file is the worse outcome.

Retry versus rerun

A run persists the concrete expansion, not the expressions. Retry replays those stored values verbatim, so retrying a June close next quarter still runs June — even if the fiscal calendar has been edited since. Rerun opens the dialog for editing and re-derives from whatever you set.

Reference a workflow input from inside a node

A node reads a launch argument two ways. Wiring an input with source: { workflowInput: "key" } hands that node a whole slot fed by the argument. Interpolation puts the value inside a string — a {{workflow.<name>}} reference the orchestrator substitutes at dispatch. The second form exists because a slot is not always available to write into. A procedure node’s input keys are fixed by its pinned manifest, so a per-run value that has to live inside a literal’s shape has nowhere else to go:
Without the reference, that graph is re-authored every month to change one string.

Three forms, two scopes

Node scope versus workflow scope is the distinction that matters. {{x}} and {{inputs.x}} are node-scoped: x must be a key in this node’s inputs, whatever that key is bound to. {{workflow.x}} skips the node entirely and reads the launch arguments, so it needs no inputs entry — but x must be declared on the workflow’s input contract. A publish message can therefore read a launch argument with no wire at all. "Weekly vendor digest for {{workflow.period}}:\n\n{{digestText}}" needs a binding for digestText and none for period. Only literal bindings are interpolated. A value arriving through source or workflowInput is passed through untouched even when it happens to contain {{…}} text, so run data can never rewrite itself. Object keys are never scanned either — only string values.

A whole-string reference keeps its type

Substitution has two modes, and the difference is the point. So a string[] workflow input can fill an array-typed procedure slot whole, and the same input can also be spliced into a label somewhere else in the shape.

An unresolvable reference throws in a literal and blanks in a prompt

The two surfaces fail differently, on purpose.
  • In a literal binding, a reference with no value at dispatch throws and fails the node, naming the input.
  • In an agent prompt or publish message, an unknown key renders as the empty string, so operators never see {{undefined}} in a published message.
memberIds: [""] is a syntactically valid reporting-API request that returns the wrong numbers — a failure nobody notices. A degraded prompt is recoverable. The literal path is the one worth stopping.

What the validator catches before publish

The optional-with-no-default case is the one WORKFLOW_REF_MISSING exists for, and it is rejected at publish time: the preflight wiring gate refuses a draft carrying any severity: "error" issue, and wiring errors are not overridable. Without that gate the graph would publish cleanly and then throw only on the runs where the operator left the field blank — passing its first test and failing in production. Give any interpolated input a value on every run — required, derived, or optional carrying a default / defaultExpr.
{{inputs.x}} and bare {{x}} are not supported inside a literal. A literal has no node-scoped resolver, so those strings are sent to the procedure verbatim; they only warn. If the value you want really is this node’s own input rather than a launch argument, bind it with source / workflowInput on its own input key instead of templating it.
There is no expression syntax inside a placeholder — a reference names a declared workflow input and nothing else. Compute the value with a derived entry on the input contract and reference the result.

Pick a validation strategy per Agent node

The single biggest correctness lever on a produce node is its validation field. Pick the weakest strategy that meets the correctness bar. Most pipelines end up with schema on most nodes and validated on the two or three nodes where semantic quality matters.

Let an agent correct a rejected output

validation.maxRetries sets how many times a producer whose output fails validation is asked to correct it. For a person, it re-opens the task. For an agent, it applies only when the workflow uses outcome routing (outcomesV1) and the node runs inline, not detached. The agent is re-prompted in the same conversation thread, inside the same run attempt, with the validation feedback as the next message. An agent is re-prompted at most 5 times per run attempt, even if maxRetries is higher. An agent is re-prompted only when its rejected turn is safe to repeat: the turn must not have called any tool. A turn that called a tool might have changed something outside the platform, so its rejected output fails the node immediately. When the re-prompts run out, the node fails with the validation detail, and its failure binding records retry: { tries, refusal: "attempts_exhausted" }. A detached agent’s rejected output always fails the node. Validation warns with INEFFECTIVE_AUTOMATED_RETRIES when maxRetries is set on a node that cannot use it.

Set capability hints — narrow, don’t sprawl

produce nodes whose worker is an agent can declare capabilityHints — the per-node lever that turns one agent definition into many personas:
At dispatch, the resolver intersects the agent definition’s permitted capabilities with the node’s hints. So adding a skill to a hint that isn’t in the agent’s permitted set produces a warning or failure depending on skillMode — hints narrow, they don’t expand. Capability-hint sprawl is the most common authoring mistake. Requesting every skill and tool set on every node burns prompt budget and weakens the agent’s focus. Request only what the node’s prompt actually uses. The Workflow Architect tends toward thoroughness — tighten before publishing.

Declare the runtime budget

Every agent-backed produce node carries a Timeout. It is not a defensive guardrail you set low. It is the control that decides where the turn executes, and it is the only such control. There is no placement toggle, no pin, and no prediction engine. Placement is a pure function of the number you type, resolved at dispatch and identical everywhere it is displayed. In the builder, the Timeout field is a duration control (value + min / h) with a live readout underneath — Runs inline or Runs in a detached VM (up to 24 h) — that updates as you type. Nobody thinks in milliseconds, and nobody should have to guess where a node will land. Both placements are the same turn: the same governance preflight, the same thread, the same cost attribution, the same streamed Session feed. The run view shows which one a step took; nothing else in the product behaves differently.

Size the node, then round up

Over-declaring is close to free; under-declaring is not. Three facts make “when in doubt, declare big” honest guidance rather than sloppiness:
  • A detached VM bills roughly memory while it sits waiting on model streams — pennies for a multi-hour budget.
  • A dead run is caught by a lease-bounded staleness backstop, not by the declared deadline. A 4-hour declaration whose VM died in minute one is reaped minutes later, not four hours later. Declaring big does not mean waiting big to find out something broke.
  • An under-declared node dies mid-turn and the work is discarded. There is no partial credit.
Rough arithmetic is enough — you are picking an order of magnitude, not forecasting:
A 782-item adjudication needs 40+ minutes on that arithmetic. If you estimate 25 minutes, declare an hour. Given two candidate numbers, take the larger one. The shape that needs this most is the bulk-judgment node: an array-typed input (a work list — candidates, transactions, findings, PRs) feeding a node that emits one structured result per item. One item is cheap; the node’s cost is items × per-item, and the operator’s brief usually names the work (“every ambiguous PR”) without naming the count. Ask for the count when it is implied but unstated. Fan-out and budget buy different things. Splitting a work list across N branches into a join buys latency; a larger timeout buys ceiling. Fan out when the operator needs the answer sooner. Raise the budget when the operator needs the whole list processed — fanning out to dodge a timeout adds a join, N sets of bindings, and N failure modes to solve what one field already solves.

What the platform tells you when the budget is wrong

  • AGENT_BUDGET_UNDERSIZED — an authoring-time warning (L3), raised on a tool-bearing produce node with declared outputs, an array-typed input, and an inline-sized timeout. It carries the sizing arithmetic and arrives as a one-click timeout fix chip in the builder’s issue rail and in the Architect’s fix-flow. It is advisory: since placement follows the declaration, there is no invalid combination to block — only an under-declaration to flag. It never blocks publish.
  • RAISE_TIMEOUT — a runtime failure, labeled Inline budget exhausted. Past ~80% of its inline budget with work outstanding, an inline turn gives up at the next tool-call boundary and names the node, its budget, and the fix, rather than burning the remaining minutes and dying as an opaque action-wall error. It is not retryable — a retry reproduces the same exhaustion. The fix is the Timeout field.
Long-running work needs an explicit notification design. Add a notify node or configure the relevant delivery surface when a person must learn that the run finished; do not assume every long run sends an automatic completion message. The Workflow Architect applies all of the above when it authors nodes for you — it recognizes the bulk-judgment shape, sizes it, quotes past runtime measurements for a node it has seen run before, and declares the budget rather than capping the work.

Wire edges that mean something

An edge from A to B means “when A finishes, consider traversing to B.” Three optional fields change the semantics: Multiple unconditioned edges from the same node fork — all fire in parallel. Multiple conditional edges all evaluate in parallel; every truthy condition fires (which is how you get conditional fan-out without a router). Error edges are mutually exclusive with success edges on the same source. Legacy workflows treat a handler whose only incoming edges are error edges as an entry node. It can dispatch before its source fails. The explicit outcome-routing contract below removes that behavior; existing workflows retain their runtime contract.

Author expected outcomes and technical failure paths

Keep expected business outcomes in the node’s structured outputs. For example, a Workday lookup can return a required string enum such as ready, person_missing, multiple_people, or phone_missing. Select that field under Outcome output, then mark the relevant values under Expected exceptions. Use ordinary conditional edges to send each value to its intended next node. Only ready should reach the SMS node. An authentication error or failed API request belongs on the technical failure path, rather than being reported as a missing person. With this contract, the existing Error Path edge connects a failed node to an ordinary handler node. A handler reached only by error edges waits for an actual failure. Add an object input on the handler and choose its Failure source under Failure input bindings. The binding carries structured failure information, including the originating run, node, attempt, category, code, message, retryability, and known external-effect state. It is separate from the source’s successful output bindings and cannot supply data from an unrelated failure. Validation checks the declared outcome field, enum members, failure-source reachability and error edges. Simple equality conditions can establish coverage of every enum member; more complex conditions may require your review of a coverage warning. A declared outcome with no selected route, an invalid router selection, or malformed condition fails visibly. An ordinary valid condition that evaluates false still skips its edge normally. Multiple matching ordinary paths all activate. Handlers use the same typed inputs, outputs and validation controls as other nodes. A handler’s successful completion records that the failure was handled; it does not erase the original technical failure or convert the run into an ordinary success. Error edges cannot feed a data join directly. Route them through an appropriate handler first. Routing a failure never repeats the failed node, and it never makes an uncertain external operation safe to repeat.

Retry a node automatically when it is safe

A Procedure node or an AI Agent node can declare a retryPolicy:
maxAttempts counts every try, including the first, and must be a whole number from 2 to 5. initialBackoffMs is the wait before the second try, a whole number from 1,000 to 300,000. Each later wait is multiplied by backoffMultiplier, from 1 to 4 (default 2). The waits together may not exceed 900,000 ms. With the example above, a node waits 5 s before its second try and 10 s before its third. The policy asks for more tries; the runtime decides whether to make them. A failed try is repeated only when all of these hold:
  • the workflow uses outcome routing (outcomesV1);
  • the failure is an execution, infrastructure or timeout failure, not an input, output, routing or governance failure;
  • the platform’s own dispatch evidence shows that no external operation took effect or could have taken effect. Only a read whose result is unknown is repeated after it started;
  • no tool-dispatch fence is set on the step.
A procedure’s idempotent flag, the effect state a sandbox reports, and a retryable hint never grant a try. In practice, a failure before the node’s first external call starts (for example, an unavailable sandbox) is retried. A call that started and then failed or timed out is not retried, because it may have written something. Route that failure to an error path instead. Every try runs inside the same run attempt. Each failed try is recorded and shown in the run’s event stream, and its token usage and cost are kept. When the tries run out, or the runtime refuses a try, the node fails through the normal failure path. Its failure binding carries retry: { tries, refusal }, for example { "tries": 3, "refusal": "attempts_exhausted" } or { "tries": 1, "refusal": "effect_unknown" }. Cancelling a run stops a try that is still waiting. Validation reports RETRY_POLICY_REQUIRES_OUTCOMES (a warning) when a workflow without outcome routing declares a policy, because legacy runs ignore it. It reports RETRY_POLICY_UNSUPPORTED_NODE (an error that blocks publish) for a policy on a Router, Join, Publish or Notify node, on an Agent node assigned to a person, or outside the bounds above. A person’s submission that fails validation is re-prompted through the node’s validation settings, not through retryPolicy.

Configure required outcome notifications

When Use outcome routing is selected, Workflow Settings also exposes Required outcome notifications. Every admitted run must have at least one authorized in-app recipient. A person who starts a run is included automatically; add one or more operators so scheduled and other automated runs have an accountable recipient. Expected exceptions and technical failures notify every configured operator. You can also stage required Slack workspace and channel targets, but production admission remains closed until the deployment completes qualification and the operational prerequisites in the outcome-recovery runbook. These receipts are delivery obligations, not advisory preferences. Muting personal notifications does not remove them. The runtime freezes the resolved recipients on each attempt, so later edits do not rewrite the evidence for an in-flight or historical run. An effective exception or failure and its obligations commit together; terminal outcomes create their own obligation, including success. A scheduled dispatcher, completed handler, or emitted event is not delivery proof—the obligation is satisfied only when its personal in-app receipt commits. Workflow completion arrives through a callback tied to the expected attempt and engine instance. A stale callback cannot finalize a newer attempt, and the watchdog uses the same terminal writer to recover a callback that never arrives. Delivery failures do not roll back the workflow outcome; safe in-app failures receive bounded retries, while revoked recipients and exhausted retries are held for operator attention. Required notifications are not evidence that business work failed or should be retried. A bell or Slack delivery problem keeps the original business verdict and is recovered through the notification controls. If an external effect is unknown, reconcile it before restart; do not use notification repair, rewind, or a new run to repeat the call. The outcomesV1 new-launch gate defaults closed; disabling it never blocks recovery for existing runs. sourceHandle and targetHandle identifiers exist for the visual designer — they pin an edge to a specific port on a multi-handle node (a router’s per-label ports, for example), so a reload or a fresh automatic layout doesn’t reshuffle the topology. In the builder, a connection drawn from an AI router’s route port carries that route’s label.

Save checkpoints automatically

Every step completion writes a checkpoint to the run record. Two operations use them:
  • Rewind — roll a running or failed run back to a prior checkpoint. Completed steps are preserved; subsequent steps are cleared; execution resumes from the checkpoint moment. Recovers from failures without restarting from scratch.
  • Branch — create a new run from a checkpoint with modified inputs. The original run is unaffected. Useful for “what if” exploration and A/B testing.
Each checkpoint stores completedStepIds, skippedStepIds, the full accumulated variables scope, accumulatedOutputs keyed by step ID, the variableOverwriteOrder for deterministic replay, and a monotonic sequence counter. Checkpoints can also be triggered from the Platform API; configuration options include interval-based capture (every N steps) and phase-boundary capture. You don’t author checkpoints — they author themselves on every step boundary. The decision is whether to expose rewind and branch as first-class operator actions in your workflow’s UI surface, or hide them from non-admin operators. That decision is set on the workflow’s policy, not in the graph.

Author the graph — three paths

You have three ways to compose:
  1. Talk to the Workflow Architect. A Forge-native agent that takes plain-language intent, drafts a validated graph in real time, and watches every tool call render in the drawer. The right path for ~80% of new workflows. The Architect deliberately has no publish authority — promotion is yours.
  2. Use the visual builder by hand. The graph editor at /production/workflows/convex/builder-v2. Steps are arranged automatically: click a + on a connection or under a final step to insert a step (or drag a step type from the palette onto a +), use Add a branch on forks and routers, drag from a step’s bottom port to another step’s top port to connect them, and fill in fields in the step’s panel. See Editing the builder canvas. Faster than the Architect for two-node sequential graphs and purely cosmetic edits.
  3. Drive the Platform API. Programmatic graph authoring through the workflow CRUD endpoints. Useful for templated workflow generation (e.g., per-customer pipelines that share a shape).
All three paths land in the same workflowDrafts row. The validator runs the same way regardless of authoring source.

Pre-publish checklist

Before clicking Publish:
  • Terminal paths end at publish. Every path through the graph should end at a publish node (or an explicitly terminal agent). A path that just stops is almost always a bug.
  • Human gates on irreversible actions. Sending email, calling external APIs, posting to public channels — wrap with a produce node assigned to a human worker unless you’ve measured the downside-risk and decided otherwise.
  • Capability hints are tight. Drop the skills and tool sets the node doesn’t actually use.
  • Timeouts are declared honestly. Any node whose input is a work list has a budget sized from items × per-item, rounded up. Read every AGENT_BUDGET_UNDERSIZED warning rather than dismissing it — it is the only signal you get before the run.
  • Validation strategies are honest. passthrough only where downstream nodes don’t depend on structured output. validated only where semantic quality matters more than cost.
  • Router coverage is complete. Every routeOptions entry has at least one outgoing edge with that label. The validator flags UNCOVERED_ROUTE_LABEL when missing.
  • validateGraphTool returns clean. The Architect calls this at the end of every turn; manual authoring should run it explicitly. warnings is acceptable if you’ve read each warning and decided to accept it.
  • Capability gaps resolved. The publish gate checks the graph’s capabilities before it saves anything. If a node references a skill / tool / agent / procedure that does not resolve in your workspace, publish is refused — see “The publish gate” below.

The publish gate

Clicking Publish runs two checks before the version row is written:
  1. Wiring validation — L1+L2 graph topology + schema-component references. Always hard-blocking; a draft with wiring errors cannot publish.
  2. Capability validation — every capabilityHints.skills, capabilityHints.toolSets, capabilityHints.externalTools, agentDefinitionId, and procedureId referenced by any node must resolve to an active row in this workspace’s registry. Reasons a gap surfaces:
    • not_found — the referenced skill / agent / procedure id is not in the registry. Synthesize it or substitute an existing primitive.
    • not_permitted_in_org — your workspace has not been granted access to an external tool the node references. Ask an admin to grant it.
    • deprecated — the referenced procedure version is past its deprecation horizon. Move to the latest active version.
    • duplicate_name — two synthesis-pending primitives share a name in this workspace (warning only — informational, doesn’t block).
When capability gaps with severity: error are present, the dialog renders the gap list with two paths:
  • Fix first — closes the dialog. You return to authoring, resolve each gap, and re-publish.
  • Publish anyway — requires a non-empty override reason. The publish proceeds and writes an auditEvents row (workflow_published_with_capability_override) carrying your identity, the draft id, the override reason, and the full gap list. Use this when a gap will resolve on the next sync (e.g. a tool grant landing later today) and you do not want to block the deploy.
Warning-severity gaps (currently just duplicate_name) never block publish and never require an override — they are surfaced in the dialog as advisory. The same check is exposed to the Workflow Architect as a pre-flight tool (validateCapabilities). The Architect calls it before emitting proposePlan and resolves error-severity gaps via synthesis, substitution, or operator escalation — so by the time the operator clicks Publish, the gaps list should be empty.

Pin the run to a version

Publishing produces a workflowVersions row with status: "active". A production run pins a specific versionId at launch; a test run pins a draftId. Upgrading a workflow — publishing a new version — never affects in-flight runs. The orchestrator walks the graph the run was pinned to, keyed by whichever foreign key the run carries. workflowVersions rows are immutable once published, so historical runs always replay against the exact shape they ran against. To start a run of the published workflow, dispatch it: from the workflow in the Console, over HTTP with POST /api/v3/workflows/dispatch, or over MCP with forge_run_workflow_and_wait (see the MCP server). For the trigger paths (manual, API, scheduled), see Scheduling and triggers. For the Console operator surface, see Console — Workflows.

Do it over the API

The Platform API path builds a draft’s structure: create the workflow, add nodes, connect them, validate, and publish. These calls use the FORGE_BASE set up in the Raw HTTP tab of the quickstart, but not its token: that token is scoped for dispatch and carries no workflow-authoring scope, so the first call below would answer 403. Mint a token with the scopes these steps need:
Scopes only narrow the app’s roles, so the app must also hold roles carrying these permissions. Builder holds workflows:read, workflows:write and agents:use; publishing also needs workflows:manage at platform scope, which Operator and Platform admin hold. Only structure and content are machine-writable. A node’s agent, worker, person, recipient, channel, credential, vault, tool, skill, procedure, model and sandbox fields are Console-only, and a write that names one answers 400. Bind the agent to a produce node in the builder before you publish. To build or change a whole workflow, ask the Workflow Architect; use these calls for precise edits you already know.
1

Create the workflow

This needs workflows:write and workflows:read at the home the workflow is created in. An External App creates at its owning org unit; a platform API key cannot create.
2

Add the nodes

Each needs workflows:read and workflows:write at the workflow’s home. A node name must be unused in the draft (409 otherwise).
3

Connect them

The builder’s connection checks apply: no self-loop, at most one edge per node pair. A cycle is not refused here; validation reports it.
4

Validate the draft

This needs workflows:read and changes nothing. status is clean, hasWarnings or hasErrors; publishability.status is publishable, gated or broken. Bind the produce node’s agent in the builder, then validate again.
5

Publish

Publishing runs every Console publish gate on the draft as it is now. It needs workflows:manage at the platform scope plus agents:use for the agents the version runs; a refusal is 422 and nothing is written. expectedActiveVersionId is null for a workflow never published; otherwise name the active version, or the call answers 409.
Over MCP, forge_call_operation runs the same writes and forge_call_read_operation the validation; both are in the default start job. Adding a node:
Validating it:

See also