> ## 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.

# Add a workflow with HITL approval

> End-to-end recipe — compose a workflow graph with a human-in-the-loop approval node, attach a budget envelope, and watch a real run pause, resume, and complete with full audit.

Human-in-the-loop approval is the third disposition the [governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md) 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](https://docs.gloo.com/forge/run/budgets-and-cost.md) caps spend for the enclosing scope; the `budgetEnvelopes` gate blocks the dispatch if the projected cost exceeds the cap.
* Every step writes to [`stepResults`](https://docs.gloo.com/forge/run/observability); every governance decision writes to `governanceAuditLog` and the approval lifecycle events land in [`auditEvents`](https://docs.gloo.com/forge/run/audit). 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](https://docs.gloo.com/forge/quickstart.md), with `workflows:use` to dispatch and `runs:read` to watch the run.

## The four steps

WORKFLOW + HITL APPROVAL

<ol aria-label="WORKFLOW + HITL APPROVAL" />

**1. Compose the graph**

The fastest path is the [Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md) — 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](https://docs.gloo.com/forge/reference/http-api/workflows).

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:

```text theme={null}
[produce: draft (agent)]  →  [produce: review (human)]  →  [produce: send (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](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph). 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.

```ts theme={null}
// produce node assigned to a human worker — represented in the graph editor as a single block
{
  type: "produce",
  name: "review",
  // one of: specific_worker | any_of_role | any_of_kind | dynamic
  workerAssignment: { kind: "any_of_kind", workerKind: "EMPLOYEE" },
  presentationHint: "approval",
  prompt: "Review the draft campaign before send",
}
```

Every transition between nodes flows through the [workflow orchestrator](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md). 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:

```yaml theme={null}
# workflowGraphNodes fields on the human-worker produce node
presentationHint: approval     # approval | form | question | confirmation
timeout: 86400000              # deadline in ms; unset = wait indefinitely with reminders
onTimeout: escalate            # escalate | skip | fail
escalationChannel: "..."       # optional escalation target
assignee: { ... }              # AssigneeTarget discriminated union
```

When the run reaches the Agent node assigned to a person, that step waits and Forge creates a [human task](https://docs.gloo.com/forge/run/approvals-and-hitl.md#human-tasks) for the assignee; the [approval lifecycle](https://docs.gloo.com/forge/run/approvals-and-hitl.md#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](https://docs.gloo.com/forge/run/budgets-and-cost.md) — 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:

```yaml theme={null}
# budgets row
scope: agent
scopeId: "<agent id>"
period: daily
amount: 5.00
enabled: true
```

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](https://docs.gloo.com/forge/reference/http-api/runs)), or through a [scheduled trigger](https://docs.gloo.com/forge/run/scheduling-and-triggers.md) 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](https://docs.gloo.com/forge/quickstart.md). 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):

```bash theme={null}
RUN_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-review-run-v1" \
  -d '{"name": "campaign-review"}' \
  | jq -r '.data.runId')
```

This needs `workflows:use`. Watch the run reach the human step, which needs `runs:read`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/runs/$RUN_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {status, humanSteps: [.humanSteps[] | {stepId, status, handoff}]}'
```

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](https://docs.gloo.com/forge/run/approvals-and-hitl.md). 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`:

```json theme={null}
{ "operationId": "dispatchWorkflow", "input": { "name": "campaign-review" }, "idempotencyKey": "campaign-review-run-v1" }
```

and read the run with `forge_call_read_operation`:

```json theme={null}
{ "operationId": "getRun", "input": { "id": "<run id>" } }
```

## 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](https://docs.gloo.com/forge/build/talk-to-agents.md) 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](https://docs.gloo.com/forge/run/factories.md) 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.**


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