JSPM

digital-workers

2.0.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 20
  • Score
    100M100P100Q53362F
  • License MIT

Common abstract interface over AI Agents and Humans

Package Exports

  • digital-workers

Readme

digital-workers

Abstract interface for organizing digital work, independent of whether AI or humans perform individual tasks.

Overview

Digital workers provides the foundational abstraction for structuring and organizing work in the digital enterprise. It defines a unified interface that both AI agents and humans implement, enabling you to design workflows without coupling them to specific execution strategies.

Why This Abstraction Matters

When building AI-powered systems, you face a fundamental question: who should do this task? Sometimes it's an AI agent operating autonomously. Sometimes it requires human judgment. Often it's a mix of both.

digital-workers lets you define work in terms of what needs to happen, not who does it:

// This workflow doesn't care if alice is an AI agent or a human
await worker$.approve('Deploy v2.0 to production', alice, { via: 'slack' })

The same Worker interface works whether alice is:

  • A human product manager who gets a Slack notification
  • An AI agent that evaluates deployment criteria autonomously
  • A supervised AI that escalates to humans for high-risk decisions

Package Relationships

┌─────────────────────────────────────────────────────────┐
│                    ai-workflows                         │
│              (orchestrates work execution)              │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  digital-workers                        │
│         (abstract interface for work & workers)         │
└────────────────────────┬────────────────────────────────┘
                         │
           ┌─────────────┴─────────────┐
           ▼                           ▼
┌─────────────────────┐   ┌─────────────────────────────┐
│  autonomous-agents  │   │     human-in-the-loop       │
│  (AI implementation)│   │   (human implementation)    │
└─────────────────────┘   └─────────────────────────────┘
  • digital-workers: Defines the abstract Worker interface, action types, and communication patterns
  • autonomous-agents: Implements Worker for AI agents with autonomous decision-making
  • human-in-the-loop: Implements Worker for humans with approval workflows and notifications

Installation

pnpm add digital-workers

Core Concepts

The Worker Abstraction

A Worker is the unified interface for any entity that can perform work—whether AI or human. This abstraction enables you to:

  1. Design workflows once - Define your business logic without hardcoding execution strategy
  2. Swap implementations - Start with humans, transition to AI agents as they prove reliable
  3. Mix freely - Teams can include both AI agents and humans working together
  4. Route dynamically - Assign tasks based on availability, capability, or risk level

Worker

A Worker is the common interface for both AI agents and humans:

import type { Worker } from 'digital-workers'

const alice: Worker = {
  id: 'user_alice',
  name: 'Alice',
  type: 'human',
  status: 'available',
  contacts: {
    email: 'alice@company.com',
    slack: { workspace: 'acme', user: 'U123' },
    phone: '+1-555-1234',
  },
}

const codeReviewer: Worker = {
  id: 'agent_reviewer',
  name: 'Code Reviewer',
  type: 'agent',
  status: 'available',
  contacts: {
    api: { endpoint: 'https://api.internal/reviewer', auth: 'bearer' },
    webhook: { url: 'https://hooks.internal/reviewer' },
  },
}

Contacts

Workers have contacts that define how they can be reached:

import type { Contacts } from 'digital-workers'

const contacts: Contacts = {
  email: 'team@company.com',                    // Simple string
  slack: { workspace: 'acme', channel: '#eng' }, // Config object
  phone: { number: '+1-555-0000', voice: 'en-US' },
  sms: '+1-555-0001',
  teams: { tenant: 'company', channel: 'Engineering' },
  discord: { server: 'dev-community', channel: 'support' },
  telegram: { chat: '@company_support' },
  web: { url: 'https://dashboard.company.com', pushEnabled: true },
  api: { endpoint: 'https://api.company.com', auth: 'bearer' },
  webhook: { url: 'https://hooks.company.com/events' },
}

Team

Teams group workers with shared contacts:

import { Team } from 'digital-workers'

const engineering = Team({
  id: 'team_eng',
  name: 'Engineering',
  members: [alice, bob, codeReviewer],
  contacts: {
    slack: '#engineering',
    email: 'eng@company.com',
  },
  lead: alice,
})

Worker Actions

Worker actions are durable workflow actions with Actor/Object semantics that integrate with ai-workflows:

import { Workflow } from 'ai-workflows'
import { registerWorkerActions, withWorkers } from 'digital-workers'

