Human

Human-in-the-loop integration for approvals, reviews, creative work, and judgment calls

First-class support for human participation in AI-powered workflows. Not everything can or should be automated—humans bring judgment, creativity, empathy, and accountability that AI cannot replicate.

Why Human-in-the-Loop?

Some tasks inherently require human involvement:

Judgment calls: Decisions with ethical, legal, or strategic implications
Creative work: Writing, design, and ideation that requires human creativity
Approvals: Sign-offs that carry accountability
Edge cases: Situations AI hasn't been trained to handle
Quality assurance: Final verification of AI-generated outputs
Relationship management: Interactions requiring empathy and nuance

import { human, approval, review } from 'human-in-the-loop'

const humanReview = human({
  name: 'content-review',

  task: {
    description: 'Review AI-generated content for accuracy and tone',
    estimatedTime: '10m',
    skills: ['content-writing', 'brand-guidelines'],
  },

  input: z.object({
    content: z.string(),
    context: z.string(),
    targetAudience: z.string(),
  }),

  output: z.object({
    approved: z.boolean(),
    edits: z.string().optional(),
    feedback: z.string(),
  }),

  ui: 'content-review-form',
})

Integration Points

Approval Gates

Insert human approvals into workflows:

const purchaseWorkflow = workflow({
  name: 'purchase-approval',

  steps: [
    validateRequest,
    checkBudget,

    // Human approval gate
    human.approval({
      name: 'manager-approval',
      assignTo: ({ input }) => input.requester.manager,
      showContext: ['request', 'budgetStatus'],
      timeout: '48h',
      escalateTo: 'department-head',
    }),

    processPayment,
    notifyVendor,
  ],
})

Review Cycles

Humans review and refine AI outputs:

const contentPipeline = workflow({
  name: 'content-creation',

  steps: [
    // AI generates draft
    generateDraft,

    // Human reviews
    human.review({
      name: 'editorial-review',
      assignTo: { role: 'editor' },
      actions: ['approve', 'request-changes', 'reject'],
      onRequestChanges: (feedback) => regenerateDraft(feedback),
      maxIterations: 3,
    }),

    // Final human sign-off
    human.approval({
      name: 'final-approval',
      assignTo: { role: 'content-lead' },
    }),

    publish,
  ],
})

Escalation Paths

AI handles routine cases, humans handle exceptions:

const supportFlow = workflow({
  name: 'customer-support',

  steps: [
    classifyTicket,
    attemptAutoResponse,

    human.escalation({
      when: [
        'confidence < 0.7',
        'sentiment = negative',
        'topic in [refund, complaint, legal]',
        'customer.tier = enterprise',
      ],
      assignTo: { role: 'support-specialist' },
      context: ['conversation', 'customerProfile', 'aiAnalysis'],
    }),
  ],
})

Human Interfaces

Define how humans interact with tasks:

Forms

const approvalForm = human.form({
  name: 'expense-approval',

  fields: [
    { name: 'decision', type: 'select', options: ['approve', 'reject', 'request-info'] },
    { name: 'notes', type: 'textarea', required: false },
    { name: 'adjustedAmount', type: 'number', showWhen: 'decision === approve' },
  ],

  context: {
    show: ['expense', 'policy', 'history'],
    highlight: ['amount', 'category', 'requester'],
  },
})

Workspaces

const reviewWorkspace = human.workspace({
  name: 'document-review',

  layout: 'split-view',
  panels: [
    { type: 'document-viewer', source: 'input.document' },
    { type: 'annotation-tools' },
    { type: 'ai-suggestions', source: 'context.suggestions' },
    { type: 'decision-form', form: reviewDecisionForm },
  ],
})

Assignment and Routing

Skills-Based Routing

const skillRouting = human.routing({
  strategy: 'skills-match',

  skills: {
    required: ['customer-service'],
    preferred: ['product-knowledge', 'technical-support'],
  },

  factors: {
    availability: 0.4,
    expertise: 0.3,
    workload: 0.2,
    performance: 0.1,
  },
})

Queue Management

const humanQueue = human.queue({
  name: 'review-queue',

  prioritization: [
    { condition: 'deadline < 1h', boost: 3 },
    { condition: 'customer.tier = enterprise', boost: 2 },
    { condition: 'type = escalation', boost: 1.5 },
  ],

  fairness: {
    maxTasksPerPerson: 10,
    rotateAfter: '2h',
    breakReminders: true,
  },
})

Quality and Feedback

Feedback Loops

const feedbackLoop = human.feedback({
  collect: {
    afterCompletion: true,
    sampleRate: 0.2,  // 20% of tasks
    questions: [
      'Was the AI-provided context helpful?',
      'How could the task be improved?',
    ],
  },

  improve: {
    shareWith: 'ai-training-pipeline',
    updatePrompts: true,
    adjustRouting: true,
  },
})

Performance Tracking

const metrics = await human.getMetrics({
  period: 'last-30-days',
  include: [
    'avgResponseTime',
    'accuracy',
    'throughput',
    'satisfaction',
  ],
})

Human + AI Collaboration

The best outcomes come from humans and AI working together:

const collaborativeReview = workflow({
  name: 'collaborative-review',

  steps: [
    // AI does initial analysis
    aiAnalysis,

    // Human reviews with AI assistance
    human.assisted({
      name: 'assisted-review',
      aiAssist: {
        suggestions: true,
        autoComplete: true,
        factCheck: true,
        similarCases: true,
      },
      humanDecides: {
        finalApproval: true,
        edits: true,
        escalation: true,
      },
    }),
  ],
})

Availability and Scheduling

const scheduling = human.schedule({
  workingHours: {
    timezone: 'America/New_York',
    hours: '9:00-17:00',
    days: ['mon', 'tue', 'wed', 'thu', 'fri'],
  },

  outOfHours: {
    queue: true,
    fallback: 'on-call-team',
    urgent: 'page-on-call',
  },

  capacity: {
    targetUtilization: 0.8,
    bufferForUrgent: 0.1,
  },
})

Was this page helpful?

On this page