> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow step settings

> Set a step’s properties in the builder: declare its outputs, pin a procedure version, reference workflow inputs, pick an agent, size the timeout, add proven artifacts, route errors.

Each step you select on the [builder canvas](https://docs.gloo.com/forge/console/production/workflows/builder-canvas.md) 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 builder](https://mintcdn.com/gloo-b243725a/Ndtg9NEpwGc2OULA/forge/images/console/production/graph-builder-light.png?fit=max\&auto=format\&n=Ndtg9NEpwGc2OULA\&q=85\&s=a045a6235a7de6552e68ef5dd71e56f1)

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](https://docs.gloo.com/forge/build/compose-a-workflow.md#reference-a-workflow-input-from-inside-a-node).

## 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](https://docs.gloo.com/forge/console/workforce/agents#check-that-an-agent-is-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:

| What is missing | Who can fix it | Permission |
| - | - | - |
| The agent's seat in a position, or the position's **Job** | A platform admin | `org:manage` |
| The agent's worker **Access** | Someone who manages Access | `grants:manage` |
| An owner, the owner's review, the confirmed identity, or the autonomy setting | Someone who manages agents | `agents:manage` |
| A paused agent | Someone who can use emergency stops | `switches:use` |

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:

| Readout | What it means |
| - | - |
| **Runs inline** | The turn executes inside one Convex action. Anything at or below the 8-minute inline budget lands here, and the action wall hard-kills it at that ceiling. |
| **Runs in a detached VM (up to 24 h)** | Declare more than 8 minutes and the same turn runs in its own VM, holding the budget you declared. |

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.

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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](https://docs.gloo.com/forge/console/production/runs.md) 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.

## Related surfaces

* [Builder canvas](https://docs.gloo.com/forge/console/production/workflows/builder-canvas.md) — where steps are added and connected.
* [Agents](https://docs.gloo.com/forge/console/workforce/agents) — an agent's **Ready to run** checklist.
* [Procedures](https://docs.gloo.com/forge/console/platform/procedures.md) — the procedure catalog and its versions.
* [Runs](https://docs.gloo.com/forge/console/production/runs.md) — each step's actual placement, heartbeat and cost once a run starts.
* Build → [Declare the runtime budget](https://docs.gloo.com/forge/build/compose-a-workflow.md#declare-the-runtime-budget) — sizing a long-running node.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.