Set Human Oversight

Human oversight controls how much approval an agent needs before it acts. You configure the level of human oversight in the Autonomy section of Agent Configuration when you configure an agent in stage 1 of the Agent Builder.

Autonomy is available for orchestrated agents only. To learn more about orchestrators, see Deploy an Orchestrator.

By default, a new agent executes every action immediately and requests no approval.
Configure autonomy when you want a person to approve some or all of the agent’s actions.

On this page you configure which actions need human approval and how long the agent waits for a reply. Human oversight is part of the human-in-the-loop (HITL) workflow. To learn how a person answers approval requests, see Respond to a Feedback Request.

Autonomy Lanes

An autonomy lane defines the level of human involvement an action needs before the agent executes it. The platform provides three lanes. Every action an agent takes runs in one of the three lanes:

Lane	Agent Behavior	When To Use
Autonomous	The agent acts independently, without human approval.	Low-risk, easily corrected actions such as logging readings, publishing status updates, and other read-only observations.
Supervised	The agent submits the action for review and waits for a reply. When a person responds, the agent acts on that response. If the configured Feedback timeout period elapses with no response, the agent applies the selected Timeout action.	Medium-confidence, reversible actions such as threshold adjustments, alert-routing changes, and configuration updates.
Controlled	The agent submits the action for approval and waits for a reply. The agent executes the action only after a person explicitly approves the action. If the configured Feedback timeout period elapses with no response, the agent does not run the action.	High-impact actions such as stopping a production line, deleting records, or sending customer-facing communications.

Lane

Agent Behavior

When To Use

Autonomous

The agent acts independently, without human approval.

Low-risk, easily corrected actions such as logging readings, publishing status updates, and other read-only observations.

Supervised

The agent submits the action for review and waits for a reply. When a person responds, the agent acts on that response. If the configured Feedback timeout period elapses with no response, the agent applies the selected Timeout action.

Medium-confidence, reversible actions such as threshold adjustments, alert-routing changes, and configuration updates.

Controlled

The agent submits the action for approval and waits for a reply. The agent executes the action only after a person explicitly approves the action. If the configured Feedback timeout period elapses with no response, the agent does not run the action.

High-impact actions such as stopping a production line, deleting records, or sending customer-facing communications.

Default Lane

The Default lane setting is the agent-wide baseline. The agent applies the default lane to every action that you do not route to a different lane with an override.

In the Agent Builder, select one lane under Default lane.
Use the optional Stage overrides and Per-lane overrides fields to change the behavior for individual actions.

Autonomy Routing

Autonomy routing is the decision the agent makes about which autonomy lane an action uses. Before the agent takes an action, the agent resolves the lane in the following order, from most specific to agent-wide global fallback:

Per-action override: A setting attached to one specific action that overrides the broader oversight rules for that action alone. In routing, a per-action override can pin a single action to a specific lane, regardless of the stage override or default lane settings. The agent checks for per-action-overrides first.
Stage override: Sets a specific autonomy lane for individual stages. For example, all actions in the Reason stage use the Controlled lane. When Stage overrides is set to Default for a stage, the global Default lane is used.
Default lane: The global fallback to be used for actions that do not have Per-action or Stage overrides.

The resolved lane determines what happens next:

Autonomous: The agent executes the action. No timeout applies since the agent does not request human input.
Supervised or Controlled: The agent pauses and requests human input. If no response arrives within the Feedback timeout period, the agent applies timeout resolution.

Timeout Resolution

Timeout resolution decides what the agent does when an action in a Supervised or Controlled lane does not get a human response within the Feedback timeout period.

Timeout resolution never applies to autonomous actions.

Timeout Action	Agent Behavior
Continue	The agent executes the action as if a person approved it.
Skip	The agent moves on without executing the action in the current cycle.
Reject	The agent cancels the action.

Timeout Action

Agent Behavior

Continue

The agent executes the action as if a person approved it.

Skip

The agent moves on without executing the action in the current cycle.

Reject

The agent cancels the action.

