Voice Agent Connector

A TypeScript library for building voice AI applications with LiveKit and SIP integration.

Overview

Voice Agent Connector provides a unified interface for:

• Managing SIP trunks (inbound/outbound) for telephony integration
• Controlling active voice calls (freeze, unfreeze, transfer, hangup)
• Sending real-time messages and signals to voice agents
• Storing and retrieving call details and transcripts

Configuration

The connector can be configured via environment variables or constructor options.

Environment Variables

LIVEKIT_URL=ws://your-livekit-server.com
LIVEKIT_API_KEY=livekit-api-key
LIVEKIT_API_SECRET=livekit-api-secret

Usage

Basic Setup

import VoiceAgentConnector from '@recombine-ai/voice-agent-connector'

const connector = new VoiceAgentConnector({
    agentName: 'my-agent',
})

// Or with explicit LiveKit configuration
const connector = new VoiceAgentConnector({
    agentName: 'my-agent',
    livekit: {
        url: 'ws://your-livekit-server.com',
        key: 'livekit-api-key',
        secret: 'livekit-api-secret',
    },
})

SIP Configuration

const connector = new VoiceAgentConnector({
    agentName: 'my-agent',
    sip: {
        roomPrefix: 'myroom', // Room name prefix (default: 'call')
        trunks: {
            in: {
                numbers: ['+15551234567'], // Inbound phone numbers
                allowedAddresses: ['54.171.127.192/30'], // Allowed IP addresses
            },
            out: {
                numbers: ['+15551234567'], // Outbound phone numbers
                server: 'sip.twilio.com', // SIP server address
                authUsername: 'user',
                authPassword: 'pass',
            },
        },
    },
})

// Initialize SIP resources
await connector.setUpSip()

Call Control

const callId = 'abc123'

// Freeze the agent (pause processing)
await connector.freeze(callId)

// Unfreeze the agent (resume processing)
await connector.unfreeze(callId)

// Reload agent configuration
await connector.reload(callId)

// Hang up the call
await connector.hangup(callId)

Sending Messages

await connector.addMessage(callId, {
    sender: 'agent', // 'user' | 'agent' | 'system'
    text: 'Hello, how can I help you?',
})

Call Transfer

await connector.transfer(
    '+15559999999', // Destination number
    callId,
    { 'X-Custom-Header': 'value' }, // Optional SIP headers
    'escalation', // Reason: 'escalation' | 'error'
    'Please hold while I transfer you.', // Optional disclaimer
)

Call Details Storage

import VoiceAgentConnector, { S3CallDetailsStorage } from '@recombine-ai/voice-agent-connector'

const connector = new VoiceAgentConnector({
    agentName: 'my-agent',
    storage: new S3CallDetailsStorage({
        bucketName: 'my-bucket',
        region: 'us-east-1',
    }),
})

// Retrieve call details
const details = await connector.getCallDetails(callId)
if (details) {
    console.log('Call duration:', details.callDuration)
    console.log('Transcript:', details.transcript)
}

Health Check

Use createHealthCheck to aggregate readiness across all connector instances. The connector is not considered healthy until its SIP resources are fully set up.

import VoiceAgentConnector, { createHealthCheck } from '@recombine-ai/voice-agent-connector'

const connectors = [
    new VoiceAgentConnector({
        agentName: 'voiceSupport',
        sip: { trunks: { in: { numbers: ['+15551234567'] } } },
    }),
    new VoiceAgentConnector({
        agentName: 'voiceSdr',
        sip: { trunks: { in: { numbers: ['+15559876543'] } } },
    }),
]

const healthCheck = createHealthCheck(connectors)

// Wire to your HTTP framework (e.g. Fastify, Express)
app.get('/health', (req, res) => {
    const status = healthCheck()
    res.status(status.ok ? 200 : 503).json(status)
})

// Start listening BEFORE SIP setup so ECS health probe has an endpoint.
// It will return 503 until all agents complete setup.
await app.listen({ port: 8000 })

// SIP setup runs after server is listening
await Promise.all(connectors.map((c) => c.setUpSip()))
// healthCheck() now returns:
// {
//   ok: true,
//   agents: {
//     voiceSupport: { sipReady: true },
//     voiceSdr: { sipReady: true }
//   }
// }

The healthCheck() closure is synchronous -- it reads boolean flags, no network calls. Safe for ECS/ALB probes firing every few seconds.

For single-agent setups, the same pattern applies:

const connector = new VoiceAgentConnector({
    agentName: 'my-agent',
    sip: {
        /* ... */
    },
})
const healthCheck = createHealthCheck([connector])

The previous connector.healthCheck() method still exists for checking LiveKit connectivity directly, but createHealthCheck is the recommended approach for deployment readiness.