Add to Cursor Add to Claude Copy for LLM View as MD

Human-in-the-Loop

Human-in-the-loop durable tasks pause for human review or approval before continuing. An AI agent proposes an action, a human approves or rejects it, and the workflow resumes with the decision. When the human responds, the task picks up exactly where it left off.

The task pauses on a durable event, freeing the worker slot until the approval arrives. If your workflow is a fixed DAG and the approval gate is known at definition time, Event Conditions are a simpler alternative. It is your responsibility to emit the event from a different part of your application to restore the task.

Step-by-step walkthrough

You’ll build a durable task that proposes an action, waits for a human to push an approval event, and resumes with the decision.

Write a wait-for-approval helper

Define a helper that calls WaitForEvent to pause execution until a human responds. The CEL expression filters on the workflow run ID so the event only matches the specific task that is waiting. Hatchet frees the worker slot while the task is suspended and resumes it when the matching event arrives.

examples/python/guides/human_in_the_loop/worker.py

async def wait_for_approval(ctx: DurableContext) -> dict:
    run_id = ctx.workflow_run_id
    approval = await ctx.aio_wait_for(
        "approval",
        UserEventCondition(
            event_key=APPROVAL_EVENT_KEY,
            expression=f"input.runId == '{run_id}'",
        ),
    )
    return approval

examples/typescript/guides/human-in-the-loop/workflow.ts

function waitForApproval(ctx: DurableContext<unknown>) {
  const runId = ctx.workflowRunId();
  return ctx.waitFor({
    eventKey: APPROVAL_EVENT_KEY,
    expression: `input.runId == '${runId}'`,
  });
}

examples/go/guides/human-in-the-loop/main.go

waitForApproval := func(ctx hatchet.DurableContext) (map[string]interface{}, error) {
	runID := ctx.WorkflowRunId()
	expression := fmt.Sprintf("input.runId == '%s'", runID)
	event, err := ctx.WaitForEvent("approval:decision", expression)
	if err != nil {
		return nil, err
	}
	var eventData map[string]interface{}
	if err := hatchet.EventInto(event, &eventData); err != nil {
		return nil, err
	}
	return eventData, nil
}

The Ruby SDK is in early access, and may change. We'd love your feedback!

examples/ruby/guides/human_in_the_loop/worker.rb

def wait_for_approval(ctx)
  run_id = ctx.workflow_run_id
  ctx.wait_for(
    'approval',
    Hatchet::UserEventCondition.new(
      event_key: APPROVAL_EVENT_KEY,
      expression: "input.runId == '#{run_id}'"
    )
  )
end

Define the approval task

Create a durable task that proposes an action, calls the helper from Step 1, and branches on the result.

examples/python/guides/human_in_the_loop/worker.py

@hatchet.durable_task(name="ApprovalTask")
async def approval_task(input: EmptyModel, ctx: DurableContext) -> dict:
    proposed_action = {"action": "send_email", "to": "user@example.com"}
    approval = await wait_for_approval(ctx)
    if approval.get("approved"):
        return {"status": "approved", "action": proposed_action}
    return {"status": "rejected", "reason": approval.get("reason", "")}

Push the approval event

When the human clicks Approve or Reject in your UI, your frontend or API pushes the event to Hatchet. Include the runId in the payload so the CEL expression in Step 1 matches it to the correct waiting task.

examples/python/guides/human_in_the_loop/trigger.py

# Include the run_id so the event matches the specific task waiting for it.
def push_approval(run_id: str, approved: bool, reason: str = "") -> None:
    hatchet.event.push(
        "approval:decision",
        {"runId": run_id, "approved": approved, "reason": reason},
    )


# Approve: push_approval("run-id-from-ui", True)
# Reject:  push_approval("run-id-from-ui", False, reason="needs review")

Run the worker

examples/python/guides/human_in_the_loop/worker.py

worker = hatchet.worker(
    "human-in-the-loop-worker",
    workflows=[approval_task],
)
worker.start()

⚠️

Always set an execution timeout on the durable task itself so it does not wait indefinitely if a human never responds. See Timeouts for configuration.

Common Patterns

Pattern	Description
Content moderation	Agent flags content; human approves or rejects before publish
Financial approvals	Agent proposes payment or transfer; human approves via dashboard
Customer support escalation	Agent drafts response; human reviews and sends, or edits before sending
LLM output review	Agent generates copy or code; human approves before it goes live

For DAG workflows with a fixed approval gate, use Event Conditions. For agent loops where the decision to wait is dynamic, use a durable task with WaitForEvent.

Pause workflows for external signals (events or sleep) without holding slots.

Long Waits

Agent workflows that may need human approval at decision points.

AI Agents

Route workflow behavior based on approve vs reject from the event payload.

Branching

Declare approval gates in DAG workflows when the wait is known at definition time.

Event Conditions