@moss-tools/livekit-orchestrator

Enhanced wrapper for @livekit/agents with voice optimization, tool management, and diagnostics utilities.

Installation

npm install @moss-tools/livekit-orchestrator

Features

• Drop-in Replacement: Re-exports all @livekit/agents APIs
• Voice Optimization: Automatic session optimization via Moss endpoint
• Enhanced Agent: Tool management methods (add, remove, inspect tools)
• Tool Tracking: Automatic latency tracking for tool execution
• Diagnostics: Built-in latency tracking and reporting

Quick Start

import {
  cli,
  defineAgent,
  voice,
  llm,
  callTool,
  LatencyTracker,
  createVoiceAgent,
  createAgentSession,
} from '@moss-tools/livekit-orchestrator';
import { z } from 'zod';

// Initialize diagnostics
const latencyTracker = new LatencyTracker('call-123');

// Create tools with latency tracking
const myTools = {
  processPayment: callTool({
    tool_name: 'processPayment',
    description: 'Process a payment',
    parameters: z.object({
      amount: z.number(),
      currency: z.string(),
    }),
    execute: async ({ amount, currency }) => {
      return `Processed ${amount} ${currency}`;
    },
    tracker: latencyTracker, // optional latency tracking
  }),
};

// Define your agent
export default defineAgent({
  async entry(ctx: JobContext) {
    // Create session with automatic voice optimization
    const session = await createAgentSession({
      stt: components.stt,
      vad: components.vad,
      llm: components.llm,
      tts: components.tts,
      userData: callInfo,
    });

    // Create agent with enhanced tool management
    const agent = createVoiceAgent({
      instructions: 'You are a helpful assistant',
      tools: myTools,
    });

    // Start session
    session.start();

    // Generate diagnostics report
    console.log(latencyTracker.generateReport());
  },
});

Environment Variables

Set these to enable automatic voice optimization:

MOSS_PROJECT_ID=your-project-id
MOSS_PROJECT_KEY=your-project-key

When set, createAgentSession automatically fetches and applies livekit lifecycle optimizations from the Moss service.

API

createAgentSession

Creates an AgentSession with automatic voice optimization from Moss.

const session = await createAgentSession({
  stt: components.stt,
  vad: components.vad,
  llm: components.llm,
  tts: components.tts,
  userData: callInfo,
});

createVoiceAgent

Creates a VoiceAgent with enhanced tool management methods.

const agent = createVoiceAgent({
  instructions: 'You are a helpful assistant',
  tools: myTools,
});

// Tool management
agent.addTool('newTool', tool);
agent.removeTool('oldTool');
agent.getToolNames(); // ['tool1', 'tool2', ...]
agent.hasTool('tool1'); // true
agent.getToolCount(); // 2

callTool

Creates a tool with optional latency tracking.

import { callTool } from '@moss-tools/livekit-orchestrator';
import { z } from 'zod';

const fetchData = callTool({
  tool_name: 'fetchData', // optional, used in tracking
  description: 'Fetch user data',
  parameters: z.object({ userId: z.string() }),
  execute: async ({ userId }) => {
    return await api.getUser(userId);
  },
  tracker: latencyTracker, // optional latency tracking
});

LatencyTracker

Tracks performance metrics and generates reports.

// Initialize tracker
const tracker = new LatencyTracker('call-123');

// Track operations manually
const endOperation = tracker.start('Database Query');
await doSomething();
endOperation();

// Track automatically
await tracker.track('API Call', async () => {
  return await fetchData();
});

// Log events
tracker.event('User responded');

// Generate report
const report = tracker.generateReport();
console.log(report);

// Get raw data
const data = tracker.getRawData();

License

SEE LICENSE IN LICENSE