Human-in-the-loop
Pause workflow execution for human review, approval, or revision
The Human-in-the-loop block (type hitl) is a container block that pauses automated runs so a person can review output, approve the next step, request changes, or cancel. Child blocks inside the container run until a breakpoint is reached, then the workflow waits for a human response.
HITL works like Loop and Parallel blocks: drag steps inside the container, then configure which steps are setpoints (re-runnable) and which are breakpoints (pause before execution).
Overview
Human-in-the-loop enables guarded automation:
Run automated steps: Blocks inside the container execute normally up to a breakpoint
Pause for review: Execution stops before the breakpoint block runs
Notify a human: Send the review prompt in-app, via Telegram, or by email
Interpret the reply: An AI interpreter maps free-text feedback to approve, revise, cancel, or clarify
Resume or revise: Approve to continue, re-run selected setpoints with feedback, or stop the run
Configuration
Open Human-in-the-loop settings from the container block to configure:
Channel
| Channel | Behavior |
|---|---|
| Manual (in-app) | Pause appears in the workspace sidebar under Pending HITL requests |
| Telegram | Sends a DM via the shared Forge HITL bot; requires your Telegram chat id |
| Email (Gmail) | Sends a review email with a reply token; replies resume the pause |
| Slack | Not implemented yet — falls back to the in-app inbox |
For Telegram, message the Forge HITL bot first, then use @userinfobot to find your chat id. Use Send test message in settings to confirm delivery.
Recipient
Required for Telegram and email channels. Not used for manual (in-app) review.
System prompt (optional)
Instructions for how the assistant should summarize workflow state and talk to the reviewer. If omitted, a default approval-focused prompt is used.
Model and max rounds
| Setting | Description |
|---|---|
| Model | LLM used to interpret human replies (default: gpt-4o-mini) |
| Max rounds | Maximum back-and-forth clarification rounds before the pause expires (default: 5) |
| API key (optional) | Override the platform key for the selected model when needed |
Steps inside the container
Mark each child block with one or both flags:
| Flag | Meaning |
|---|---|
| Setpoint | This step can be re-run when the human requests revisions |
| Breakpoint | Pause before this step runs so a human can review upstream output |
A container typically has at least one breakpoint. Setpoints define which earlier steps the human can ask to redo without restarting the entire workflow.
How execution works
- The workflow enters the HITL container and runs child blocks connected from the container start handle.
- When an unapproved breakpoint is reached, execution pauses and a pending request is created.
- The configured channel delivers a review message summarizing current state.
- The human replies (in-app, Telegram, or email).
- The interpreter chooses one action:
- approve — continue and run the breakpoint block
- revise — re-run declared setpoints with injected feedback
- cancel — stop the run
- clarify — ask a follow-up question and wait for another reply
- On resume, prior block outputs are preserved; only reset setpoints and downstream steps re-execute.
Pending pauses expire after 7 days if not resolved.
Accessing HITL output
After a human responds, reference the container block in downstream steps:
| Reference | Description |
|---|---|
<hitl.reply> | The human's raw reply text |
<hitl.feedback> | Revision guidance from the interpreter (falls back to the raw reply) |
<hitl.action> | One of approve, revise, cancel, or clarify |
Replace hitl with your container block name if you renamed it.
Example use cases
Content approval
Agent generates a draft inside the container. A breakpoint before a publish/send step lets an editor approve or request edits to specific setpoints.
Ops review
API and Function blocks gather data; execution pauses before a mutating API call until an operator approves via Telegram.
Quality gate
Evaluator scores output; a breakpoint before downstream routing lets a human override or send specific steps back for revision.
Responding to pauses
Open Pending HITL requests from the workspace sidebar. Review the summary, reply in the dialog, and submit to resume or revise.
Reply directly to the Forge HITL bot message. Your message is correlated to the active pause and processed by the interpreter.
Reply to the review email. The reply token in the message headers links your response back to the correct pause.
Notes
- Category:
subflow - Type:
hitl - Container block — place child blocks inside it; configure setpoints and breakpoints per child
- The interpreter can only re-run declared setpoints; it cannot invent new steps or bypass breakpoints
- Slack channel support is planned; until then it behaves like manual review