HumanLayer TypeScript SDK

The official TypeScript SDK for HumanLayer, providing human oversight for AI applications.

Installation

npm install humanlayer

Key Features

• Human approval workflows for sensitive operations
• Structured feedback collection from humans
• Multiple contact channels (Slack, Email, etc.)
• Full TypeScript support
• Async/await API
• Framework integrations

Basic Usage

import { humanlayer } from 'humanlayer'

const hl = humanlayer({
  runId: 'my-agent',
  contactChannel: {
    slack: {
      channelOrUserId: 'C123456',
      contextAboutChannelOrUser: 'the compliance team',
    },
  },
})

// Require approval for sensitive functions
const sendEmail = hl.requireApproval(async (to: string, subject: string) => {
  // Email sending logic here
})

// Get human input during execution
const support = hl.humanAsTool({
  responseOptions: [
    { name: 'approve', title: 'Approve' },
    { name: 'deny', title: 'Deny' },
  ],
})

Framework Support

• OpenAI function calling
• LangChain.js
• Vercel AI SDK

Contact Channels

Configure how humans are contacted:

// Slack
const slackChannel = {
  slack: {
    channelOrUserId: 'C123456',
    contextAboutChannelOrUser: 'the support team',
  },
}

// Email
const emailChannel = {
  email: {
    address: 'support@company.com',
    contextAboutUser: 'the support team',
  },
}

Response Options

Structure human responses:

const options = [
  {
    name: 'approve',
    title: 'Approve',
    description: 'Approve the action',
  },
  {
    name: 'deny',
    title: 'Deny',
    description: 'Deny with feedback',
    promptFill: 'Denied because...',
  },
]

const approval = await hl.requireApproval(myFunction, {
  responseOptions: options,
})

Error Handling

The SDK provides detailed error types:

try {
  await hl.requireApproval(myFunction)()
} catch (error) {
  if (error instanceof HumanLayerException) {
    // Handle HumanLayer-specific errors
    console.error('HumanLayer error:', error.message)
  } else {
    // Handle other errors
    console.error('Unexpected error:', error)
  }
}

Environment Variables

Required:

• HUMANLAYER_API_KEY: Your HumanLayer API key

Optional:

• HUMANLAYER_API_BASE: API base URL (default: https://api.humanlayer.dev/humanlayer/v1)
• HUMANLAYER_HTTP_TIMEOUT_SECONDS: HTTP timeout in seconds (default: 30)

Examples

See the examples directory for complete working examples:

• OpenAI function calling
• Email classification
• Vercel AI SDK integration

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Type check
npm run check

License

Apache 2.0 - see LICENSE

HumanLayer TS changelog

0.7.2

--END--

From this point on, python and typescript will be released together. Any further changes to the typescript SDK will be inlcuded in the repos main CHANGELOG.md.

0.7.1

Features

• Support for interactive: boolean on ReponseOption - setting to false will cause prompts to be written in by default

  • BREAKING - if you are using prompt_fill on ReponseOption, and want to give users the option to edit prompt, you will need to add interactive=true

• API now returns HumanContactStatus.response_option_name and FunctionCallStatus.reject_option_name on objects for consuming human classification/steering reponses with deterministic (non-llm) code

Updates

• Changed default http client timeout to 30s in python clients

Examples

• Added ts_email_classifier example in ./examples/ts_email_classifier
• Added in-depth examples docs in ./examples/README.md

0.7.0

• TS - Fix a bug in fetchHumanApproval with callId resolution
• TS - remove env var for HUMANLAYER_APPROVAL_METHOD
• TS - add non-constructor entrypoint import { humanlayer } from "humanlayer" -- humanlayer(params) is a wrapper around new HumanLayer(params)
• DEV - update makefile for building/testing TS more regularly

0.6.1

• Fix - Add more comprehensive module exports for CommonJS and ES modules
• Enhancement - add lower-level create/fetch methods to typescript package
• Enhancement - expand EmailContactChannel to support experimental subject and message id fields

0.5.8

Enhancements

• Add support for client-side usage of respond methods for responding to function calls / human contacts. This enables building custom approval UX in your web app / client of choice.
• Added some contrived examples for client-side approvals in TS and PY