signalwire-agents 0.1.0

package/dist/prefabs/InfoGathererAgent.js

@@ -0,0 +1,202 @@
+/**
+ * InfoGathererAgent - A prefab agent that sequentially collects information
+ * from callers through conversational interaction.
+ *
+ * Tracks fields per call, validates with optional regex patterns, and fires
+ * an onComplete callback once all required fields are gathered.
+ */
+import { AgentBase } from '../AgentBase.js';
+import { SwaigFunctionResult } from '../SwaigFunctionResult.js';
+// ── Agent ───────────────────────────────────────────────────────────────────
+/** Prefab agent that sequentially collects named fields from a caller with optional validation and completion callback. */
+export class InfoGathererAgent extends AgentBase {
+    fields;
+    introMessage;
+    confirmationMessage;
+    onCompleteCallback;
+    sessions = new Map();
+    /**
+     * Declarative prompt sections merged by AgentBase constructor.
+     * Additional dynamic sections are added in the constructor body below.
+     */
+    static PROMPT_SECTIONS = [
+        {
+            title: 'Role',
+            body: 'You are an information-gathering assistant. Your job is to collect specific pieces of information from the caller in a friendly, conversational manner.',
+        },
+        {
+            title: 'Rules',
+            bullets: [
+                'Ask for one field at a time, in the order listed.',
+                'If the caller provides information for a later field, accept it and move on.',
+                'Always confirm each piece of information before saving it using the save_field tool.',
+                'If validation fails, politely ask the caller to try again.',
+                'Use the get_status tool when you need to check progress.',
+                'Once all required fields are collected, summarize the information and confirm with the caller.',
+            ],
+        },
+    ];
+    /**
+     * Create an InfoGathererAgent with the specified fields and callbacks.
+     * @param config - Configuration including fields to collect, messages, and completion callback.
+     */
+    constructor(config) {
+        const agentName = config.name ?? 'InfoGatherer';
+        super({
+            name: agentName,
+            ...config.agentOptions,
+        });
+        this.fields = config.fields;
+        this.introMessage = config.introMessage ?? 'Hello! I need to collect some information from you. Let me walk you through it.';
+        this.confirmationMessage = config.confirmationMessage ?? 'Thank you! I have collected all the required information.';
+        this.onCompleteCallback = config.onComplete;
+        // Build the dynamic fields section
+        const fieldBullets = this.fields.map((f) => {
+            const reqLabel = f.required === false ? '(optional)' : '(required)';
+            const valLabel = f.validation ? ` [validation: ${f.validation instanceof RegExp ? f.validation.source : f.validation}]` : '';
+            return `${f.name}: ${f.description} ${reqLabel}${valLabel}`;
+        });
+        this.promptAddSection('Fields to Collect', { bullets: fieldBullets, numbered: true });
+        if (this.introMessage) {
+            this.promptAddSection('Introduction', {
+                body: `Begin the conversation with: "${this.introMessage}"`,
+            });
+        }
+        // Hints for speech recognition
+        this.addHints(this.fields.map((f) => f.name));
+        // Register tools after all fields are initialized
+        this.defineTools();
+    }
+    // ── Session helpers ───────────────────────────────────────────────────
+    getSession(rawData) {
+        const callId = rawData['call_id'] ?? 'default';
+        let session = this.sessions.get(callId);
+        if (!session) {
+            session = { collected: {}, completeFired: false };
+            this.sessions.set(callId, session);
+        }
+        return session;
+    }
+    getFieldByName(name) {
+        return this.fields.find((f) => f.name.toLowerCase() === name.toLowerCase());
+    }
+    validateValue(field, value) {
+        if (!field.validation)
+            return true;
+        const pattern = field.validation instanceof RegExp
+            ? field.validation
+            : new RegExp(field.validation);
+        return pattern.test(value);
+    }
+    getRequiredFields() {
+        return this.fields.filter((f) => f.required !== false);
+    }
+    allRequiredCollected(session) {
+        return this.getRequiredFields().every((f) => f.name in session.collected);
+    }
+    // ── Tool registration ─────────────────────────────────────────────────
+    /** Register the save_field and get_status SWAIG tools. */
+    defineTools() {
+        // Tool: save_field
+        this.defineTool({
+            name: 'save_field',
+            description: 'Save a collected field value from the caller. Validates the value if a validation pattern is configured for the field.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    field_name: {
+                        type: 'string',
+                        description: 'The name of the field to save.',
+                    },
+                    value: {
+                        type: 'string',
+                        description: 'The value provided by the caller.',
+                    },
+                },
+                required: ['field_name', 'value'],
+            },
+            handler: async (args, rawData) => {
+                const fieldName = args['field_name'];
+                const value = args['value'];
+                if (!fieldName || !value) {
+                    return new SwaigFunctionResult('Both field_name and value are required.');
+                }
+                const field = this.getFieldByName(fieldName);
+                if (!field) {
+                    const available = this.fields.map((f) => f.name).join(', ');
+                    return new SwaigFunctionResult(`Unknown field "${fieldName}". Available fields: ${available}`);
+                }
+                if (!this.validateValue(field, value)) {
+                    return new SwaigFunctionResult(`The value "${value}" is not valid for field "${field.name}". Please ask the caller to provide a valid value. Expected format: ${field.validation instanceof RegExp ? field.validation.source : field.validation}`);
+                }
+                const session = this.getSession(rawData);
+                session.collected[field.name] = value;
+                // Check if all required fields are now collected
+                if (this.allRequiredCollected(session) && !session.completeFired) {
+                    session.completeFired = true;
+                    if (this.onCompleteCallback) {
+                        try {
+                            await this.onCompleteCallback({ ...session.collected });
+                        }
+                        catch (err) {
+                            this.log.error(`onComplete callback error: ${err}`);
+                        }
+                    }
+                    const collectedSummary = Object.entries(session.collected)
+                        .map(([k, v]) => `${k}: ${v}`)
+                        .join(', ');
+                    return new SwaigFunctionResult(`Field "${field.name}" saved successfully. All required fields are now collected! Summary: ${collectedSummary}. ${this.confirmationMessage}`);
+                }
+                // Determine remaining fields
+                const remaining = this.fields
+                    .filter((f) => f.required !== false && !(f.name in session.collected))
+                    .map((f) => f.name);
+                return new SwaigFunctionResult(`Field "${field.name}" saved as "${value}". Remaining required fields: ${remaining.length > 0 ? remaining.join(', ') : 'none'}.`);
+            },
+        });
+        // Tool: get_status
+        this.defineTool({
+            name: 'get_status',
+            description: 'Get the current status of information gathering, showing which fields have been collected and which remain.',
+            parameters: {
+                type: 'object',
+                properties: {},
+            },
+            handler: (args, rawData) => {
+                const session = this.getSession(rawData);
+                const collectedEntries = Object.entries(session.collected);
+                const collectedStr = collectedEntries.length > 0
+                    ? collectedEntries.map(([k, v]) => `${k}: ${v}`).join(', ')
+                    : 'none';
+                const remainingRequired = this.getRequiredFields()
+                    .filter((f) => !(f.name in session.collected))
+                    .map((f) => f.name);
+                const remainingOptional = this.fields
+                    .filter((f) => f.required === false && !(f.name in session.collected))
+                    .map((f) => f.name);
+                let status = `Collected: ${collectedStr}.`;
+                if (remainingRequired.length > 0) {
+                    status += ` Remaining required: ${remainingRequired.join(', ')}.`;
+                }
+                else {
+                    status += ' All required fields have been collected!';
+                }
+                if (remainingOptional.length > 0) {
+                    status += ` Optional fields not yet collected: ${remainingOptional.join(', ')}.`;
+                }
+                return new SwaigFunctionResult(status);
+            },
+        });
+    }
+}
+// ── Factory function ────────────────────────────────────────────────────────
+/**
+ * Factory function that creates and returns a new InfoGathererAgent.
+ * @param config - Configuration for the info gatherer agent.
+ * @returns A configured InfoGathererAgent instance.
+ */
+export function createInfoGathererAgent(config) {
+    return new InfoGathererAgent(config);
+}
+export default InfoGathererAgent;
+//# sourceMappingURL=InfoGathererAgent.js.map

