@the-handover/sdk

Human-in-the-loop approval SDK for AI agents. Stop agents from taking destructive actions without human sign-off.

Install

npm install @the-handover/sdk

Quick Start

import { HandoverClient, DecisionDenied } from '@the-handover/sdk';

const client = new HandoverClient({ apiKey: 'ho_live_...' });

try {
  const decision = await client.approve({
    action: 'Delete 500 user records',
    approver: '[email protected]',
    urgency: 'critical',
  });
  console.log(`Approved by ${decision.resolved_by}`);
  // Proceed with action...
} catch (err) {
  if (err instanceof DecisionDenied) {
    console.log('Denied — agent stopped');
    // Agent CANNOT proceed
  }
}

Rich Responses

import { HandoverClient, ChooseResponse } from '@the-handover/sdk';

const client = new HandoverClient({ apiKey: 'ho_live_...' });

const decision = await client.approve({
  action: 'Select deployment target',
  approver: '[email protected]',
  response_type: {
    type: 'choose',
    choices: ['staging', 'production', 'canary'],
    label: 'Which environment?',
  },
});
console.log(`Deploying to: ${decision.response_data?.chosen}`);

OpenAI Integration

import { HandoverClient } from '@the-handover/sdk';
import { handoverToolDefinition, handleHandoverCall } from '@the-handover/sdk/openai';

const client = new HandoverClient({ apiKey: 'ho_live_...' });

// Add to your tools
const tools = [handoverToolDefinition()];

// Handle tool calls
if (toolCall.function.name === 'request_human_approval') {
  const result = await handleHandoverCall(client, toolCall.function.arguments, {
    approver: '[email protected]',
  });
}

LangChain Integration

import { HandoverClient } from '@the-handover/sdk';
import { HandoverApprovalTool } from '@the-handover/sdk/langchain';

const client = new HandoverClient({ apiKey: 'ho_live_...' });
const tool = new HandoverApprovalTool({
  client,
  approver: '[email protected]',
});

Docs

Full documentation at thehandover.xyz/docs