To select the timeout action, the agent checks the following settings in order, from most specific to agent-wide global fallback:

Per-action override: The timeout and defaultAction values configured on the feedback condition of a particular action in the Reason stage. Per-action settings take precedence over all other settings.
Per-lane override: The timeout settings that apply to actions within a particular autonomy lane. Per-lane settings take precedence over global fallback settings.
Timeout action: The global fallback settings configured in the Feedback timeout and Timeout actions fields.
Built-in default: The system-wide values that the agent uses when no other setting exists: Continue and 300000 milliseconds (5 minutes). The built-in default is not configurable.

Global Fallback Settings

Global fallback settings provide agent-wide defaults for the timeout behavior. The settings apply across all autonomy lanes, you do not set one fallback per lane.

The agent uses the global fallback settings only for feedback conditions that do not have a per-action override or per-lane Default action setting.

There are two global fallback settings:

Setting	Default Value	What It Controls
Feedback timeout	300000	The time in milliseconds the agent waits for a human response.
Timeout action	Continue	The action the agent takes when the configured Feedback timeout period expires without a human response. The following actions are available: Continue: After the configured Feedback timeout expires, the agent proceeds with the action. Skip: After the configured Feedback timeout expires, the agent skips the action. Reject: After the configured Feedback timeout expires, the agent cancels the action.

Setting

Default Value

What It Controls

Feedback timeout

300000

The time in milliseconds the agent waits for a human response.

Timeout action

Continue

The action the agent takes when the configured Feedback timeout period expires without a human response. The following actions are available:

Continue: After the configured Feedback timeout expires, the agent proceeds with the action.
Skip: After the configured Feedback timeout expires, the agent skips the action.
Reject: After the configured Feedback timeout expires, the agent cancels the action.

Decide Which Lane an Action Needs

Every action handler carries a risk tier: low, medium, high, or critical. The tier appears as a badge in the handler picker of the Actuate stage. For the tiers and the actions in each one, see Act on Data.

The risk tier of an action suggests a starting lane. Start from the recommendation in the following table and adjust the lane for the context in which the action runs:

Risk Tier Starting Recommendation Adjust When

Risk Tier	Starting Recommendation	Adjust When
`low`	Autonomous	Almost always appropriate.
`medium`	Supervised	The action is novel, high-volume, or hard to reverse.
`high`	Controlled	The agent has a long track record you trust.
`critical`	Controlled	Never relax this. Always require approval.

low

Autonomous

Almost always appropriate.

medium

Supervised

The action is novel, high-volume, or hard to reverse.

high

Controlled

The agent has a long track record you trust.

critical

Controlled

Never relax this. Always require approval.

The risk tier is a starting point, not a decision. Consider the following six factors before you assign a lane.

Agent Confidence

Confidence is a value between 0 and 1 that the Reason stage produces alongside its analysis or plan. The Reason stage produces a confidence value in large language model (LLM) mode only. A deterministic, rule-based agent produces no confidence value.

When confidence falls below the confidenceThreshold of a lane, the agent moves the action to a stricter lane. For example, an autonomous.confidenceThreshold: 0.95 keeps the action in the autonomous lane only when the agent is at least 95% confident.

For a rule-based agent, confidenceThreshold has no effect. Use defaultLane and per-action overrides to control the lane instead. For more information, see Reason on Data.

Reversibility

An action is considered reversible when you can undo its effect without a second operation and without a lasting consequence.

To evaluate the reversibility of an action, ask two questions:

Can you restore the previous state, and how long does that take?
Does anything outside the platform act on the result before you can undo it?

An action that another system consumes immediately, such as an email to a customer or a command to a production line, is effectively irreversible. Put those actions in the controlled lane, even when the risk tier suggests otherwise.

Operator availability: A controlled lane only works if someone responds. For overnight or off-hours cycles, either use a short timeout with defaultAction: continue, or relax the autonomy level of the lane to Supervised.

Scope of Impact

The scope of impact is the number of systems, devices, or people that one action affects. A threshold change on a single sensor and the same change across an entire site carry the same risk tier but different consequences.

