TorkTORK
Docs/Phase 5 Features

Human-in-the-Loop (HITL)

New in v0.9

Enforce human oversight for high-risk AI agent actions. Require approval for sensitive operations and prevent automation abuse.

Overview

HITL (Human-in-the-Loop) enforcement ensures that humans maintain oversight over AI agent actions. It provides approval workflows for sensitive operations and protection against automation abuse attacks.

This is a cloud feature
An approval queue has to outlive the process that raised it, so HITL runs server-side. Reach it with @torknetwork/sdk (npm install @torknetwork/sdk, entry class TorkClient) or the REST API directly. The on-device tork-governance family is a different package — it exports Tork, decides locally and synchronously, and has no approval queue. There is no Python cloud SDK, so the Python examples below use requests with a Bearer token.

Approval Workflows

Require human approval for sensitive or high-risk actions

Velocity Limits

Prevent approval fatigue by limiting approval rates

Slicing Detection

Detect attempts to bypass controls through multiple small requests

Cool-down Periods

Enforce breaks after high activity to prevent burnout

Security Consideration
HITL is designed to prevent "slicing attacks" where an attacker breaks a large harmful action into many small, individually harmless requests that collectively bypass controls.

Request Approval

Request human approval before executing a high-risk action:

python
# HITL is a cloud feature — approvals are queued server-side by Tork.
# There is no Python cloud SDK, so call the REST API with a Bearer token.
import os, requests

TORK_API = "https://tork.network/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TORK_API_KEY']}"}

# Request approval for a high-risk action
r = requests.post(f"{TORK_API}/approvals", headers=HEADERS, json={
    "agent_id": "agent-1",
    "tool_name": "delete_user_data",
    "target": "user-123",
    "parameters": {
        "data_types": ["profile", "history", "preferences"]
    },
    "expires_in_minutes": 60,  # Auto-expire after 60 minutes
})

approval = r.json()
print(approval["approval_id"])
print(approval["status"])      # 'pending'
print(approval["expires_at"])

Check Approval Status

Poll for the approval decision or use webhooks for real-time notifications:

python
import time

approval_id = approval["approval_id"]

# Poll for decision
while True:
    r = requests.get(f"{TORK_API}/approvals", headers=HEADERS)
    current = next(a for a in r.json() if a["approval_id"] == approval_id)

    if current["status"] == "approved":
        print(f"Approved by: {current['reviewed_by']}")
        print(f"Reason: {current['review_reason']}")
        # Proceed with the action
        delete_user_data(user_id="user-123")
        break

    elif current["status"] == "rejected":
        print(f"Rejected by: {current['reviewed_by']}")
        print(f"Reason: {current['review_reason']}")
        # Handle rejection
        notify_requester("Your request was rejected")
        break

    elif current["status"] == "expired":
        print("Request expired without decision")
        break

    else:  # pending
        print("Still waiting for approval...")
        time.sleep(30)  # Wait 30 seconds before checking again

Slicing Attack Detection

Slicing attacks attempt to bypass HITL controls by:

  • Making many small requests that individually seem harmless
  • Rapid-fire approvals to exhaust the approver
  • Aggregating value across multiple requests to exceed limits
Illustrative API
Slicing detection, velocity limits, cool-downs and HITL config are available today through the Tork MCP server (tork_hitl_detect_slicing, tork_hitl_check_velocity, tork_hitl_check_cooldown, tork_hitl_get_config). The hitl.* helper shown in the remaining examples on this page is illustrative of the shape of those calls — it is not a class exported by any published SDK. Check the MCP tool schemas for exact arguments before building against it.
python
# Detect slicing attacks
result = hitl.detect_slicing_attack(
    agent_id="agent-1",
    approver_id="approver-1",
    time_window_minutes=60
)

if result['attackDetected']:
    print(f"Slicing attack detected!")
    print(f"Confidence: {result['confidence']}")

    for alert in result['alerts']:
        print(f"  Alert: {alert['type']}")
        print(f"  Description: {alert['description']}")
        print(f"  Evidence: {alert['evidence']}")

    # Take protective action
    hitl.pause_approvals(agent_id="agent-1", duration_minutes=30)
else:
    print("No attack patterns detected")
Attack Types Detected
Tork detects several attack patterns: velocity abuse, value aggregation, temporal clustering, approver fatigue, and pattern repetition.

Velocity Limits

Velocity limits prevent approvers from being overwhelmed with too many requests:

python
# Check if approver is within velocity limits
velocity = hitl.check_velocity(
    agent_id="agent-1",
    approver_id="approver-1"
)

print(f"Approvals this hour: {velocity['currentCount']}/{velocity['maxApprovals']}")
print(f"Approvals today: {velocity['dailyCount']}/{velocity['dailyMax']}")
print(f"Can approve: {velocity['allowed']}")

if not velocity['allowed']:
    print(f"Reason: {velocity['reason']}")
    print(f"Reset at: {velocity['resetsAt']}")

Cool-down Periods

Cool-down periods are automatically triggered after high approval activity:

python
# Check if in cool-down
cooldown = hitl.is_in_cooldown(
    agent_id="agent-1",
    approver_id="approver-1"
)

if cooldown['active']:
    print(f"In cool-down until: {cooldown['endsAt']}")
    print(f"Reason: {cooldown['reason']}")
    print(f"Triggered by: {cooldown['trigger']}")

    # Wait for cool-down or escalate
    if is_urgent:
        escalate_to_manager(request)
else:
    print("No cool-down active, can proceed")

# Manually trigger cool-down if needed
hitl.trigger_cooldown(
    agent_id="agent-1",
    approver_id="approver-1",
    duration_minutes=30,
    reason="Manual security review"
)

Configuration

Configure HITL settings for your organization:

python
# Get HITL configuration
config = hitl.get_config("agent-1")

# Update configuration
hitl.update_config(
    agent_id="agent-1",
    config={
        "enabled": True,
        "requireApprovalFor": [
            "delete_data",
            "modify_permissions",
            "send_external_email",
            "access_pii"
        ],
        "riskThresholds": {
            "low": {"autoApprove": True},
            "medium": {"requireApproval": True, "timeout": 60},
            "high": {"requireApproval": True, "timeout": 30, "notifyAdmin": True},
            "critical": {"requireApproval": True, "timeout": 15, "notifyAdmin": True, "requireMFA": True}
        },
        "velocityLimits": {
            "perHour": 10,
            "perDay": 50
        },
        "cooldownConfig": {
            "threshold": 5,  # Trigger after 5 approvals in 15 min
            "duration": 30   # 30 minute cool-down
        }
    }
)

MCP Tools

ToolDescription
tork_hitl_request_approvalRequest human approval for an action
tork_hitl_check_statusCheck the status of an approval request
tork_hitl_check_velocityCheck velocity limits for an approver
tork_hitl_detect_slicingDetect slicing attack patterns
tork_hitl_cooldown_statusCheck or manage cool-down periods

Related Documentation

Approval Queue

Manage approvals in the Admin Console

Learn more

Policy Engine

Define which actions require approval

Learn more