signalwire-agents 0.1.0

package/examples/call-flow.ts

@@ -0,0 +1,60 @@
+/**
+ * Call Flow Verbs Example
+ *
+ * Control what happens before, during, and after the AI conversation
+ * using SWML verbs in the 5-phase rendering pipeline.
+ * Run: npx tsx examples/call-flow.ts
+ */
+
+import { AgentBase, SwaigFunctionResult } from '../src/index.js';
+
+const agent = new AgentBase({
+  name: 'call-flow-agent',
+  route: '/',
+  basicAuth: ['user', 'pass'],
+  recordCall: true,       // Record the call (Phase 3)
+  recordFormat: 'mp4',
+  recordStereo: true,
+});
+
+agent.setPromptText('You are a receptionist. Help callers schedule appointments.');
+
+// Phase 1: Play ringing before answering
+agent.addPreAnswerVerb('play', {
+  urls: ['ring:us'],
+  auto_answer: false,
+});
+
+// Phase 3: Play a welcome message after answering but before the AI takes over
+agent.addPostAnswerVerb('play', {
+  url: 'say:Welcome to Acme Corp. Please hold while I connect you with our AI assistant.',
+});
+
+// Phase 5: Hangup after the AI conversation ends
+agent.addPostAiVerb('hangup', {});
+
+// AI config
+agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
+agent.addPronunciation({ replace: 'Acme', with: 'Ak-mee' });
+agent.setParam('temperature', 0.7);
+
+// Post-prompt for call summary
+agent.setPostPrompt('Provide a JSON summary with: caller_name, appointment_date, appointment_reason');
+
+// Tool for scheduling
+agent.defineTool({
+  name: 'schedule_appointment',
+  description: 'Schedule an appointment for the caller',
+  parameters: {
+    date: { type: 'string', description: 'Appointment date (YYYY-MM-DD)' },
+    time: { type: 'string', description: 'Appointment time (HH:MM)' },
+    reason: { type: 'string', description: 'Reason for the appointment' },
+  },
+  handler: (args) => {
+    return new SwaigFunctionResult(
+      `Appointment scheduled for ${args.date} at ${args.time}. Reason: ${args.reason}`,
+    );
+  },
+});
+
+agent.run();

package/examples/contexts-steps.ts

@@ -0,0 +1,62 @@
+/**
+ * Contexts & Steps Example
+ *
+ * Multi-step conversation workflows where the AI follows a structured
+ * sequence of steps, each with its own prompt, criteria, and allowed tools.
+ * Run: npx tsx examples/contexts-steps.ts
+ */
+
+import { AgentBase, SwaigFunctionResult } from '../src/index.js';
+
+const agent = new AgentBase({
+  name: 'quiz-agent',
+  route: '/',
+  basicAuth: ['user', 'pass'],
+});
+
+agent.setPromptText('You are a fun quiz host named Quizzy.');
+
+// Define tools
+agent.defineTool({
+  name: 'get_score',
+  description: 'Get the current score for the player',
+  parameters: {},
+  handler: () => new SwaigFunctionResult('The player has 3 out of 5 correct.'),
+});
+
+agent.defineTool({
+  name: 'submit_answer',
+  description: 'Submit an answer to the current question',
+  parameters: {
+    answer: { type: 'string', description: 'The answer to check' },
+  },
+  handler: (args) => {
+    return new SwaigFunctionResult(`The answer "${args.answer}" has been recorded.`);
+  },
+});
+
+// Define the conversation flow
+const ctx = agent.defineContexts();
+const quiz = ctx.addContext('default');
+
+// Step 1: Greet the player
+quiz
+  .addStep('greeting', { task: 'Welcome the player and explain the quiz rules.' })
+  .setStepCriteria('Player has acknowledged the rules and is ready to start')
+  .setFunctions('none') // No tools needed for greeting
+  .setValidSteps(['question']);
+
+// Step 2: Ask questions
+quiz
+  .addStep('question', { task: 'Ask the player a trivia question and evaluate their answer.' })
+  .setStepCriteria('Player has answered the question')
+  .setFunctions(['submit_answer'])
+  .setValidSteps(['question', 'results']);
+
+// Step 3: Show results
+quiz
+  .addStep('results', { task: 'Show the final score and thank the player for playing.' })
+  .setFunctions(['get_score'])
+  .setEnd(true);
+
+agent.run();

package/examples/datamap-tools.ts