Assign the lane based on the widest effect that the action can have, not the typical one. When the same handler serves both narrow and wide cases, add a requireFeedback block with a condition that requests approval only for the wide case.

Response Availability

A Controlled lane only works when someone responds. Before you assign an action to a Controlled lane, check the level of human availability for the period that the agent runs.

Availability also determines a workable timeout. Match the timeout to the trigger interval of the agent. A timeout longer than the interval lets requests from several cycles queue up at once.

When an agent runs overnight or outside staffed hours, requests can expire before anyone sees them. For those cycles, consider one of the following options:

Configure notifications for the network, so that a request reaches a person who is on call. See Respond to a Feedback Request.
Restrict the trigger of the agent to staffed hours. See Set a Trigger to Run an Agent Cycle.
Use a short timeout with defaultAction: continue, to let the cycle proceed without a response. The agent then runs the action without approval. Choose this option only for actions that tolerate an unapproved run.

Request Volume

When a frequent action runs in the Supervised or Controlled lane, the agent creates a feedback request every cycle. A constant stream of requests can reduce the attention that each one receives. Oversight adds value only when a person has time to review each request.

Regulate the volume of requests with one of the following options:

Add a condition to the requireFeedback block so that the agent asks only when the situation warrants it. For example, confidence < 0.85.
Use the confidenceThreshold setting on the lane to keep an agent that has a high confidence level in a lane that generates fewer feedback requests.
Widen the trigger interval, so that cycles run less often.

Audit and Regulatory Requirements

Some actions require a recorded human decision regardless of their risk tier. The audit trail of an agent supports compliance needs. Examples include the EU AI Act, FDA 21 CFR Part 11 for electronic records, and the ISO 9001 quality management standard.

Put actions that require a human decision in the controlled lane with defaultAction: reject. A rejection on timeout records a refusal, so the record covers the decision either way. Enable Audit Trail in the agent configuration to preserve the record. See Configure an Agent.

Audit Trail is available for orchestrated agents only. To learn more about orchestrators, see Deploy an Orchestrator.

Set the Default Lane (YAML)

Add an autonomy block to the agent and set defaultLane. The default lane applies to every action that has no explicit override. Use the optional lanes block to tune how each lane behaves. The Agent Builder shows these per-lane overrides as fields.

autonomy:
  defaultLane: supervised        # autonomous | supervised | controlled

  lanes:
    autonomous:
      confidenceThreshold: 0.95  # Use the autonomous lane when confidence >= 0.95

    supervised:
      confidenceThreshold: 0.7
      timeout: 300000            # Time to wait for a feedback response (5 min)
      defaultAction: continue    # continue | skip | reject (applied on timeout)

    controlled:
      timeout: 600000            # Time to wait for human approval (10 min)
      defaultAction: reject      # reject = do NOT act on timeout (recommended)

Units: Use a number that represents milliseconds for every timeout in the autonomy block. For example: 300000 milliseconds = 5 minutes, 600000 milliseconds = 10 minutes.

Override the Default Lane for a Specific Action (YAML)

To use a different lane for one action, add a requireFeedback block to its execute substage. This is a stage override. It takes precedence over defaultLane for that action only.

actuate:
  substages:
    - type: execute
      name: adjust-thresholds
      executors:
        - type: mqtt_publish
          connection: factory-mqtt
          topic: factory/quality/threshold-updates
          payload:
            metricName: '${action.params.metricName}'
            newThreshold: '${action.params.newThreshold}'

      requireFeedback:
        condition: 'confidence < 0.85'   # Only ask when confidence is low
        priority: normal                 # critical | high | normal | low
        question: "I adjusted the threshold for {{action.params.metricName}} from {{action.params.oldThreshold}} to {{action.params.newThreshold}}. Was this appropriate?"
        options:
          - id: approve
            label: Good adjustment
          - id: revert
            label: Revert — threshold was fine
            riskLevel: medium
          - id: modify
            label: Adjust further
            riskLevel: low
        timeout: 300000
        defaultAction: continue

