feat: add executor level hitl docs

docs.json

@@ -266,6 +266,8 @@
                       "workflows/hitl/overview",
                       "workflows/hitl/human-review",
                       "workflows/hitl/step",
+                      "workflows/hitl/executor",
+                      "workflows/hitl/nested",
                       "workflows/hitl/output-review",
                       "workflows/hitl/router",
                       "workflows/hitl/condition",

reference/workflows/conditional-steps.mdx

@@ -10,6 +10,7 @@
 | `else_steps` | `WorkflowSteps` | `None` | Steps to execute if the condition is not met (else branch) |
 | `name` | `Optional[str]` | `None` | Name of the condition step |
 | `description` | `Optional[str]` | `None` | Description of the condition step |
+| `human_review` | `Optional[HumanReview]` | `None` | All HITL settings in a single config. See [HumanReview Config](/workflows/hitl/human-review). |
 | `requires_confirmation` | `bool` | `False` | Pause for user to decide which branch to execute |
 | `confirmation_message` | `Optional[str]` | `None` | Message shown to user when requesting decision |
 | `on_reject` | `OnReject` | `OnReject.else_branch` | Action when rejected: `else_branch` (execute else_steps), `skip`, `cancel` |

reference/workflows/loop-steps.mdx

@@ -11,6 +11,11 @@ sidebarTitle: Loop Steps
 | `max_iterations` | `int` | `3` | Maximum number of iterations for the loop |
 | `forward_iteration_output` | `bool` | `True` | If True, each iteration receives the previous iteration's output as input. If False, all iterations receive the original loop input |
 | `end_condition` | `Optional[Union[Callable[[List[StepOutput]], bool], Callable[[List[StepOutput]], Awaitable[bool]]]]` | `None` | Function to evaluate if the loop should end |
+| `human_review` | `Optional[HumanReview]` | `None` | All HITL settings in a single config. See [HumanReview Config](/workflows/hitl/human-review). |
 | `requires_confirmation` | `bool` | `False` | Pause for user confirmation before starting the loop |
 | `confirmation_message` | `Optional[str]` | `None` | Message shown to user when requesting confirmation |