package/dist/prefabs/InfoGathererAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InfoGathererAgent.js","sourceRoot":"","sources":["../../src/prefabs/InfoGathererAgent.ts"],"names":[],"mappings":"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"}

package/dist/prefabs/ReceptionistAgent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ReceptionistAgent - A prefab front-desk agent that handles visitor
+ * check-in, department directory lookup, and call transfers by extension.
+ */
+import { AgentBase } from '../AgentBase.js';
+import type { AgentOptions } from '../types.js';
+export interface ReceptionistDepartment {
+    /** Department name (e.g. "Engineering", "HR"). */
+    name: string;
+    /** Internal extension number or SIP address. */
+    extension: string;
+    /** Optional description of the department. */
+    description?: string;
+}
+export interface ReceptionistConfig {
+    /** Agent display name. */
+    name?: string;
+    /** Company name displayed in greetings and prompts. */
+    companyName: string;
+    /** Departments with extensions for the directory. */
+    departments: ReceptionistDepartment[];
+    /** Custom welcome message. */
+    welcomeMessage?: string;
+    /** Whether visitor check-in functionality is enabled. Default true. */
+    checkInEnabled?: boolean;
+    /** Callback fired when a visitor checks in. */
+    onVisitorCheckIn?: (visitor: Record<string, string>) => void | Promise<void>;
+    /** Additional AgentBase options forwarded to super(). */
+    agentOptions?: Partial<AgentOptions>;
+}
+/** Prefab front-desk agent that handles visitor check-in, department directory lookup, and call transfers by extension. */
+export declare class ReceptionistAgent extends AgentBase {
+    private companyName;
+    private departments;
+    private welcomeMessage;
+    private checkInEnabled;
+    private onVisitorCheckInCallback?;
+    private sessions;
+    /** Declarative prompt sections merged by AgentBase constructor. */
+    static PROMPT_SECTIONS: ({
+        title: string;
+        body: string;
+        bullets?: undefined;
+    } | {
+        title: string;
+        bullets: string[];
+        body?: undefined;
+    })[];
+    /**
+     * Create a ReceptionistAgent with the specified company, departments, and check-in settings.
+     * @param config - Configuration including company name, departments, and visitor check-in callback.
+     */
+    constructor(config: ReceptionistConfig);
+    private getSession;
+    private findDepartment;
+    /** Register the get_department_list, transfer_to_department, and optional check_in_visitor SWAIG tools. */
+    protected defineTools(): void;
+}
+/**
+ * Factory function that creates and returns a new ReceptionistAgent.
+ * @param config - Configuration for the receptionist agent.
+ * @returns A configured ReceptionistAgent instance.
+ */
+export declare function createReceptionistAgent(config: ReceptionistConfig): ReceptionistAgent;
+export default ReceptionistAgent;

