Human-in-the-Loop (HITL)

What is HITL?

Human-in-the-Loop (HITL) is a governance pattern where agent actions are paused and queued for human approval before execution. This is the strictest form of oversight, ideal for high-risk or irreversible actions.

When to Use HITL

• Financial transactions - Payments, transfers, refunds
• Data modifications - Deletes, updates to critical data
• External communications - Emails, messages to customers
• System changes - Configuration updates, deployments
• Compliance-sensitive - Actions requiring audit trails

Enabling HITL

Via SDK

from turingpulse_sdk import instrument, GovernanceDirective

@instrument(
    name="financial-agent",
    governance=GovernanceDirective(
        hitl=True,
        reviewers=["finance@company.com", "compliance@company.com"],
        escalation_channels=["slack://finance-alerts"],
        auto_escalate_after_seconds=3600,
    )
)
def process_refund(user_id: str, amount: float, reason: str):
    """This function will pause for approval before executing."""
    return payment_service.refund(user_id, amount, reason)

Via UI

1. Navigate to Governance → Policies
2. Click Create Policy
3. Select Human-in-the-Loop (HITL)
4. Choose the workflow to apply
5. Configure reviewers and timeouts
6. Save and enable

Conditional HITL

Apply HITL only when certain conditions are met by configuring condition-based policies in the TuringPulse UI:

1. Navigate to Governance → Policies
2. Create a HITL policy for your workflow
3. Set conditions (e.g., cost > $100, risk score > 0.8, action type = "delete")
4. The platform evaluates conditions and only triggers HITL when matched

HITL Workflow

1. Action Triggered

When an instrumented function is called with HITL enabled:

• Execution pauses before the function body runs
• A review request is created in TuringPulse
• Reviewers are notified via configured channels

2. Review Queue

Reviewers see the pending action in the Review Queue:

• Action Details - Function name, arguments, metadata
• Context - User info, session history, risk indicators
• Workflow Info - Which agent/workflow triggered

3. Review Actions

• Approve - Allow the action to proceed
• Reject - Block the action (raises exception)
• Modify - Edit parameters and approve
• Escalate - Forward to another reviewer

4. Execution Resumes

After approval, the function executes normally. After rejection, a GovernanceBlockedError is raised.

Handling Rejections

from turingpulse_sdk import instrument, GovernanceDirective
from turingpulse_sdk import GovernanceBlockedError

@instrument(
    name="financial-agent",
    governance=GovernanceDirective(hitl=True, reviewers=["admin@company.com"])
)
def process_refund(user_id: str, amount: float):
    return payment_service.refund(user_id, amount)

# Handle rejection gracefully
try:
    result = process_refund("user-123", 500.00)
    print(f"Refund processed: {result}")
except GovernanceBlockedError as e:
    print(f"Refund rejected: {e.reason}")
    print(f"Rejected by: {e.reviewer}")
    # Notify user, log, etc.

Timeouts and Escalation

Escalation

If a review isn't completed within the timeout, escalate to additional reviewers:

governance = GovernanceDirective(
    hitl=True,
    reviewers=["level1@company.com"],
    auto_escalate_after_seconds=1800,  # Escalate after 30 minutes
    escalation_channels=["pagerduty://critical", "slack://managers"],
)

HITL Configuration

Best Practices

• Use conditions - Apply HITL conditionally to avoid overwhelming reviewers with low-risk actions.
• Set appropriate timeouts - Balance urgency with reviewer availability.
• Configure escalation - Ensure actions don't get stuck if primary reviewers are unavailable.
• Provide context - Include relevant metadata to help reviewers make informed decisions.
• Monitor queue depth - Track review queue size to ensure adequate reviewer capacity.

Next Steps

• Human-after-the-Loop (HATL)
• Human-on-the-Loop (HOTL)
• Review Queue
• Review Policies