@@ -0,0 +1,52 @@
+/**
+ * DataMap Tools Example
+ *
+ * Server-side tools that call external APIs without requiring
+ * your own webhook endpoints. The SignalWire platform executes
+ * these directly based on the data_map configuration.
+ * Run: npx tsx examples/datamap-tools.ts
+ */
+
+import {
+  AgentBase,
+  DataMap,
+  SwaigFunctionResult,
+  createSimpleApiTool,
+} from '../src/index.js';
+
+const agent = new AgentBase({
+  name: 'weather-agent',
+  route: '/',
+  basicAuth: ['user', 'pass'],
+});
+
+agent.setPromptText(
+  'You are a weather assistant. Help users check the weather in any city.',
+);
+
+// Method 1: Build a DataMap manually with full control
+const weatherTool = new DataMap('get_weather')
+  .purpose('Get current weather for a city')
+  .parameter('city', 'string', 'The city name', { required: true })
+  .webhook('GET', 'https://wttr.in/${lc:args.city}?format=j1')
+  .output(
+    new SwaigFunctionResult(
+      'Weather in ${args.city}: ${response.current_condition[0].temp_F}°F, ${response.current_condition[0].weatherDesc[0].value}',
+    ),
+  )
+  .fallbackOutput(
+    new SwaigFunctionResult('Sorry, I could not fetch the weather for that city.'),
+  );
+
+agent.registerSwaigFunction(weatherTool.toSwaigFunction());
+
+// Method 2: Use the createSimpleApiTool helper for quick API integrations
+const jokeTool = createSimpleApiTool({
+  name: 'get_joke',
+  url: 'https://official-joke-api.appspot.com/random_joke',
+  responseTemplate: 'Here is a joke: ${response.setup} ... ${response.punchline}',
+});
+
+agent.registerSwaigFunction(jokeTool.toSwaigFunction());
+
+agent.run();

package/examples/dynamic-config.ts

@@ -0,0 +1,51 @@
+/**
+ * Dynamic Configuration Example
+ *
+ * Customize agent behavior per-request based on query parameters,
+ * headers, or request body. Each request gets an ephemeral copy
+ * of the agent, so modifications don't affect other callers.
+ * Run: npx tsx examples/dynamic-config.ts
+ */
+
+import { AgentBase, SwaigFunctionResult } from '../src/index.js';
+
+const agent = new AgentBase({
+  name: 'dynamic-agent',
+  route: '/',
+  basicAuth: ['user', 'pass'],
+});
+
+agent.setPromptText('You are a helpful assistant.');
+
+agent.defineTool({
+  name: 'greet',
+  description: 'Greet the user by name',
+  parameters: {},
+  handler: () => new SwaigFunctionResult('Hello!'),
+});
+
+// Customize the agent per-request
+agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, agentCopy) => {
+  const copy = agentCopy as AgentBase;
+
+  // Customize based on query params (e.g., ?lang=es&name=Carlos)
+  const lang = queryParams['lang'];
+  if (lang === 'es') {
+    copy.setPromptText('Eres un asistente amigable. Responde siempre en español.');
+    copy.setLanguages([{ name: 'Spanish', code: 'es-ES', voice: 'polly.Lucia' }]);
+  } else if (lang === 'fr') {
+    copy.setPromptText('Vous êtes un assistant sympathique. Répondez toujours en français.');
+    copy.setLanguages([{ name: 'French', code: 'fr-FR', voice: 'polly.Celine' }]);
+  }
+
+  // Customize based on caller info from the request body
+  const callerName = queryParams['name'] ?? (bodyParams['caller_name'] as string);
+  if (callerName) {
+    copy.setGlobalData({ caller_name: callerName });
+    copy.setPromptText(
+      `You are a helpful assistant. The caller's name is ${callerName}. Greet them by name.`,
+    );
+  }
+});
+
+agent.run();

package/examples/multi-agent.ts

