HumanReview Config

HumanReview groups all HITL settings into a single object instead of passing them as separate parameters. Step, Loop, Router, Condition, and Steps accept human_review=HumanReview(...). Parallel accepts the parameter but rejects every HITL field, since parallel branches cannot be individually paused.

from agno.workflow.step import Step
from agno.workflow.types import HumanReview
from agno.workflow import OnReject, OnTimeout

Step(
    name="draft_email",
    agent=draft_agent,
    human_review=HumanReview(
        requires_output_review=True,
        output_review_message="Review the draft before sending.",
        on_reject=OnReject.retry,
        max_retries=3,
        timeout=300,
        on_timeout=OnTimeout.approve,
    ),
)

Flat parameters still work for backward compatibility:

# Equivalent to the above
Step(
    name="draft_email",
    agent=draft_agent,
    requires_output_review=True,
    output_review_message="Review the draft before sending.",
    on_reject=OnReject.retry,
    hitl_max_retries=3,
    hitl_timeout=300,
    on_timeout=OnTimeout.approve,
)

If both human_review and flat parameters are provided, human_review takes priority.

All Fields

Field	Type	Default	Description
`requires_confirmation`	`bool`	`False`	Pause for user confirmation before execution
`confirmation_message`	`str`	`None`	Message shown during confirmation
`requires_user_input`	`bool`	`False`	Pause to collect user input before execution
`user_input_message`	`str`	`None`	Message shown when collecting input
`user_input_schema`	`List[UserInputField]`	`None`	Schema defining expected input fields
`requires_output_review`	`bool` or `Callable[[StepOutput], bool]`	`False`	Pause after execution for output review
`output_review_message`	`str`	`None`	Message shown during output review
`requires_iteration_review`	`bool`	`False`	Pause after each loop iteration for review
`iteration_review_message`	`str`	`None`	Message shown during iteration review
`on_reject`	`OnReject`	`OnReject.skip`	Action when user rejects
`on_error`	`OnError`	`OnError.skip`	Action when step errors
`max_retries`	`int`	`3`	Max retries on rejection (when `on_reject=OnReject.retry`)
`timeout`	`int`	`None`	Seconds to wait for user response
`on_timeout`	`OnTimeout`	`OnTimeout.cancel`	Action when timeout expires

Supported Fields by Component

Not every field works on every component. Passing an unsupported requires_* flag raises a ValueError at construction time. The behavior fields (on_reject, on_error, max_retries, timeout, on_timeout) are not validated; they only take effect on the components marked below.

Field	Step	Loop	Router	Condition	Steps	Parallel
`requires_confirmation`	✓	✓	✓	✓	✓	-
`requires_user_input`	✓	-	✓	-	-	-
`requires_output_review`	✓	-	✓	-	-	-
`requires_iteration_review`	-	✓	-	-	-	-
`on_reject`	✓	✓	✓	✓	✓	-
`on_error`	✓	-	-	✓	-	-
`max_retries`	✓	-	✓	-	-	-
`timeout`	✓	-	-	-	-	-
`on_timeout`	✓	-	-	-	-	-

Condition and Steps only support requires_confirmation. Parallel doesn’t support any HITL fields. Passing unsupported fields raises a clear error:

from agno.workflow.condition import Condition
from agno.workflow.types import HumanReview

# This raises ValueError: requires_output_review is not supported on Condition.
# Supported: requires_confirmation.
Condition(
    name="my_condition",
    steps=[...],
    human_review=HumanReview(requires_output_review=True),
)

Validation Rules

requires_output_review and requires_iteration_review cannot both be True in the same config.
Each component validates at construction time. You get a clear error if a field is unsupported.

HITL Modes

Pre-execution: Confirmation

Pause before a step runs. The user approves or rejects.

HumanReview(
    requires_confirmation=True,
    confirmation_message="Delete 1000 records?",
    on_reject=OnReject.cancel,
)

Pre-execution: User Input

Collect parameters from the user before execution.

from agno.workflow.types import HumanReview, UserInputField

HumanReview(
    requires_user_input=True,
    user_input_message="Configure report settings:",
    user_input_schema=[
        UserInputField(name="format", field_type="str", required=True),
        UserInputField(name="include_charts", field_type="bool", required=False),
    ],
)

Post-execution: Output Review

Pause after a step completes so the user can review the output. Supported on Step and Router.

HumanReview(
    requires_output_review=True,
    output_review_message="Review the generated report.",
    on_reject=OnReject.retry,
    max_retries=3,
)

Per-iteration: Iteration Review

Pause after each loop iteration for review. Supported on Loop only.

HumanReview(
    requires_iteration_review=True,
    iteration_review_message="Review this iteration's output.",
    on_reject=OnReject.retry,
)

Timeout

Set a timeout for how long to wait for a user response. If the timeout expires, on_timeout determines what happens. The timeout only applies to Step pauses; other components ignore it.

from agno.workflow import OnTimeout

HumanReview(
    requires_confirmation=True,
    confirmation_message="Approve deployment?",
    timeout=300,  # 5 minutes
    on_timeout=OnTimeout.approve,  # Auto-approve after timeout
)

`OnTimeout` Value	Behavior
`OnTimeout.approve`	Automatically approve and continue
`OnTimeout.skip`	Skip the step and continue
`OnTimeout.cancel`	Cancel the workflow (default)

Serialization

HumanReview serializes to a single "human_review" key in the workflow state. Deserialization reads "human_review" first, then falls back to flat keys for backward compatibility with existing persisted data.

config = HumanReview(
    requires_confirmation=True,
    confirmation_message="Proceed?",
    timeout=60,
)

data = config.to_dict()
# {"requires_confirmation": True, "confirmation_message": "Proceed?", "timeout": 60, ...}

restored = HumanReview.from_dict(data)

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

HumanReview Config

All Fields

Supported Fields by Component

Validation Rules

HITL Modes

Pre-execution: Confirmation

Pre-execution: User Input

Post-execution: Output Review

Per-iteration: Iteration Review

Timeout

Serialization

Developer Resources

​All Fields

​Supported Fields by Component

​Validation Rules

​HITL Modes

​Pre-execution: Confirmation

​Pre-execution: User Input

​Post-execution: Output Review

​Per-iteration: Iteration Review

​Timeout

​Serialization

​Developer Resources

All Fields

Supported Fields by Component

Validation Rules

HITL Modes

Pre-execution: Confirmation

Pre-execution: User Input

Post-execution: Output Review

Per-iteration: Iteration Review

Timeout

Serialization

Developer Resources