-| `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel` |
+| `requires_iteration_review` | `bool` | `False` | Pause after each iteration so the user can review and approve, edit, or reject. See [Loop HITL](/workflows/hitl/loop#iteration-review). |
+| `iteration_review_message` | `Optional[str]` | `None` | Message shown to user during iteration review |
+| `hitl_timeout` | `Optional[int]` | `None` | Seconds before the HITL pause auto-resolves. See [Timeout](/workflows/hitl/timeout). |
+| `on_timeout` | `Union[OnTimeout, str]` | `OnTimeout.cancel` | Action when the HITL timeout expires: `approve`, `reject`, `cancel` |
+| `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel`, `retry` |

reference/workflows/router-steps.mdx

@@ -11,12 +11,18 @@ sidebarTitle: Router Steps
 | `choices` | `WorkflowSteps` | Required | Available steps for selection. Supports nested lists (becomes Steps container) |
 | `name` | `Optional[str]` | `None` | Name of the router step |
 | `description` | `Optional[str]` | `None` | Description of the router step |
+| `human_review` | `Optional[HumanReview]` | `None` | All HITL settings in a single config. See [HumanReview Config](/workflows/hitl/human-review). |
 | `requires_confirmation` | `bool` | `False` | Pause for user confirmation before executing selected route |
 | `confirmation_message` | `Optional[str]` | `None` | Message shown to user when requesting confirmation |
-| `requires_user_input` | `bool` | `False` | Pause for user to select route(s) instead of using selector |
+| `requires_user_input` | `bool` | `False` | Pause for user to select route(s) instead of using selector. See [Router HITL](/workflows/hitl/router#route-selection). |
 | `user_input_message` | `Optional[str]` | `None` | Message shown to user when requesting route selection |
 | `allow_multiple_selections` | `bool` | `False` | Allow user to select multiple routes |
-| `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel` |
+| `requires_output_review` | `bool` | `False` | Pause after the selected route completes to review its output. See [Output Review](/workflows/hitl/output-review). |
+| `output_review_message` | `Optional[str]` | `None` | Message shown to user during output review |
+| `hitl_max_retries` | `int` | `3` | Max re-executions when an output review is rejected with `OnReject.retry` |
+| `hitl_timeout` | `Optional[int]` | `None` | Seconds before the HITL pause auto-resolves. See [Timeout](/workflows/hitl/timeout). |
+| `on_timeout` | `Union[OnTimeout, str]` | `OnTimeout.cancel` | Action when the HITL timeout expires: `approve`, `reject`, `cancel` |
+| `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel`, `retry` |
 
 ## Selector Return Types
 

reference/workflows/run-output.mdx

@@ -24,6 +24,27 @@
 | `metadata` | `Optional[Dict[str, Any]]` | `None` | Additional metadata stored with the response |
 | `created_at` | `int` | `int(time())` | Unix timestamp when the response was created |
 | `status` | `RunStatus` | `RunStatus.pending` | Current status of the workflow run |
+| `step_requirements` | `Optional[List[StepRequirement]]` | `None` | HITL requirements to resolve before continuing the run. Accumulates across pauses; the last entry is the active one. See [HITL overview](/workflows/hitl/overview). |
+| `error_requirements` | `Optional[List[ErrorRequirement]]` | `None` | Error-level HITL requirements when a step failed with `on_error="pause"`. See [Error Handling](/workflows/hitl/error-handling). |
+| `paused_step_index` | `Optional[int]` | `None` | Index of the paused step |
+| `paused_step_name` | `Optional[str]` | `None` | Name of the paused step |
+| `pause_kind` | `Optional[Union[PauseKind, str]]` | `None` | Active pause kind: `"step"` or `"executor"`. `None` when not paused. |
+
+### HITL Properties
+
+Read-only properties that filter `step_requirements` for common cases:
+
+| Property | Returns | Description |
+|----------|---------|-------------|
+| `is_paused` | `bool` | `True` if the workflow is paused (`status == RunStatus.paused`) |
+| `is_cancelled` | `bool` | `True` if the workflow was cancelled |
+| `active_step_requirements` | `List[StepRequirement]` | Requirements that have not been resolved yet |
+| `steps_requiring_confirmation` | `List[StepRequirement]` | Requirements needing confirm/reject |
+| `steps_requiring_user_input` | `List[StepRequirement]` | Requirements needing user input values |
+| `steps_requiring_output_review` | `List[StepRequirement]` | Requirements needing output review |
+| `steps_requiring_route` | `List[StepRequirement]` | Routers needing route selection |
+| `steps_requiring_executor_resolution` | `List[StepRequirement]` | Steps with a paused agent/team tool call |
+| `active_error_requirements` | `List[ErrorRequirement]` | Error requirements that still need user decision |
 
 ## WorkflowRunOutputEvent Types and Attributes
 
@@ -85,6 +106,92 @@
 | `step_response` | `Optional[StepOutput]` | `None` | Complete step execution result object |
 | *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
 
+### StepPausedEvent Attributes
+
+Emitted when step-level HITL pauses a step before execution.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.step_paused.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the paused step |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the paused step |
+| `step_id` | `Optional[str]` | `None` | Unique step identifier |
+| `requires_confirmation` | `bool` | `False` | Pause is for confirmation |
+| `confirmation_message` | `Optional[str]` | `None` | Message shown to the user |
+| `requires_user_input` | `bool` | `False` | Pause is for user input |
+| `user_input_message` | `Optional[str]` | `None` | Message shown to the user |
+| `user_input_schema` | `Optional[List[Dict[str, Any]]]` | `None` | Schema describing the requested input fields |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
+### StepContinuedEvent Attributes
+
+Emitted when a paused step resumes after step-level HITL is resolved.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.step_continued.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the resuming step |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the step |
+| `step_id` | `Optional[str]` | `None` | Unique step identifier |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
+### StepExecutorPausedEvent Attributes
+
+Emitted when the agent or team running a step pauses on a tool call that requires HITL. See [Executor HITL](/workflows/hitl/executor).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.step_executor_paused.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the step containing the executor |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the step |
+| `step_id` | `Optional[str]` | `None` | Unique step identifier |
+| `executor_id` | `Optional[str]` | `None` | ID of the paused agent or team |
+| `executor_name` | `Optional[str]` | `None` | Name of the paused agent or team |
+| `executor_run_id` | `Optional[str]` | `None` | Run ID of the paused executor |
+| `executor_type` | `Optional[Union[ExecutorType, str]]` | `None` | `"agent"` or `"team"` |
+| `executor_requirements` | `Optional[List[Any]]` | `None` | Tool-level HITL requirements awaiting resolution |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
+### StepExecutorContinuedEvent Attributes
+
+Emitted when a paused executor resumes after executor-level HITL is resolved.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.step_executor_continued.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the step containing the executor |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the step |
+| `step_id` | `Optional[str]` | `None` | Unique step identifier |
+| `executor_id` | `Optional[str]` | `None` | ID of the resuming agent or team |
+| `executor_name` | `Optional[str]` | `None` | Name of the resuming agent or team |
+| `executor_run_id` | `Optional[str]` | `None` | Run ID of the resuming executor |
+| `executor_type` | `Optional[Union[ExecutorType, str]]` | `None` | `"agent"` or `"team"` |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
+### StepOutputReviewEvent Attributes
+
+Emitted when a step requires post-execution output review. See [Output Review](/workflows/hitl/output-review).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.step_output_review.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the step under review |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the step |
+| `step_id` | `Optional[str]` | `None` | Unique step identifier |
+| `requires_output_review` | `bool` | `True` | Always `True` for this event |
+| `output_review_message` | `Optional[str]` | `None` | Message shown to the user during review |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
+### StepErrorEvent Attributes
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.step_error.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the step that errored |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the step |
+| `error` | `Optional[str]` | `None` | Error message |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
 ### ConditionExecutionStartedEvent Attributes
 
 | Parameter | Type | Default | Description |
@@ -196,6 +303,20 @@
 | `step_results` | `List[StepOutput]` | `field(default_factory=list)` | Results from executed steps |
 | *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
 
+### RouterPausedEvent Attributes
+
+Emitted when a router pauses for the user to select route(s). See [Router HITL](/workflows/hitl/router#route-selection).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `event` | `str` | `WorkflowRunEvent.router_paused.value` | Event type identifier |
+| `step_name` | `Optional[str]` | `None` | Name of the router step |
+| `step_index` | `Optional[Union[int, tuple]]` | `None` | Index of the router |
+| `available_choices` | `List[str]` | `[]` | Names of routes the user can select from |
+| `user_input_message` | `Optional[str]` | `None` | Message shown to the user |
+| `allow_multiple_selections` | `bool` | `False` | Whether the user can select multiple routes |
+| *Inherits all fields from `BaseWorkflowRunOutputEvent`* |
+
 ### StepsExecutionStartedEvent Attributes
 
 | Parameter | Type | Default | Description |

reference/workflows/step.mdx

@@ -16,10 +16,18 @@ sidebarTitle: Step
 | `skip_on_failure` | `bool` | `False` | Whether to skip this step if it fails after all retries |
 | `add_workflow_history` | `bool` | `False` | If True, add the workflow history to the step |
 | `num_history_runs` | `int` | `None` | Number of runs to include in the workflow history, if not provided, all history runs are included |
+| `human_review` | `Optional[HumanReview]` | `None` | All HITL settings in a single config. Equivalent to passing the flat fields below. See [HumanReview Config](/workflows/hitl/human-review). |
 | `requires_confirmation` | `bool` | `False` | Pause for user confirmation before execution |
 | `confirmation_message` | `Optional[str]` | `None` | Message shown to user when requesting confirmation |
 | `requires_user_input` | `bool` | `False` | Pause to collect user input before execution |
 | `user_input_message` | `Optional[str]` | `None` | Message shown to user when requesting input |
 | `user_input_schema` | `Optional[List[UserInputField]]` | `None` | Schema defining expected input fields |
-| `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel` |
-| `on_error` | `OnError` | `OnError.fail` | Action on error: `fail`, `skip`, `pause` |
+| `requires_output_review` | `Union[bool, Callable[[StepOutput], bool]]` | `False` | Pause after execution to review the step's output. See [Output Review](/workflows/hitl/output-review). |
+| `output_review_message` | `Optional[str]` | `None` | Message shown to user during output review |
+| `hitl_max_retries` | `int` | `3` | Max re-executions when an output review is rejected with `OnReject.retry` |
+| `hitl_timeout` | `Optional[int]` | `None` | Seconds before the HITL pause auto-resolves. See [Timeout](/workflows/hitl/timeout). |
+| `on_timeout` | `Union[OnTimeout, str]` | `OnTimeout.cancel` | Action when the HITL timeout expires: `approve`, `reject`, `cancel` |
+| `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel`, `retry` |
+| `on_error` | `OnError` | `OnError.fail` | Action on error: `fail`, `skip`, `pause` |
+
+When the step's `agent` or `team` calls a tool decorated with `@tool(requires_confirmation=True)`, `requires_user_input=True`, or `external_execution=True`, the workflow pauses with `pause_kind="executor"`. See [Executor HITL](/workflows/hitl/executor).

reference/workflows/steps-step.mdx

@@ -8,6 +8,7 @@ sidebarTitle: Steps
 | `name` | `Optional[str]` | `None` | Name of the steps group for identification |
 | `description` | `Optional[str]` | `None` | Description of the steps group's purpose |
 | `steps` | `Optional[List[Any]]` | `[]` | List of steps to execute sequentially (empty list if not provided) |
+| `human_review` | `Optional[HumanReview]` | `None` | All HITL settings in a single config. See [HumanReview Config](/workflows/hitl/human-review). |
 | `requires_confirmation` | `bool` | `False` | Pause for user confirmation before executing the pipeline |
 | `confirmation_message` | `Optional[str]` | `None` | Message shown to user when requesting confirmation |
 | `on_reject` | `OnReject` | `OnReject.skip` | Action when rejected: `skip`, `cancel` |

reference/workflows/workflow.mdx

@@ -80,6 +80,31 @@ Execute the workflow asynchronously with optional streaming.
 
 - `Union[WorkflowRunOutput, AsyncIterator[WorkflowRunOutputEvent]]`: Either a WorkflowRunOutput or an iterator of WorkflowRunOutputEvents, depending on the `stream` parameter
 
+### `continue_run`
+
+Resume a paused workflow run after HITL requirements have been resolved. Used for both step-level and executor-level pauses. See [HITL overview](/workflows/hitl/overview).
+
+**Parameters:**
+
+- `run_response` (Optional[WorkflowRunOutput]): The paused `WorkflowRunOutput` to continue. If not provided, `run_id` and `session_id` must be supplied to load it from the database.
+- `run_id` (Optional[str]): The run_id of the paused run. Required if `run_response` is not provided.
+- `session_id` (Optional[str]): The session_id of the paused run. Required if `run_response` is not provided.
+- `step_requirements` (Optional[List[StepRequirement]]): Updated step requirements with confirmation status. Defaults to the requirements from `run_response`.
+- `stream` (bool): Whether to stream the response. Defaults to the workflow's stream setting.
+- `stream_events` (Optional[bool]): Whether to stream events. Defaults to the workflow's `stream_events` setting.
+
+**Returns:**
+
+- `Union[WorkflowRunOutput, Iterator[WorkflowRunOutputEvent]]`: A `WorkflowRunOutput` if `stream=False`, otherwise an iterator of events.
+
+**Raises:**
+
+- `ValueError`: If neither `run_response` nor (`run_id` + `session_id`) are provided, the run is not paused, or step requirements have not been resolved.
+
+### `acontinue_run`
+
+Asynchronous variant of `continue_run`. Required when the workflow's database is async. Same parameters and return shape as `continue_run`.
+
 ### `print_response`
 
 Print workflow execution with rich formatting and optional streaming.