Skip to main content
Human-in-the-loop approval is the third disposition the governance pipeline returns — alongside 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 produce nodes — an agent-worker step, then a human-worker (EMPLOYEE / CONTRACTOR) step, then another agent-worker step.
  • The human-worker produce node creates an approval-shaped human-interaction request when the run reaches it; its workflowNodeRuns row sits in waiting until a human resolves it (the run itself stays running — there is no holding run status).
  • An envelope budget caps spend for the enclosing scope; the budgetEnvelopes gate blocks the dispatch if the projected cost exceeds the cap.
  • Every step writes to stepResults; every governance decision writes to governanceAuditLog and the approval lifecycle events land in auditEvents. 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_BASE and ACCESS_TOKEN from the Raw HTTP tab of the quickstart, with workflows:use to dispatch and runs:read to 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 produce nodes wired in sequence — the middle node is assigned to a human worker (EMPLOYEE or CONTRACTOR) rather than an agent:
Each node has a type and a small handful of fields. The human-worker 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.
Every transition between nodes flows through the workflow orchestrator. When the orchestrator advances to a 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 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:
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).
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 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:
The 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 the FORGE_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):
This needs workflows:use. Watch the run reach the human step, which needs runs:read:
While a human step is 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:
and read the run with 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 router node to dispatch to one of N human-worker produce nodes based on the upstream output, each carrying its own assignee / 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.
A workflow that cannot pause for a human is not a production workflow — it is a script with extra steps.