package/dist/prefabs/ReceptionistAgent.js

@@ -0,0 +1,205 @@
+/**
+ * ReceptionistAgent - A prefab front-desk agent that handles visitor
+ * check-in, department directory lookup, and call transfers by extension.
+ */
+import { AgentBase } from '../AgentBase.js';
+import { SwaigFunctionResult } from '../SwaigFunctionResult.js';
+// ── Agent ───────────────────────────────────────────────────────────────────
+/** Prefab front-desk agent that handles visitor check-in, department directory lookup, and call transfers by extension. */
+export class ReceptionistAgent extends AgentBase {
+    companyName;
+    departments;
+    welcomeMessage;
+    checkInEnabled;
+    onVisitorCheckInCallback;
+    sessions = new Map();
+    /** Declarative prompt sections merged by AgentBase constructor. */
+    static PROMPT_SECTIONS = [
+        {
+            title: 'Role',
+            body: 'You are a friendly and professional receptionist. Greet visitors warmly, help them check in, look up department information, and transfer calls to the appropriate extension.',
+        },
+        {
+            title: 'Rules',
+            bullets: [
+                'Always greet the caller with the company welcome message.',
+                'If a caller wants to reach a department, use get_department_list to find the right one, then transfer_to_department.',
+                'If a caller wants to check in as a visitor, collect their name, purpose of visit, and who they are visiting, then use check_in_visitor.',
+                'Be warm, helpful, and professional at all times.',
+                'If you are unsure which department the caller needs, offer to list all departments.',
+                'Confirm the department name before transferring.',
+            ],
+        },
+    ];
+    /**
+     * Create a ReceptionistAgent with the specified company, departments, and check-in settings.
+     * @param config - Configuration including company name, departments, and visitor check-in callback.
+     */
+    constructor(config) {
+        const agentName = config.name ?? 'Receptionist';
+        super({
+            name: agentName,
+            ...config.agentOptions,
+        });
+        this.companyName = config.companyName;
+        this.departments = config.departments;
+        this.welcomeMessage = config.welcomeMessage ?? `Welcome to ${this.companyName}! How may I help you today?`;
+        this.checkInEnabled = config.checkInEnabled ?? true;
+        this.onVisitorCheckInCallback = config.onVisitorCheckIn;
+        // Welcome section
+        this.promptAddSection('Welcome', {
+            body: `You are the receptionist for ${this.companyName}. Greet callers with: "${this.welcomeMessage}"`,
+        });
+        // Department directory section
+        const deptBullets = this.departments.map((dept) => {
+            let line = `${dept.name} (ext: ${dept.extension})`;
+            if (dept.description)
+                line += ` - ${dept.description}`;
+            return line;
+        });
+        this.promptAddSection('Department Directory', { bullets: deptBullets });
+        if (this.checkInEnabled) {
+            this.promptAddSection('Visitor Check-In', {
+                body: 'If a caller wants to check in as a visitor, collect their full name, the purpose of their visit, and the name of the person they are visiting. Then use the check_in_visitor tool.',
+            });
+        }
+        // Speech recognition hints
+        const hints = [this.companyName];
+        hints.push(...this.departments.map((d) => d.name));
+        this.addHints(hints);
+        // Register tools after all fields are initialized
+        this.defineTools();
+    }
+    // ── Session helpers ───────────────────────────────────────────────────
+    getSession(rawData) {
+        const callId = rawData['call_id'] ?? 'default';
+        let session = this.sessions.get(callId);
+        if (!session) {
+            session = { visitors: [] };
+            this.sessions.set(callId, session);
+        }
+        return session;
+    }
+    // ── Department helpers ────────────────────────────────────────────────
+    findDepartment(name) {
+        const normalized = name.toLowerCase().trim();
+        return this.departments.find((d) => d.name.toLowerCase() === normalized);
+    }
+    // ── Tool registration ─────────────────────────────────────────────────
+    /** Register the get_department_list, transfer_to_department, and optional check_in_visitor SWAIG tools. */
+    defineTools() {
+        // Tool: get_department_list
+        this.defineTool({
+            name: 'get_department_list',
+            description: `List all departments at ${this.companyName} with their extensions and descriptions.`,
+            parameters: {
+                type: 'object',
+                properties: {},
+            },
+            handler: () => {
+                if (this.departments.length === 0) {
+                    return new SwaigFunctionResult('No departments are currently listed in the directory.');
+                }
+                const lines = this.departments.map((dept) => {
+                    let line = `${dept.name} - Extension: ${dept.extension}`;
+                    if (dept.description)
+                        line += ` (${dept.description})`;
+                    return line;
+                });
+                return new SwaigFunctionResult(`Department directory for ${this.companyName}:\n${lines.join('\n')}`);
+            },
+        });
+        // Tool: transfer_to_department
+        this.defineTool({
+            name: 'transfer_to_department',
+            description: 'Transfer the caller to a department by dialing its extension.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    department_name: {
+                        type: 'string',
+                        description: 'The name of the department to transfer to.',
+                    },
+                },
+                required: ['department_name'],
+            },
+            handler: (_args) => {
+                const deptName = _args['department_name'];
+                if (!deptName) {
+                    return new SwaigFunctionResult('Please provide a department name to transfer to.');
+                }
+                const dept = this.findDepartment(deptName);
+                if (!dept) {
+                    const available = this.departments.map((d) => d.name).join(', ');
+                    return new SwaigFunctionResult(`Department "${deptName}" not found in the directory. Available departments: ${available}`);
+                }
+                const result = new SwaigFunctionResult(`Transferring you to ${dept.name} at extension ${dept.extension}. One moment please.`);
+                result.connect(dept.extension);
+                return result;
+            },
+        });
+        // Tool: check_in_visitor (only if enabled)
+        if (this.checkInEnabled) {
+            this.defineTool({
+                name: 'check_in_visitor',
+                description: 'Check in a visitor by recording their name, purpose of visit, and who they are visiting.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        visitor_name: {
+                            type: 'string',
+                            description: 'Full name of the visitor.',
+                        },
+                        purpose: {
+                            type: 'string',
+                            description: 'Purpose of the visit.',
+                        },
+                        visiting: {
+                            type: 'string',
+                            description: 'Name of the person or department the visitor is here to see.',
+                        },
+                    },
+                    required: ['visitor_name', 'purpose', 'visiting'],
+                },
+                handler: async (_args, rawData) => {
+                    const visitorName = _args['visitor_name'];
+                    const purpose = _args['purpose'];
+                    const visiting = _args['visiting'];
+                    if (!visitorName || !purpose || !visiting) {
+                        return new SwaigFunctionResult('Please provide the visitor\'s name, purpose of visit, and who they are visiting.');
+                    }
+                    const visitorRecord = {
+                        visitor_name: visitorName,
+                        purpose,
+                        visiting,
+                        checked_in_at: new Date().toISOString(),
+                    };
+                    // Store in session
+                    const session = this.getSession(rawData);
+                    session.visitors.push(visitorRecord);
+                    // Fire callback
+                    if (this.onVisitorCheckInCallback) {
+                        try {
+                            await this.onVisitorCheckInCallback(visitorRecord);
+                        }
+                        catch (err) {
+                            this.log.error(`onVisitorCheckIn callback error: ${err}`);
+                        }
+                    }
+                    return new SwaigFunctionResult(`Visitor checked in successfully! Name: ${visitorName}, Purpose: ${purpose}, Visiting: ${visiting}. Welcome to ${this.companyName}!`);
+                },
+            });
+        }
+    }
+}
+// ── Factory function ────────────────────────────────────────────────────────
+/**
+ * Factory function that creates and returns a new ReceptionistAgent.
+ * @param config - Configuration for the receptionist agent.
+ * @returns A configured ReceptionistAgent instance.
+ */
+export function createReceptionistAgent(config) {
+    return new ReceptionistAgent(config);
+}
+export default ReceptionistAgent;
+//# sourceMappingURL=ReceptionistAgent.js.map