const workflow = Workflow($ => {
  registerWorkerActions($)
  const worker$ = withWorkers($)

  $.on.Expense.submitted(async (expense) => {
    // Notify finance team
    await worker$.notify(finance, `New expense: ${expense.amount}`)

    // Request approval from manager
    const approval = await worker$.approve(
      `Expense: $${expense.amount} for ${expense.description}`,
      manager,
      { via: 'slack' }
    )

    if (approval.approved) {
      await worker$.notify(expense.submitter, 'Your expense was approved!')
    }
  })
})

Direct Workflow Integration

// Using $.do for durable actions
await $.do('Worker.notify', {
  actor: 'system',
  object: alice,
  action: 'notify',
  message: 'Deployment complete',
  via: 'slack',
})

// Using $.send for fire-and-forget
await $.send('Worker.notified', { ... })

Action Types

notify - Send notifications

await worker$.notify(target, 'Message content', {
  via: 'slack',           // Channel to use
  priority: 'urgent',     // 'low' | 'normal' | 'high' | 'urgent'
})

ask - Request information

const result = await worker$.ask<Priority>(
  target,
  'What priority should this be?',
  {
    via: 'slack',
    schema: { priority: 'low | normal | high' },
  }
)
console.log(result.answer) // { priority: 'high' }

approve - Request approval

const result = await worker$.approve(
  'Deploy v2.0 to production',
  manager,
  {
    via: 'slack',
    context: { version: '2.0', environment: 'production' },
    timeout: 3600000, // 1 hour
  }
)

if (result.approved) {
  console.log(`Approved by ${result.approvedBy?.name}`)
}

decide - AI-powered decisions

const result = await worker$.decide({
  options: ['React', 'Vue', 'Svelte'],
  context: 'Choosing a frontend framework for our new project',
  criteria: ['DX', 'Performance', 'Ecosystem'],
})

console.log(result.choice)     // 'React'
console.log(result.reasoning)  // 'React offers the best ecosystem...'
console.log(result.confidence) // 0.85

Standalone Functions

For use outside workflows:

import { notify, ask, approve, decide } from 'digital-workers'

// Simple notification
await notify(alice, 'Task completed', { via: 'slack' })

// Ask with variants
await ask(alice, 'What is the status?')
await ask.ai('What is our refund policy?', { policies: [...] })
await ask.yesNo(manager, 'Should we proceed?')

// Approval variants
await approve('Deploy to production', manager)
await approve.all('Major change', [cto, vpe, securityLead])
await approve.any('Urgent fix', oncallTeam)

// Decision making
await decide({ options: ['A', 'B', 'C'], criteria: ['cost', 'time'] })
await decide.yesNo('Should we proceed?', context)
await decide.prioritize(['Task 1', 'Task 2', 'Task 3'])

Additional Utilities

Role Definition

import { Role } from 'digital-workers'

const engineer = Role({
  name: 'Software Engineer',
  description: 'Builds and maintains software',
  responsibilities: ['Write code', 'Review PRs', 'Fix bugs'],
  skills: ['TypeScript', 'React', 'Node.js'],
})

Goals & KPIs

import { Goals, kpis, okrs } from 'digital-workers'

const teamGoals = Goals({
  shortTerm: ['Ship v2.0', 'Reduce tech debt'],
  longTerm: ['100% test coverage'],
  metrics: [
    { name: 'Velocity', current: 42, target: 50, unit: 'points' },
  ],
})

Content Generation

import { generate } from 'digital-workers'

const result = await generate('Write a product description', {
  type: 'text',
  instructions: 'Keep it under 100 words',
})

Type Validation

import { is } from 'digital-workers'

const result = await is('hello@example.com', 'email')
console.log(result.valid) // true

Type Reference

Key types exported:

  • Worker - Worker interface
  • Team - Team interface
  • WorkerRef - Lightweight worker reference
  • Contacts - Contact configuration
  • ContactChannel - Channel names
  • WorkerAction - Action types
  • NotifyResult, AskResult, ApprovalResult, DecideResult, DoResult
  • WorkerContext - Context extension for workflows
  • autonomous-agents - Implements Worker for AI agents with autonomous decision-making, goals, and metrics
  • human-in-the-loop - Implements Worker for humans with approval workflows, notifications, and escalation
  • ai-workflows - Uses digital-workers to orchestrate work execution with durable, event-driven workflows
  • services-as-software - External service integration (crosses company boundaries, unlike workers)