Skip to main content
Each step you select on the builder canvas opens its Properties panel. This page covers the settings operators change most often there: the procedure a procedure node is pinned to, a {{workflow.<name>}} reference inside a static value, the agent an Agent node runs, the Timeout that decides where a step runs, proven artifacts, and the error path and delivery confirmation on Publish and Notify.
Graph builderGraph builder

Graph builder — Forge Console at /production/workflows/convex/builder-v2

What you can do

  • Declare the fields an Agent or Human step outputs. The last step’s outputs are the workflow’s outputs.
  • Pin a procedure node to a procedure version.
  • Reuse a declared workflow input inside a node’s static value, so the graph does not change when the value does.
  • Pick the AI agent for an Agent node and see whether it is Ready, Needs attention or Blocked before you pick it.
  • Set an Agent node’s Timeout, which decides whether the step runs inline or in a detached VM.
  • Put up to five of the agent’s proven artifacts in front of a step’s prompt.
  • Connect an error path from Publish or Notify to a handler, and require delivery receipts before the success path continues.

Choosing a procedure for a procedure node

A procedure node’s Properties show the procedure it is pinned to, as procedure-id@version. A version that is no longer the active head is labelled with its status, for example deprecated.
  • Upgrade. When a newer active version exists, a “vX available” banner offers Upgrade. The banner reads the procedure’s own version list, so it appears however large the catalog is.
  • Change procedure. The catalog list stays closed on a bound node; choose Change procedure to open it, or Cancel to keep the current binding. Switching procedures replaces the node’s input bindings with the new procedure’s inputs.
  • Confirming dropped bindings. A switch or upgrade keeps each input binding whose input still exists with the same type. If any binding would be dropped — on this node, or a downstream node reading an output the new version no longer declares — a confirmation lists each one before anything changes. Keep current procedure leaves the node as it was. An upgrade that drops nothing applies in one click.
  • Search. The list shows active procedures a page at a time. Type in Search procedures to match on name, id, or description across the whole catalog, and choose Load more to see the next page.

Reusing a workflow input inside a node’s static value

