Set Human Oversight

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

When you leave autonomy unset, every action executes immediately with no feedback request. Add an autonomy configuration to put a human in the loop for some (or all) of the agent’s actions.

Oversight is one half of the human-in-the-loop loop. Here you decide which actions need a person and how long the agent waits for an answer. The other half is to act on the requests it raises. See Respond to a Feedback Request.

The Three Autonomy Lanes

Every action an agent takes runs in one of three lanes. The lane decides how much human involvement is required before the action executes.

Lane Behavior

Autonomous

The agent acts independently, without human approval. Use for low-risk, easily corrected actions such as logging readings, publishing status updates, and other read-only observations.

Supervised

The agent proposes an action and raises it for a human to review. The action proceeds after the operator responds. If no one responds within the timeout, it proceeds on its own (per the lane’s default action). Review is requested, not strictly required. Use for medium-confidence, reversible decisions such as threshold adjustments, alert-routing changes, and configuration updates.

Controlled

A human must explicitly approve every action before it runs. Nothing happens until an operator responds. Use for high-impact actions such as stopping a production line, deleting records, or sending customer-facing communications.

Choosing a Lane

Start from the action’s risk level and adjust based on context:

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

Other factors to consider:

  • Agent confidence: A high-confidence autonomous action is safer than a low-confidence supervised one. Use confidenceThreshold to escalate to a stricter lane automatically when confidence is low.

  • Reversibility: Easily undone actions can be autonomous. Hard-to-reverse actions belong in the controlled lane.

  • 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 to supervised.

Set the Default Lane

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 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: every timeout in the autonomy block is in milliseconds. 300000 = 5 minutes, 600000 = 10 minutes.

Override the Lane for a Specific Action

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 Lane for a Reasoning Step

You can also add requireFeedback to a Reason substage, so operators review 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 own page in the HiveMQ Platform, and the network can optionally send a notification. For a controlled action, the agent waits for the operator’s answer before deciding whether to execute or skip. For the operator’s step-by-step, see Respond to a Feedback Request.

Field Reference

Autonomy Block

Field Required Description

defaultLane

Yes

Applied to every action without a requireFeedback override

autonomous.confidenceThreshold

No

Act autonomously when confidence meets or exceeds this value

supervised.timeout

No

Milliseconds to wait for feedback before applying defaultAction

supervised.defaultAction

No

continue, skip, or reject when the timeout elapses

controlled.timeout

No

Milliseconds to wait for human approval (default: 300000 / 5 min)

controlled.defaultAction

No

continue, skip, or reject on timeout. Strongly recommend reject for controlled actions

requireFeedback Fields

Field Required Description

condition

No

Expression evaluated against agent state. Skip the feedback request this cycle if it is false. Use "true" to always request feedback.

priority

No

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

question

Yes

The question shown to the operator. Supports {{variable}} interpolation.

options

Yes

At least one response option is required.

timeout

No

Milliseconds to wait before applying defaultAction.

defaultAction

No

continue, skip, or reject when the timeout elapses.

Response Option Fields

Field Required Description

id

Yes

Unique identifier, stored in memory.feedbackHistory

label

Yes

Button text shown to the operator in the dashboard

riskLevel

No

low, medium, high, or critical, displayed in the UI to help operators understand the consequence

How defaultAction Sets Supervised vs Controlled

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

Configuration What happens

No requireFeedback

Uses the defaultLane setting

requireFeedback with defaultAction: continue

Supervised: The agent raises the request, and the action proceeds when the operator responds or the timeout elapses

requireFeedback with defaultAction: reject

Controlled: Blocks until a response, then rejects the action if the timeout elapses

Complete Example: Three Lanes in One Agent

This 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