pass and block. This recipe wires it end-to-end: a workflow graph that pauses at a human checkpoint, the node-level hold configuration that parks the run there, a budget envelope that caps spend, and a run you can watch resume in the operator console.
The end state
When the recipe is done:- A workflow definition exists with at least three
producenodes — an agent-worker step, then a human-worker (EMPLOYEE / CONTRACTOR) step, then another agent-worker step. - The human-worker
producenode creates an approval-shaped human-interaction request when the run reaches it; itsworkflowNodeRunsrow sits inwaitinguntil a human resolves it (the run itself staysrunning— there is noholdingrun status). - An envelope budget caps spend for the enclosing scope; the
budgetEnvelopesgate blocks the dispatch if the projected cost exceeds the cap. - Every step writes to
stepResults; every governance decision writes togovernanceAuditLogand the approval lifecycle events land inauditEvents. Operators inspect both in Forge Console; integrations use the documented HTTP operations.
Prerequisites
- Console access to compose and publish the workflow, assign its human worker, and attach the envelope budget. A draft graph edit over HTTP cannot set a node’s agent or worker.
- The person who will decide the hold, available as the human worker (an EMPLOYEE or CONTRACTOR) for the middle step.
- For the API path: the
FORGE_BASEandACCESS_TOKENfrom the Raw HTTP tab of the quickstart, withworkflows:useto dispatch andruns:readto watch the run.
The four steps
1
Compose the graph
The fastest path is the Workflow Architect — describe what you want in plain language and watch it draft, validate, and pin the graph. For deterministic authoring, use the Forge Console graph editor at Production → Workflows → New or the Dashboard API.The minimum graph for HITL is three Each node has a type and a small handful of fields. The human-worker Every transition between nodes flows through the workflow orchestrator. When the orchestrator advances to a
produce nodes wired in sequence — the middle node is assigned to a human worker (EMPLOYEE or CONTRACTOR) rather than an agent:produce node is the load-bearing one for this recipe — it is the synchronization point, and its workflowNodeRuns row sits in waiting while the human is out. The Architect renders the same node types described in Node Types. All five shipping node types — produce, router, join, publish, procedure — are listed there; human dispatch is a property of the worker assignment on a produce node, not a separate node type.produce node whose resolved worker is a human, it does not run an agent — it creates an approval request and stops walking the DAG.2
Configure the hold
A human-worker When the run reaches the Agent node assigned to a person, that step waits and Forge creates a human task for the assignee; the approval lifecycle takes over from there. A notification reaches the assignee through whatever surfaces are configured (Console tray, Slack syndication, email).
produce node carries its own hold configuration on the node itself — there is no approvalPolicyId field on workflowGraphNodes. The approvalPolicies table is the separate, platform-scoped mechanism whose trigger enum covers deployment, run_creation, budget_change, agent_config_change, policy_change, agent_position_creation, and workflow_lifecycle_change — it has no per-node trigger.The node-level fields that shape the hold are:3
Cap the spend
A workflow that pauses for review still costs money — the draft node ran a model, the storage write incurred a small charge, and the resume node will run another model. Without a ceiling, a runaway loop is bounded only by the agent-level monthly budget.Attach an envelope budget — a The
budgets row scoped to the enclosing entity. Envelope scopes are global / gateway / agent / externalApp over a daily / weekly / monthly period; there is no workflow-definition-scoped envelope:budgetEnvelopes gate reads this on every dispatch in the run. An exhausted envelope blocks the dispatch with errorCode budget_exceeded (not retryable) and writes a governanceAuditLog row with disposition: "block". The run halts; no resume token will revive it without operator intervention.4
Run it and watch the pause
Trigger the run from the Console (Production → Workflows → Run), via the API (POST /v2/workflows/dispatch), or through a scheduled trigger if it should fire on a cadence. Every dispatch — manual, API, or cron — flows through the same orchestrator and the same gate pipeline.Open the Console run-detail view and watch the DAG light up live: green for completed, blue for in-flight, amber for the step waiting on a person. When the run hits the human-worker
produce node, the approver’s tray fills and the audit timeline records an approval_created event under the workflow category (the governance category is used when an approval has no run attached).When the approver clicks Approve, three things happen in order: the approvals row flips to approved (stamping resolvedAt / resolvedBy), an approval.resolved event goes out on the bus, and the orchestrator wakes up and advances to the send node. From the operator’s view, the DAG flickers and the run completes. From the audit view, every transition is timestamped and attributed.Only a person decides the hold: in the Console, from Slack, by replying to the approval email, or with their own Personal key through POST /api/v3/governance-human-tasks/{humanTaskId}/complete (completeHumanTask, scopes reaching approvals:approve) or the MCP tool forge_handle_human_task. The key acts as its owner, who must be on the task; a platform API key or External App is refused with 403, and a hold that sends outside Forge is approved only in the Console. No shared token decides it (the shared-token POST /api/workflow/approval was removed on 2026-10-10). An integration reads the held run with GET /api/v3/runs/{runId}/trust-status and hands its Console handoff to a person.Do it over the API
These calls use theFORGE_BASE and ACCESS_TOKEN set up in the Raw HTTP tab of the quickstart. Compose the graph and assign the human worker in Console: a draft graph edit over HTTP cannot set a node’s agent or worker. Attach the envelope budget in Console as well. The run itself goes over HTTP.
Dispatch the published workflow (use your workflow’s name, and add runtimeArgs matching its inputs):
workflows:use. Watch the run reach the human step, which needs runs:read:
waiting, its handoff names the Console item the reviewer opens. A reviewer can also answer it with their own Personal key, as in Approvals and HITL. Read the run again: after the answer, the step is resolved and the run goes on to completion.
Over MCP, dispatch with forge_call_operation:
forge_call_read_operation:
When to reach for something else
- You need branching approval logic — one reviewer for some inputs, a different reviewer for others. Use a
routernode to dispatch to one of N human-workerproducenodes based on the upstream output, each carrying its ownassignee/workerAssignment. - You want the human in the conversation rather than gating a step. That’s the Hybrid Workforce Chat shape, not the workflow shape. Chat is the right surface for back-and-forth; HITL approval is the right surface for go/no-go on a discrete action.
- The pause is so common that the workflow is mostly waiting. Reconsider whether the work belongs in a workflow at all — long-running interactive review may want a factory with a managed channel rather than a graph with one node per pause.