A node input bound to Static value holds a constant fixed when you author the graph. That constant can carry a {{workflow.<name>}} reference to one of the workflow’s declared inputs, substituted when the run starts — so a value that has to sit inside a shape, like the period token in a report’s dimension filters, stops being a reason to re-author the graph every month. Select the node, open the properties panel, and set the slot’s binding to Static value.
  • For JSON-shaped slots (object, array, string[], number[]) the value is a multiline JSON editor rather than a single line, so a real filter payload is readable before you run it. It highlights JSON syntax, offers every declared workflow input as you type {{, and underlines problems inline with the same rules the publish gate applies.
  • Underneath, a substitution preview shows what the literal resolves to, computed with the arguments of the last completed run. It uses the same substitution the orchestrator uses at dispatch, so a whole-value reference previews as a real array and an embedded one previews spliced into its text. If the referenced input has no value the preview names it instead of resolving; if the workflow has never completed a run there is nothing to preview against and it says so.
  • The preview appears only once the literal parses. While the JSON is mid-edit and invalid, the preview keeps showing the last value that parsed — which is what would actually be dispatched.
The binding dropdown lists Static value as a real option, and switching an interpolated literal to another binding asks before replacing it. That confirm exists because a literal can be the only place a declared workflow input is read: replacing it silently would drop both the value and the input’s last reader in one click. The slot also states which inputs it interpolates. Two rules are worth knowing before you author one, because the console lints for both:
  • The reference must name a declared workflow input that always has a value — required, derived, or optional with a default. An optional input with no default publishes cleanly and then fails only on the runs where the field was left blank.
  • Inside a static value, {{workflow.x}} is the only form that resolves. The {{inputs.x}} and bare {{x}} spellings work in agent prompts and publish messages, not here; used in a literal they are sent to the step verbatim and raise a warning.
An unresolvable reference in a static value fails the step rather than substituting a blank — a blank inside a report filter is a valid request that returns the wrong numbers. The full authoring contract is in Compose a Workflow.

Choose an agent that can run

On an Agent node assigned to AI, the properties panel’s AI agent picker shows each agent’s readiness beside its name: Ready, Needs attention or Blocked. It is the same check the agent’s Ready to run checklist runs. When the agent you pick isn’t ready, a callout under the picker lists what is missing in plain words and who can fix each gap: If you hold the permission, the callout points you to the checklist instead. Open setup checklist opens the agent’s checklist in a new tab, and Create a new agent starts one in the Agent Builder in a new tab, so you keep your place in the workflow. On the canvas, an Agent node whose agent can’t run carries a readiness badge in its bottom-left corner. Hover over it or focus it to see each gap and a link to the checklist. When a publish is refused, the dialog groups these gaps under Agents not ready to run, each with its agent’s name, the gap, and the checklist link.

Setting the runtime budget for a step

On an Agent node assigned to AI, the properties panel’s Timeout field is a duration control — a number plus a min / h unit — and it is the control that decides where that step runs. Under the field sits a live readout that updates as you type: There is no placement toggle and nothing predicts placement for you — the number you type is the decision, and the readout only tells you what it implies. Over-declaring is close to free (a detached VM bills roughly memory while it waits on model streams, and a dead run is caught by a staleness backstop rather than by the declared deadline), so round up.
The SANDBOX — Enable sandbox VM checkbox on the same panel is a different control. It gives the agent a VM to execute code in; it does not extend the agent’s runtime. Set Timeout for that. Reading the sandbox checkbox as a runtime escape hatch is a real, already-made mistake — the panel now says so under the checkbox.
AGENT_BUDGET_UNDERSIZED appears in the issue rail when an AI Agent node with tools, declared outputs, and an array-typed (work-list) input still carries an inline-sized timeout. It is a warning, never an error: it carries the sizing arithmetic, offers a one-click timeout fix chip, and never blocks publish. Since placement follows whatever you declare, there is no invalid combination to block — only an under-declaration worth flagging.
Size a bulk-judgment node as expected items × ~60 output tokens, plus about 4 minutes of time-to-first-token, and round up. A 782-item adjudication needs 40+ minutes. Never trim the work list to fit a budget — raise the budget.
Launching a test run shows the same thing before you commit: if any step in the draft will run detached, the launch dialog lists those steps with their declared budgets (“Adjudicate — detached VM, ~40 min budget”) above the cost forecast. An all-inline graph shows nothing there — the pane appears exactly when there is something to tell you. Once the run is going, Runs shows each step’s actual placement, its heartbeat, and its dual cost meter.

Giving a step proven artifacts

On an Agent node assigned to AI, Advanced → Proven artifacts puts the agent’s top proven artifacts in front of the step’s prompt. Enter a whole number from 0 to 5; 0 is off and is the default. Only artifacts graded proven and still active are used, and only when the agent has memory on. Each one takes prompt space, so use a small number, and only on a step that repeats work the agent has done well before. The field refuses anything outside 0–5. Setting it back to 0 turns it off for that step only: the same agent can use proven artifacts in one step and not in another.

Publish and Notify error handlers

Connect an error path from Publish or Notify to a handler. Preflight refusal and synchronous dispatch failures take that path. On durable outcomes, handling a technical failure preserves the failed execution (failure_handled); expected business exceptions have their own routing contract. On an outcomes-enabled workflow, Delivery confirmation can require queued, accepted, or delivered receipts before the node’s success path continues. Choose all recipients or at least one, with a 60–900 second deadline. Clearing the policy restores the existing behavior: Notify records obligations, and queued Publish hands off to its transport. Email hand-off does not establish final delivery. The selected-step inspector shows original confirmation progress, deadline, and safe next action. An uncertain effect requires reconciliation before any resend. An authorized repair creates a separate notification obligation; it cannot change the original wait’s result. Required notification reporting stays separate from business completion and error handling.

Declare step and workflow outputs

A step’s Outputs are the named fields it emits. Downstream steps read them through their input bindings, rules and conditions, and the outputs of the last step become the workflow’s outputs. Declare a step’s outputs. Select an Agent or Human step and find Outputs in its Properties panel. A step with none shows No outputs declared. When Passthrough is stored as the step’s strategy, an empty section starts collapsed as Add output fields; choose it to open the section.
  1. Type the field name in the output_field_name box, for example summary.
  2. Press Enter or choose + Add. A new output is a string.
  3. Change its type if it is not text: string, number, integer, boolean, object, array, date, file, string[], number[] or file[]. A text output is string.
  4. Optionally describe the field, so the agent and downstream authors know what it holds.
To declare several fields at once, choose Infer outputs from a sample →, paste a sample JSON object and choose Apply. Each top-level key becomes an output with an inferred type. It replaces the outputs already declared. Each declared output has its own remove control. The step’s Validation Strategy, under Advanced in the same panel, decides how its result is checked against the declared outputs: Schema (a structural check), Validated (schema plus an agent review) or Passthrough (no validation). A step added from the palette starts on Schema. A Human step offers only Passthrough and Schema. To declare your own outputs, choose Schema or Validated. Under Passthrough:
  • A Human step may declare only the fields every human task returns: decision, completedBy, completedVia and response. Any other declared output is an error that blocks publishing.
  • An Agent step never emits its declared outputs, so they resolve to nothing. Publishing is blocked when a downstream step binds to one; an output nothing reads is only a warning.
The workflow’s outputs. The builder has no separate workflow-output editor. When a run completes, Forge merges the outputs of every terminal step (a step with no outgoing edge other than an error path) into the run’s outputs. To give a workflow a summary output, declare summary on an Agent or Human step that has no step after it, with Schema or Validated as its strategy. A Publish or Notify step emits its own result, not the fields of the step before it: Notify, for example, returns the IDs of the notifications it recorded. If a workflow ends with one of them, the earlier step’s fields do not become workflow outputs. A failed or cancelled run also records the outputs its terminal steps produced before it stopped.

Key state to watch

  • Agent readiness beside each name in the AI agent picker — a Blocked agent cannot run the step.
  • The Timeout readout — Runs inline or Runs in a detached VM (up to 24 h); the number you type is the placement decision.
  • AGENT_BUDGET_UNDERSIZED in the issue rail — a warning that a work-list step still has an inline-sized timeout.
  • No outputs on the last step — the run completes with no workflow outputs to read. Check that the last step is an Agent or Human step and declares them under Schema or Validated.
  • Delivery confirmation deadline on Publish and Notify — the success path waits for the receipts you chose, for 60 to 900 seconds.
  • Builder canvas — where steps are added and connected.
  • Agents — an agent’s Ready to run checklist.
  • Procedures — the procedure catalog and its versions.
  • Runs — each step’s actual placement, heartbeat and cost once a run starts.
  • Build → Declare the runtime budget — sizing a long-running node.