package/dist/prefabs/ReceptionistAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReceptionistAgent.js","sourceRoot":"","sources":["../../src/prefabs/ReceptionistAgent.ts"],"names":[],"mappings":"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"}

package/dist/prefabs/SurveyAgent.d.ts

@@ -0,0 +1,84 @@
+/**
+ * SurveyAgent - A prefab agent that conducts surveys with branching logic,
+ * scoring, and conditional question flow.
+ *
+ * Supports multiple question types (multiple choice, open ended, rating,
+ * yes/no), conditional branching based on answers, and per-answer scoring.
+ */
+import { AgentBase } from '../AgentBase.js';
+import type { AgentOptions } from '../types.js';
+export interface SurveyQuestion {
+    /** Unique question identifier. */
+    id: string;
+    /** The question text to ask the caller. */
+    text: string;
+    /** Question type determines validation and display. */
+    type: 'multiple_choice' | 'open_ended' | 'rating' | 'yes_no';
+    /** Options for multiple_choice questions. */
+    options?: string[];
+    /**
+     * Next question ID after this one.
+     * - string: always go to that question
+     * - Record<string, string>: map from answer value to next question ID
+     * - undefined: proceed to next question in array order
+     */
+    nextQuestion?: string | Record<string, string>;
+    /**
+     * Points awarded for answers.
+     * - number: fixed points for any answer
+     * - Record<string, number>: points per specific answer value
+     */
+    points?: number | Record<string, number>;
+}
+export interface SurveyConfig {
+    /** Agent display name. */
+    name?: string;
+    /** Ordered list of survey questions. */
+    questions: SurveyQuestion[];
+    /** Opening message before the first question. */
+    introMessage?: string;
+    /** Message after the survey is complete. */
+    completionMessage?: string;
+    /** Callback fired when the survey is finished. */
+    onComplete?: (responses: Record<string, unknown>, score: number) => void | Promise<void>;
+    /** Additional AgentBase options forwarded to super(). */
+    agentOptions?: Partial<AgentOptions>;
+}
+/** Prefab agent that conducts surveys with branching logic, answer scoring, and conditional question flow. */
+export declare class SurveyAgent extends AgentBase {
+    private questions;
+    private questionMap;
+    private introMessage;
+    private completionMessage;
+    private onCompleteCallback?;
+    private sessions;
+    /** Declarative prompt sections merged by AgentBase constructor. */
+    static PROMPT_SECTIONS: ({
+        title: string;
+        body: string;
+        bullets?: undefined;
+    } | {
+        title: string;
+        bullets: string[];
+        body?: undefined;
+    })[];
+    /**
+     * Create a SurveyAgent with the specified questions and callbacks.
+     * @param config - Configuration including questions, messages, and completion callback.
+     */
+    constructor(config: SurveyConfig);
+    private getSession;
+    private resolveNextQuestion;
+    private calculatePoints;
+    private validateAnswer;
+    private normalizeAnswer;
+    /** Register the answer_question, get_current_question, and get_survey_progress SWAIG tools. */
+    protected defineTools(): void;
+}
+/**
+ * Factory function that creates and returns a new SurveyAgent.
+ * @param config - Configuration for the survey agent.
+ * @returns A configured SurveyAgent instance.
+ */
+export declare function createSurveyAgent(config: SurveyConfig): SurveyAgent;
+export default SurveyAgent;