@@ -0,0 +1,67 @@
+/**
+ * Multi-Agent Server Example
+ *
+ * Host multiple agents under a single HTTP server, each at its own route.
+ * Run: npx tsx examples/multi-agent.ts
+ * Test:
+ *   curl http://user:pass@localhost:3000/support
+ *   curl http://user:pass@localhost:3000/sales
+ *   curl http://localhost:3000/          (agent listing)
+ *   curl http://localhost:3000/health
+ */
+
+import { AgentBase, AgentServer, SwaigFunctionResult } from '../src/index.js';
+
+// --- Support Agent ---
+const support = new AgentBase({
+  name: 'support',
+  route: '/support',
+  basicAuth: ['user', 'pass'],
+});
+
+support.setPromptText('You are a customer support agent. Help resolve issues quickly and politely.');
+support.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
+
+support.defineTool({
+  name: 'lookup_ticket',
+  description: 'Look up a support ticket by ID',
+  parameters: {
+    ticket_id: { type: 'string', description: 'The ticket ID' },
+  },
+  handler: (args) => {
+    return new SwaigFunctionResult(`Ticket ${args.ticket_id}: Status is "In Progress", assigned to Team B.`);
+  },
+});
+
+// --- Sales Agent ---
+const sales = new AgentBase({
+  name: 'sales',
+  route: '/sales',
+  basicAuth: ['user', 'pass'],
+});
+
+sales.setPromptText('You are a sales agent. Help potential customers understand our products and pricing.');
+sales.addLanguage({ name: 'English', code: 'en-US', voice: 'dave' });
+
+sales.defineTool({
+  name: 'get_pricing',
+  description: 'Get pricing information for a product',
+  parameters: {
+    product: { type: 'string', description: 'Product name' },
+  },
+  handler: (args) => {
+    const prices: Record<string, string> = {
+      basic: '$29/mo',
+      pro: '$99/mo',
+      enterprise: 'Custom pricing - schedule a call',
+    };
+    const price = prices[args.product?.toLowerCase()] ?? 'Product not found';
+    return new SwaigFunctionResult(`Pricing for ${args.product}: ${price}`);
+  },
+});
+
+// --- Server ---
+const server = new AgentServer({ port: 3000 });
+server.register(support);
+server.register(sales);
+server.run();

package/examples/pom-prompt.ts

@@ -0,0 +1,68 @@
+/**
+ * POM (Prompt Object Model) Example
+ *
+ * Build structured prompts with sections, bullets, and subsections
+ * instead of raw text strings.
+ * Run: npx tsx examples/pom-prompt.ts
+ */
+
+import { AgentBase, SwaigFunctionResult } from '../src/index.js';
+
+const agent = new AgentBase({
+  name: 'support-agent',
+  route: '/',
+  basicAuth: ['user', 'pass'],
+});
+
+// Build a structured prompt with POM
+agent.promptAddSection('Role', {
+  body: 'You are a technical support agent for Acme Corp.',
+});
+
+agent.promptAddSection('Capabilities', {
+  bullets: [
+    'Answer questions about our products',
+    'Help troubleshoot common issues',
+    'Escalate complex problems to human agents',
+  ],
+});
+
+agent.promptAddSection('Guidelines', {
+  body: 'Always follow these rules when assisting customers:',
+  subsections: [
+    {
+      title: 'Tone',
+      body: 'Be professional, empathetic, and patient.',
+    },
+    {
+      title: 'Escalation',
+      body: 'If you cannot resolve the issue in 3 attempts, offer to transfer to a human agent.',
+    },
+  ],
+});
+
+agent.promptAddSection('Product Info', {
+  bullets: [
+    'Widget Pro - Our flagship product, $99/mo',
+    'Widget Lite - Basic tier, $29/mo',
+    'Widget Enterprise - Custom pricing',
+  ],
+  numbered: true,
+});
+
+// Add a tool for transferring calls
+agent.defineTool({
+  name: 'transfer_to_human',
+  description: 'Transfer the caller to a human support agent',
+  parameters: {
+    reason: { type: 'string', description: 'Reason for the transfer' },
+  },
+  handler: (_args) => {
+    return new SwaigFunctionResult('Transferring you to a human agent now.')
+      .connect('+15551234567');
+  },
+});
+
+agent.setPostPrompt('Summarize the support interaction including the issue and resolution.');
+
+agent.run();

package/examples/simple-agent.ts

@@ -0,0 +1,33 @@
+/**
+ * Simple Agent Example
+ *
+ * A minimal AI voice agent that answers calls and responds to questions.
+ * Run: npx tsx examples/simple-agent.ts
+ * Test: curl http://user:pass@localhost:3000/
+ */
+
+import { AgentBase, SwaigFunctionResult } from '../src/index.js';
+
+const agent = new AgentBase({
+  name: 'simple-agent',
+  route: '/',
+  basicAuth: ['user', 'pass'],
+});
+
+agent.setPromptText('You are a friendly assistant named Siggy. Help callers with their questions.');
+
+agent.addHints(['SignalWire', 'SWML', 'Siggy']);
+agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
+
+// Define a tool the AI can call
+agent.defineTool({
+  name: 'get_time',
+  description: 'Get the current date and time',
+  parameters: {},
+  handler: () => {
+    const now = new Date().toLocaleString();
+    return new SwaigFunctionResult(`The current date and time is ${now}`);
+  },
+});
+
+agent.run();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "signalwire-agents",
+  "version": "0.1.0",
+  "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "swaig-test": "./dist/cli/swaig-test.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsc --watch",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@hono/node-server": "^1.11.0",
+    "hono": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "changeset": "^0.2.6",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0"
+  }
+}