Pause Anatomy
The objects a paused workflow exposes: WorkflowRunOutput, StepRequirement, and the executor requirements you resolve to continue.
When a workflow pauses for HITL, it exposes the pause through three nested objects. You read them to find out what is being asked, then resolve the innermost ones and call continue_run.
1run_output = workflow.run("...")23if run_output.is_paused:4 for step_req in run_output.step_requirements or []:5 ... # inspect and resolve6 run_output = workflow.continue_run(run_output)1. WorkflowRunOutput
The top-level run object tells you that a pause happened and where.
| Field | Type | Description |
|---|---|---|
is_paused | bool | True while waiting for user action |
pause_kind | "step" | "executor" | None | Which level paused. None when not paused. |
paused_step_name | Optional[str] | Name of the step that paused |
paused_step_index | Optional[int] | Index of the paused step |
step_requirements | Optional[List[StepRequirement]] | The pending requirements. Accumulates across pauses; the last entry is active. |
Convenience filters return subsets of step_requirements:
| Property | Returns requirements that need... |
|---|---|
active_step_requirements | any resolution (not yet resolved) |
steps_requiring_confirmation | confirm / reject |
steps_requiring_user_input | user input values |
steps_requiring_output_review | output review |
steps_requiring_route | route selection |
steps_requiring_executor_resolution | executor (agent/team) tool resolution |
step_requirements accumulates resolved requirements as run history. To determine the current pause, read only the last entry: (run_output.step_requirements or [])[-1:]. This matters during nested HITL, where a single run pauses more than once. The filter properties above already exclude resolved requirements, so prefer them when you can.
2. StepRequirement
Each entry in step_requirements describes one paused step. The fields that are set depend on what kind of pause it is.
| Field | Set When | Description |
|---|---|---|
step_name / step_index / step_id | always | Identifies the step |
step_type | always | The primitive that created it (Step, Loop, Router, ...) |
requires_confirmation | step confirmation | Pending confirm/reject |
confirmation_message | step confirmation | Message to show the user |
requires_user_input | step user input | Pending input values |
user_input_schema | step user input | List[UserInputField] to fill |
requires_route_selection | router selection | Pending route choice |
available_choices | router selection | Route names to pick from |
requires_output_review | output review | Output ready for review |
step_output | output review | The executed StepOutput under review |
requires_executor_input | executor pause | An agent/team tool call paused |
executor_requirements | executor pause | List of pending tool calls (see below) |
executor_id / executor_name / executor_type | executor pause | The paused agent or team |
Resolution methods (step-level):
| Method | For |
|---|---|
confirm() | Confirmation |
reject(feedback=...) | Confirmation / output review |
edit(new_output) | Output review (accept with edits) |
set_user_input(**values) | User input |
select(choice) / select_multiple([...]) | Route selection |
Status properties: needs_confirmation, needs_user_input, needs_output_review, needs_route_selection, needs_executor_resolution, is_resolved, is_timed_out.
3. Executor Requirements
When requires_executor_input is True, the step paused because the agent or team called a HITL tool. Each entry in executor_requirements is one pending tool call. These are the same RunRequirement objects an agent exposes on a standalone run.
| Field | Description |
|---|---|
tool_execution.tool_name | Name of the paused tool |
tool_execution.tool_args | Arguments the agent chose |
tool_execution.result | Set this for external_execution tools |
user_input_schema | Fields the user must supply (for requires_user_input tools) |
Status properties: needs_confirmation, needs_user_input, needs_external_execution, is_resolved.
Resolution methods (executor-level):
| Method | For |
|---|---|
confirm() | @tool(requires_confirmation=True) |
reject(note=...) | @tool(requires_confirmation=True) |
provide_user_input({...}) | @tool(requires_user_input=True) |
set tool_execution.result | @tool(external_execution=True) |
See Executor HITL for full resolution examples.
Resolution Flow
1run_output = workflow.run("...")23while run_output.is_paused:4 # Active requirement only (history-safe)5 for step_req in (run_output.step_requirements or [])[-1:]:6 if step_req.requires_executor_input:7 for executor_req in step_req.executor_requirements or []:8 executor_req.confirm()9 elif step_req.needs_confirmation:10 step_req.confirm()11 elif step_req.needs_user_input:12 step_req.set_user_input(**collect_values(step_req))13 elif step_req.needs_route_selection:14 step_req.select(choose(step_req.available_choices))1516 run_output = workflow.continue_run(run_output)1718print(run_output.content)