Skip to main content

​
Installation

yarn add @humaniq/js

npm install @humaniq/js

bun install @humaniq/js

​
Basic Usage

​
1. Import the SDK

import { needsHumanApproval } from "@humaniq/js";

​
2. Wrap Your Agent’s Actions

// your tool that needs human approval. Can be anything
const sendEmailTool = async() => {
  //...
}
// Wrap a function that needs approval before execution
// defaults to an async approval request so your agent will continue after sending an approval request
// to a human.
const sendEmail = needsHumanApproval({actionId: "send-email"},  sendEmailTool);

// Like normally, add your tool definitions to your LLM however you normally do, you don't need to change
// anything there.
// ...


// Now jus use the wrapped tool in your tool handler for tool calling. Works with OpenAI and any other
// Agent frameworks that support tools
export const executeTool = async (
  toolName: string,
  toolArguments: any
) => {
  switch (toolName) {
    case 'sendEmail':
      // use the wrapped humaniq tool
      return sendEmail(toolArguments)
    // other tools
  }
}

​
Add Form Fields

Present approvers with context and editable fields: 
const processRefund = needsHumanApproval({
  type: 'sync',
  title: 'Refund Request',
  ask: (args) => `Review refund request for order ${args.orderId}`,
  approvalArguments: {
    amount: {
      type: 'number',
      value: args.amount,
      label: 'Refund Amount',
      editable: true
    },
    reason: {
      type: 'string',
      value: args.reason,
      label: 'Refund Reason',
      editable: true
    }
  }
})

​
Auto-approve Rules

Automatically approve requests that meet certain criteria: 
const approveAccess = needsHumanApproval({
  type: "sync",
  title: "Access Request",
  ask: (args) => `Approve access to ${args.resource}?`,
  // Auto-approve during business hours
  autoApprove: async (args) => {
    const hour = new Date().getHours();
    return hour >= 9 && hour <= 17;
  },
  // Only seek approvals for production
  shouldSeekApprovals: async (args) => {
    return args.environment === "production";
  },
});

​
Handle Approval States

Add callbacks to handle approval states: 
const criticalOperation = needsHumanApproval({
  type: 'sync',
  title: 'Critical Operation',
  ask: 'Approve system changes?',
  // Callback URLs for different states
  onApprovedCallbackUrl: 'https://api.your-app.com/webhooks/approved',
  onRejectedCallbackUrl: 'https://api.your-app.com/webhooks/rejected',
  onExpiredCallbackUrl: 'https://api.your-app.com/webhooks/expired'
})

​
Multiple Approvers

Route approvals to specific team members: 
const deployCode = needsHumanApproval({
  type: 'sync',
  title: 'Code Deployment',
  ask: 'Approve production deployment?',
  approvers: [
    { name: 'Engineering Lead', email: '[email protected]' },
    { name: 'DevOps Manager', email: '[email protected]' }
  ],
});

​
Next Steps

View Examples

Explore industry-specific examples and patterns

​
Troubleshooting

Synchronous approvals default to a 20-second timeout. Adjust this with the syncTimeout option:
needsHumanApproval({
  type: 'sync',
  syncTimeout: 60000  // 60 seconds
})
All approval functions throw standard errors that can be caught:
try {
  await processRefund({ amount: 100 })
} catch (error) {
  if (error.code === 'APPROVAL_REJECTED') {
    // Handle rejection
  }
}