HIL System Overview
Human-in-the-Loop (HIL) allows workflows to pause at a node, wait for a human decision or data entry, and resume automatically once the actor responds. This guide gives you the complete mental model before diving into specifics.
What Is HIL?
Automated workflows often reach points that require human judgment — an approval decision, a data entry step, or a review of AI-generated content. HIL is the mechanism by which a workflow pauses at such a point, notifies the right person, and resumes when they respond.
Key properties of the HIL system:
- Fully durable: When a workflow suspends, the entire execution state is serialised and written to the database. The in-process thread is freed — there is no long-running thread holding memory.
- Channel-agnostic: Actors can respond through the web UI, a Slack bot, an email link, or any application that calls the resume API. The engine does not care which channel is used.
- Correlation-token based: Each suspension generates a unique token that links the actor's response back to the correct execution instance.
The HIL Lifecycle
HIL node executes
Engine calls the HIL executor. It returns NodeExecutionResult.Suspend(payload).
State persisted
Engine serialises ExecutionMemory and writes to Process_SuspendedExecutions. A correlation token is generated and stored.
Actor notified
A HIL task is created. Notification channels (email, Slack, inbox) are triggered by event handlers.
Actor responds
Actor calls POST /api/executions/{executionResId}/resume with their response data.
Execution resumes
Engine restores ExecutionMemory, merges response data, and continues from the suspended node's output port.
Why the Engine Is Freed During Suspension
Workflows can be suspended for hours, days, or indefinitely. If the engine held an in-process thread for each suspended execution, the server would exhaust resources quickly. Instead, suspension is a database operation — the thread is freed and the engine can handle other executions. When resume is called, a new thread is allocated and the state is restored from the database.