Override the Default Lane for a Reasoning Step

You can also add requireFeedback to a Reason substage, so a person reviews the agent’s interpretation before it plans actions:

reason:
  substages:
    - type: analyze
      name: quality-assessment
      prompt: '...'
      outputSchema: {}

      requireFeedback:
        condition: 'confidence < 0.6'
        priority: high
        question: "My confidence in this quality analysis is {{confidence}}. I found {{issues.length}} issues. Is my interpretation correct?"
        options:
          - id: confirm
            label: Yes, analysis looks correct
          - id: adjust
            label: Partially correct — see my notes
          - id: reject
            label: No, re-analyze with different parameters
        timeout: 180000
        defaultAction: continue

Reason-stage feedback requests do not block the current cycle (it continues regardless), but the platform stores the response in memory to adjust future reasoning.

Responding to Requests

When an agent raises a feedback request, it appears in a banner on the agent’s page in the HiveMQ Platform, and the network can optionally send a notification. For a controlled action, the agent waits for your answer before deciding whether to execute or skip. For step-by-step information on how you give feedback, see Respond to a Feedback Request.

Field Reference

Autonomy Block

Field Required Description

Field	Required	Description
`defaultLane`	Yes	The agent applies every action without a `requireFeedback` override.
`autonomous.confidenceThreshold`	No	The agent acts autonomously when confidence meets or exceeds this value.
`supervised.confidenceThreshold`	No	The agent waits the configured `supervised.timeout` period for a human response before applying the selected timeout action when confidence meets or exceeds this value.
`supervised.timeout`	No	The time in milliseconds that the agent waits for feedback before it applies `defaultAction`.
`supervised.defaultAction`	No	The timeout action: `continue`, `skip`, or `reject`.
`controlled.timeout`	No	The time in milliseconds that the agent waits for approval. Default: 300000 / 5 min.
`controlled.defaultAction`	No	The timeout action: `continue`, `skip`, or `reject`. Set `reject` for controlled actions.

defaultLane

Yes

The agent applies every action without a requireFeedback override.

autonomous.confidenceThreshold

The agent acts autonomously when confidence meets or exceeds this value.

supervised.confidenceThreshold

The agent waits the configured supervised.timeout period for a human response before applying the selected timeout action when confidence meets or exceeds this value.

supervised.timeout

The time in milliseconds that the agent waits for feedback before it applies defaultAction.

supervised.defaultAction

The timeout action: continue, skip, or reject.

controlled.timeout

The time in milliseconds that the agent waits for approval. Default: 300000 / 5 min.

controlled.defaultAction

The timeout action: continue, skip, or reject. Set reject for controlled actions.

requireFeedback Fields

Field Required Description

Field	Required	Description
`condition`	No	An expression that the agent evaluates against its state. If the expression evaluates to `false`, the agent skips the feedback request for the cycle. Use `"true"` to always request feedback and `"false"` to never request feedback.
`priority`	No	Sets the display order in the feedback dashboard: `critical`, `high`, `normal`, or `low`.
`question`	Yes	The question that the platform shows to the person. Supports `{{variable}}` interpolation.
`options`	Yes	The response options. At least one response option is required.
`timeout`	No	The time in milliseconds that the agent waits before it applies `defaultAction`.
`defaultAction`	No	The timeout action: `continue`, `skip`, or `reject`.

condition

An expression that the agent evaluates against its state. If the expression evaluates to false, the agent skips the feedback request for the cycle. Use "true" to always request feedback and "false" to never request feedback.

priority

Sets the display order in the feedback dashboard: critical, high, normal, or low.

question

Yes

The question that the platform shows to the person. Supports {{variable}} interpolation.

options

Yes

The response options. At least one response option is required.

timeout

The time in milliseconds that the agent waits before it applies defaultAction.

defaultAction

The timeout action: continue, skip, or reject.

Response Option Fields

Field Required Description

Field	Required	Description
`id`	Yes	A unique identifier. The platform stores the identifier in `memory.feedbackHistory`.
`label`	Yes	The button text that the dashboard shows to the person.
`riskLevel`	No	The risk of the outcome if the person selects this option: `low`, `medium`, `high`, or `critical`. The dashboard shows the value as a badge on the option.

