Human-in-the-Loop (HITL)

Fully autonomous agents aren't always the answer. Learn when and how to keep humans in the loop for safety, compliance, and trust.

Why HITL Matters

96% of AI practitioners consider human oversight important:

• Agents hallucinate actions — misinterpret prompts and overstep boundaries
• Mistakes scale instantly — autonomous errors cascade across systems
• Regulations require it — EU AI Act mandates human oversight for high-risk AI
• Trust is earned — users build confidence gradually, not overnight

Gartner predicts 40% of agentic AI projects may fail by 2027 without proper oversight.

HITL Patterns

1. Approval Gate

Agent proposes, human approves before execution:

def execute_with_approval(action, risk_level):
    if risk_level == "high":
        # Block until human approves
        approval = await request_human_approval(
            action=action,
            context=get_full_context(),
            timeout="24h"
        )
        if not approval.granted:
            return ActionResult(status="rejected", reason=approval.reason)
    
    return execute(action)

Use for: database migrations, production deploys, access control changes, financial transactions.

2. Confidence-Based Routing

Route decisions based on the agent's confidence level:

Confidence Thresholds:
  90%+ → Auto-execute (low risk, high confidence)
  70-90% → Execute with logging (monitor closely)  
  50-70% → Ask for clarification before proceeding
  <50%  → Escalate to human with full context

Target: 10-15% escalation rate for sustainable operations

3. Progressive Autonomy

Start restrictive, grant more autonomy as trust builds:

Level 1: "Suggest Only"
  Agent recommends actions, human executes all

Level 2: "Auto-execute Safe Actions"
  Read-only operations auto-execute
  Write operations require approval

Level 3: "Auto-execute with Exceptions"  
  Most operations auto-execute
  Dangerous operations still need approval

Level 4: "Full Autonomy with Audit"
  Everything auto-executes
  Full audit trail, alerts on anomalies

4. Feedback Loop

Human corrections improve the agent over time:

Agent Action → Human Review → Feedback
     ↑                           │
     └───── Learn & Improve ─────┘

Error Taxonomy (for structured learning):
  - Classification miss  → Improve routing logic
  - Missing context      → Better retrieval
  - Tool failure         → Fix tool or add fallback
  - Policy violation     → Update guardrails

Implementation Strategies

Tool Permission Tiers

tools:
  read_file:     { permission: "auto",     risk: "low" }
  search_code:   { permission: "auto",     risk: "low" }
  edit_file:     { permission: "auto",     risk: "medium" }
  run_tests:     { permission: "auto",     risk: "medium" }
  git_commit:    { permission: "confirm",  risk: "medium" }
  deploy:        { permission: "approve",  risk: "high" }
  delete_data:   { permission: "approve",  risk: "critical" }
  modify_access: { permission: "approve",  risk: "critical" }

import { query } from "@anthropic-ai/claude-agent-sdk";

// Progressive trust levels
// "default"         — Standard permission checks
// "acceptEdits"     — Auto-approve file edits
// "bypassPermissions" — Skip ALL checks (CI/CD only!)
// "plan"            — Planning mode, no execution

const response = query({
  prompt: "Deploy the application to production",
  options: {
    permissionMode: "default",
    allowedTools: ["Read", "Write", "Bash", "AskUserQuestion"],

    canUseTool: async (toolName, input) => {
      // Tier 1: Always allow read-only
      if (["Read", "Grep", "Glob"].includes(toolName)) {
        return { behavior: "allow" };
      }

      // Tier 2: Auto-approve safe writes
      if (toolName === "Write" && !input.file_path?.includes(".env")) {
        return { behavior: "allow" };
      }

      // Tier 3: Block dangerous ops
      if (input.command?.includes("rm -rf /")) {
        return { behavior: "deny", message: "Blocked: system-level delete" };
      }

      // Tier 4: Human confirmation for everything else
      return { behavior: "ask", message: `Approve ${toolName}?` };
    },

    hooks: {
      PermissionRequest: async (input) => {
        console.log(`[AUDIT] Permission requested: ${input.toolName}`);
        await auditLog.write(input);
      }
    }
  }
});

Async Approval Workflows

For long-running agent tasks, approvals should be asynchronous:

1. Agent reaches approval checkpoint
2. Saves full state (context, plan, progress)
3. Sends notification (Slack, email, dashboard)
4. Pauses execution
5. Human reviews and responds (hours/days later)
6. Agent resumes from saved state

Real-World Examples

• Claude Code — Asks for confirmation before shell commands that modify the system. Users can set --dangerously-skip-permissions for Level 4 autonomy
• GitHub Copilot — Creates PRs for review instead of directly pushing to main. Humans review agent PRs like junior developer code
• Cursor — Shows diffs and requires explicit "Accept" before applying multi-file changes

Measuring HITL Effectiveness

• Escalation rate — Target 10-15%. Too high = agent is useless; too low = risky
• Resolution time — How fast humans resolve escalated items
• Override rate — How often humans reject agent proposals (high = bad agent)
• Feedback utilization — Does the agent actually improve from corrections?
• User trust score — Over time, users should move toward higher autonomy levels

Best Practices

• Default to caution — Start at Level 1 and let users opt into more autonomy
• Make approvals effortless — One-click approve/reject with full context visible
• Preserve agent state — Don't lose work when paused for approval
• Track everything — Audit trail for compliance and debugging
• Treat HITL like SRE — Define thresholds, measure throughput, improve over time
• Plan for scale — As adoption grows, human reviewers become a bottleneck. Use feedback to reduce escalation rate

Next Steps

• Production Agents — Taking HITL-enabled agents to production
• Evaluation — Measuring agent safety and reliability