Skip to main content
The human_in_loop_action lets you pause an automation at any point so a human can take over the browser session. Once the human signals they’re done, the automation resumes from where it left off.

​
Overview

  • Use when: A step requires human judgment, sensitive credentials, or manual verification that cannot be automated.
  • How it works: The agent pauses, the task owner receives a magic-link email to a live browser stream, the human completes the step, then clicks a “Done” button to resume the agent.
  • Timeout: If no completion signal arrives within max_wait_time seconds, the task fails with a HumanInLoopTimeoutException. The hard task timeout is 10 minutes, so max_wait_time must be less than 600.

​
Properties

PropertyTypeUnitDescription
max_wait_timefloatsecondsMaximum time to wait for human completion before timing out

​
JSON Example

{
  "type": "action_node",
  "human_in_loop_action": {
    "max_wait_time": 300
  }
}
The example above waits up to 5 minutes for the human to finish.

​
The HITL Flow

When the agent reaches a human_in_loop_action node:
  1. Agent pauses — execution halts at this node.
  2. Email sent — Optexity sends a magic-link (OTP) email to the task owner.
  3. Human takes over — the link opens the live browser stream at the task-logs page.
  4. Human signals done — the task owner clicks the “Done” button in the dashboard.
  5. Agent resumes — the agent picks up execution at the next node.
If the human does not click done within max_wait_time seconds, the task fails.

​
Complete Automation Example

{
  "url": "https://secure.example.com/login",
  "parameters": {
    "input_parameters": {
      "username": ["user@example.com"]
    }
  },
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "input_text": {
          "command": "get_by_label(\"Username\")",
          "input_text": "{username[0]}",
          "prompt_instructions": "Enter the username"
        }
      }
    },
    {
      "type": "action_node",
      "human_in_loop_action": {
        "max_wait_time": 300
      }
    },
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_role(\"button\", name=\"Submit\")",
          "prompt_instructions": "Click submit after human completes the step"
        }
      }
    }
  ]
}
In this example the agent fills in the username, then pauses for up to 5 minutes so the human can enter a password or complete a sensitive step, then resumes and clicks Submit.

​
Timeout Behavior

If max_wait_time elapses without a completion signal, the agent raises HumanInLoopTimeoutException and the task is marked failed. Choose a value that gives the human enough time to respond — common values:
ScenarioSuggested max_wait_time
Quick manual entry (~1 min)120
Short review (~3 min)180
Longer step (~8 min)480
The hard task timeout is 10 minutes (600 seconds). Setting max_wait_time to 600 or above will cause the task to time out before the HITL window closes. Always keep max_wait_time below 600

​
Best Practices

​
Place HITL nodes at natural breakpoints

Put the pause node immediately before the step that requires human action, not after. The agent stops at the HITL node; all prior nodes will have already executed.

​
Keep max_wait_time realistic

Setting an extremely large timeout (e.g. hours) keeps the cloud worker occupied. If you expect a long human delay, consider splitting the automation into two separate runs instead.

​
Only one HITL pause per task at a time

A second human_in_loop_action node will not trigger while the first is already active. Design your automation so HITL nodes are sequential, not concurrent.

​
Next Steps