id

Yes

A unique identifier. The platform stores the identifier in memory.feedbackHistory.

label

Yes

The button text that the dashboard shows to the person.

riskLevel

The risk of the outcome if the person selects this option: low, medium, high, or critical. The dashboard shows the value as a badge on the option.

How defaultAction Sets Supervised vs Controlled

For an action with a requireFeedback block, the defaultAction value determines whether the action behaves as supervised or controlled:

Configuration What happens

Configuration	What happens
No `requireFeedback`	The agent uses the `defaultLane` setting.
`requireFeedback` with `defaultAction: continue`	Supervised: The agent submits the request, and the action proceeds when a human responds or the timeout elapses.
`requireFeedback` with `defaultAction: reject`	Controlled: The agent waits for a human response and rejects the action if the timeout elapses.

No requireFeedback

The agent uses the defaultLane setting.

requireFeedback with defaultAction: continue

Supervised: The agent submits the request, and the action proceeds when a human responds or the timeout elapses.

requireFeedback with defaultAction: reject

Controlled: The agent waits for a human response and rejects the action if the timeout elapses.

Complete Example: Three Lanes in One Agent

The example agent uses all three lanes: autonomous logging, a supervised threshold adjustment, and a controlled line stop:

autonomy:
  defaultLane: supervised
  lanes:
    autonomous:
      confidenceThreshold: 0.95
    supervised:
      confidenceThreshold: 0.7
      timeout: 300000
      defaultAction: continue
    controlled:
      timeout: 600000
      defaultAction: reject

stages:
  actuate:
    substages:
      # Lane 1 — Autonomous: logs observations, no feedback needed
      - type: execute
        name: log-observations
        executors:
          - type: mqtt_publish
            connection: factory-mqtt
            topic: factory/quality/observations
            payload:
              type: observation
              metrics: '${action.params}'
              timestamp: '${now}'

      # Lane 2 — Supervised: adjusts thresholds, asks the operator to review
      - type: execute
        name: adjust-thresholds
        executors:
          - type: mqtt_publish
            connection: factory-mqtt
            topic: factory/quality/threshold-updates
            payload:
              metricName: '${action.params.metricName}'
              newThreshold: '${action.params.newThreshold}'

        requireFeedback:
          condition: 'true'
          priority: normal
          question: "I adjusted the threshold for {{action.params.metricName}} from {{action.params.oldThreshold}} to {{action.params.newThreshold}}. Was this appropriate?"
          options:
            - id: approve
              label: Good adjustment
            - id: revert
              label: Revert — threshold was fine
              riskLevel: medium
            - id: modify
              label: Adjust further
              riskLevel: low
          timeout: 300000
          defaultAction: continue      # Supervised: continue if no response

      # Lane 3 — Controlled: line stop BLOCKS for human approval
      - type: execute
        name: emergency-line-stop
        executors:
          - type: mqtt_publish
            connection: factory-mqtt
            topic: factory/line-control/stop
            payload:
              type: emergency-stop
              severity: critical
              message: '${action.params.message}'
              timestamp: '${now}'

        requireFeedback:
          condition: 'true'
          priority: critical
          question: "CRITICAL: I need to stop the production line. Metric '{{action.params.metricName}}' has failed quality checks. Confidence: {{confidence}}. Approve?"
          options:
            - id: approve
              label: Approve Line Stop
              riskLevel: high
            - id: reject
              label: Reject — continue production
              riskLevel: high
            - id: investigate
              label: Hold — send technician first
              riskLevel: medium
          timeout: 600000
          defaultAction: reject        # Controlled: REJECT if no response

Next Steps

Respond to a Feedback Request: Act on the requests this oversight configuration raises. This is the other half of the human-in-the-loop loop workflow.
Configure an Agent: Review the rest of the agent configuration that oversight is part of.
Deploy an Agent: Deploy the agent so its oversight rules take effect.