SignalWire AI Agents SDK for TypeScript

Build AI voice agents as HTTP microservices that serve SWML documents and handle SWAIG function callbacks.

Quick Start

npm install
npm run build

import { AgentBase, SwaigFunctionResult } from 'signalwire-agents';

const agent = new AgentBase({
  name: 'my-agent',
  route: '/',
  basicAuth: ['user', 'pass'],
});

agent.setPromptText('You are a helpful assistant.');

agent.defineTool({
  name: 'get_time',
  description: 'Get the current time',
  parameters: {},
  handler: () => new SwaigFunctionResult(`It is ${new Date().toLocaleTimeString()}`),
});

agent.run(); // Starts HTTP server on port 3000

Point your SignalWire phone number's SWML webhook at http://user:pass@your-host:3000/ and the agent will answer calls.

How It Works

When a call comes in, SignalWire requests a SWML document from your agent's HTTP endpoint. The SDK builds this document with your configured prompt, tools, languages, and call flow verbs. During the call, the AI can invoke your tools via SWAIG callbacks to the same server.

SignalWire ──GET /──> Agent (returns SWML JSON)
SignalWire ──POST /swaig──> Agent (calls your tool handlers)
SignalWire ──POST /post_prompt──> Agent (sends call summary)

Installation

npm install signalwire-agents

Requires Node.js >= 18.

Core Concepts

AgentBase

The main class. Each agent is an HTTP server that serves SWML and handles tool callbacks.

const agent = new AgentBase({
  name: 'my-agent',        // Agent name (required)
  route: '/',               // HTTP route path
  port: 3000,               // Server port
  basicAuth: ['u', 'p'],    // HTTP basic auth credentials
  autoAnswer: true,         // Auto-answer incoming calls
  recordCall: false,        // Record calls
  recordFormat: 'mp4',      // Recording format
  nativeFunctions: [],      // Platform-native functions (e.g., 'check_time')
});

Auth credentials can also be set via environment variables SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD. If neither is provided, credentials are auto-generated and logged at startup.

Tools (SWAIG Functions)

Tools let the AI perform actions during a call. Define them with defineTool():

agent.defineTool({
  name: 'lookup_order',
  description: 'Look up an order by ID',
  parameters: {
    order_id: { type: 'string', description: 'The order ID' },
  },
  handler: async (args, fullBody) => {
    const order = await db.findOrder(args.order_id);
    return new SwaigFunctionResult(`Order ${order.id}: status is ${order.status}`);
  },
});

Handlers receive the parsed arguments and the full request body. They can be async. The return value must be a SwaigFunctionResult.

Secure Tools

Mark a tool as secure: true to require per-call HMAC tokens:

agent.defineTool({
  name: 'charge_card',
  description: 'Charge the customer credit card',
  parameters: { amount: { type: 'string', description: 'Amount to charge' } },
  secure: true,
  handler: (args) => new SwaigFunctionResult(`Charged $${args.amount}`),
});

SwaigFunctionResult

The response builder for tool handlers. Carries response text plus structured platform actions. All methods return this for chaining.

// Simple response
return new SwaigFunctionResult('Done.');

// Transfer the call
return new SwaigFunctionResult('Transferring you now.')
  .connect('+15551234567');

// Multiple actions
return new SwaigFunctionResult('Noted.')
  .updateGlobalData({ last_action: 'sms' })
  .sendSms({
    toNumber: '+15551234567',
    fromNumber: '+15559876543',
    body: 'Your order has shipped!',
  });

// Hang up
return new SwaigFunctionResult('Goodbye!').hangup();

Available actions: connect, hangup, hold, stop, waitForUser, say, playBackgroundFile, stopBackgroundFile, sendSms, recordCall, stopRecordCall, tap, stopTap, joinRoom, joinConference, sipRefer, pay, executeSwml, switchContext, swmlChangeStep, swmlChangeContext, updateGlobalData, removeGlobalData, setMetadata, removeMetadata, toggleFunctions, simulateUserInput, replaceInHistory, addDynamicHints, clearDynamicHints, setEndOfSpeechTimeout, executeRpc, and more.

Prompts

Raw Text

agent.setPromptText('You are a helpful assistant.');

Prompt Object Model (POM)

Build structured prompts with sections, bullets, and subsections:

agent.promptAddSection('Role', {
  body: 'You are a customer support agent.',
});

agent.promptAddSection('Rules', {
  bullets: [
    'Always be polite',
    'Never share internal data',
    'Escalate if unsure',
  ],
});

agent.promptAddSection('Guidelines', {
  body: 'Follow these interaction patterns:',
  subsections: [
    { title: 'Greeting', body: 'Always start with a warm greeting.' },
    { title: 'Closing', body: 'Ask if there is anything else before ending.' },
  ],
});

You can also append to existing sections:

agent.promptAddToSection('Rules', { bullet: 'Keep responses under 2 sentences' });
agent.promptAddSubsection('Guidelines', 'Tone', { body: 'Use a conversational tone.' });

DataMap (Server-Side Tools)

DataMap tools execute on the SignalWire platform without hitting your server. They map API responses to AI-consumable text using templates:

import { DataMap, SwaigFunctionResult } from 'signalwire-agents';

const weather = new DataMap('get_weather')
  .purpose('Get weather for a city')
  .parameter('city', 'string', 'City name', { required: true })
  .webhook('GET', 'https://wttr.in/${lc:args.city}?format=j1')
  .output(new SwaigFunctionResult('Weather: ${response.current_condition[0].temp_F}°F'))
  .fallbackOutput(new SwaigFunctionResult('Could not fetch weather.'));

agent.registerSwaigFunction(weather.toSwaigFunction());

Or use the helper for simple cases:

import { createSimpleApiTool } from 'signalwire-agents';

const joke = createSimpleApiTool({
  name: 'get_joke',
  url: 'https://official-joke-api.appspot.com/random_joke',
  responseTemplate: '${response.setup} ... ${response.punchline}',
});

agent.registerSwaigFunction(joke.toSwaigFunction());

Contexts & Steps

Define multi-step conversation workflows where the AI follows a structured sequence:

const ctx = agent.defineContexts();
const flow = ctx.addContext('default');

flow.addStep('greeting', { task: 'Greet the user and ask how you can help.' })
  .setStepCriteria('User has stated their request')
  .setFunctions('none')
  .setValidSteps(['help', 'goodbye']);

flow.addStep('help', { task: 'Help the user with their request.' })
  .setFunctions(['lookup_order', 'check_status'])
  .setValidSteps(['goodbye']);

flow.addStep('goodbye', { task: 'Thank the user and end the call.' })
  .setEnd(true);

Steps support gather_info for structured data collection:

flow.addStep('collect_info')
  .setText('Collect the caller information.')
  .setGatherInfo({ outputKey: 'caller_info' })
  .addGatherQuestion({ key: 'name', question: 'What is your name?' })
  .addGatherQuestion({ key: 'email', question: 'What is your email?', type: 'string', confirm: true })
  .setValidSteps(['process']);

Call Flow (5-Phase Rendering)

Control what happens at each stage of the call:

// Phase 1: Before answering (e.g., play ringing)
agent.addPreAnswerVerb('play', { urls: ['ring:us'], auto_answer: false });

// Phase 2: Answer (automatic if autoAnswer: true)

// Phase 3: After answer, before AI (e.g., welcome message, recording)
agent.addPostAnswerVerb('play', { url: 'say:Welcome!' });

// Phase 4: AI conversation (automatic - built from your prompt, tools, etc.)

// Phase 5: After AI ends (e.g., cleanup)
agent.addPostAiVerb('hangup', {});

AI Configuration

// Speech hints for better recognition
agent.addHints(['SignalWire', 'SWML', 'SWAIG']);

// Languages and voices
agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });

// Pronunciation corrections
agent.addPronunciation({ replace: 'API', with: 'A P I' });

// LLM parameters
agent.setParam('temperature', 0.7);
agent.setParams({ top_p: 0.9, frequency_penalty: 0.3 });
agent.setPromptLlmParams({ temperature: 0.5 }); // per-prompt params

// Global data accessible to all tools
agent.setGlobalData({ company: 'Acme Corp', plan: 'enterprise' });

// Native platform functions
agent.setNativeFunctions(['check_time']);

Dynamic Configuration

Customize agent behavior per-request based on caller info, query params, or headers:

agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, agentCopy) => {
  const copy = agentCopy as AgentBase;

  // Different prompt based on query param
  if (queryParams['lang'] === 'es') {
    copy.setPromptText('Responde en español.');
    copy.setLanguages([{ name: 'Spanish', code: 'es-ES', voice: 'polly.Lucia' }]);
  }

  // Add caller-specific data
  const callerId = bodyParams['caller_id_number'] as string;
  if (callerId) {
    copy.setGlobalData({ caller_phone: callerId });
  }
});

Each request gets an ephemeral copy of the agent, so modifications don't affect other callers.

Post-Prompt (Call Summaries)

Get a summary after each call:

agent.setPostPrompt('Summarize this call as JSON with: topic, resolution, follow_up_needed');

Override onSummary() in a subclass to process summaries:

class MyAgent extends AgentBase {
  async onSummary(summary: Record<string, unknown> | null, rawData: Record<string, unknown>) {
    console.log('Call summary:', summary);
    // Save to database, send notification, etc.
  }
}

Multi-Agent Server

Host multiple agents under a single HTTP server:

import { AgentServer, AgentBase } from 'signalwire-agents';

const support = new AgentBase({ name: 'support', route: '/support', basicAuth: ['u', 'p'] });
support.setPromptText('You are a support agent.');

const sales = new AgentBase({ name: 'sales', route: '/sales', basicAuth: ['u', 'p'] });
sales.setPromptText('You are a sales agent.');

const server = new AgentServer({ port: 3000 });
server.register(support);
server.register(sales);
server.run();

The root / returns a JSON listing of all registered agents. Health checks are at /health and /ready.

HTTP Endpoints

Each agent exposes these endpoints:

Endpoint	Method	Description
/	GET/POST	Returns SWML document
/swaig	GET/POST	SWAIG function dispatcher
/post_prompt	GET/POST	Post-prompt summary handler
/health	GET	Health check
/ready	GET	Readiness check

All endpoints (except health/ready) require basic auth.

Environment Variables

Variable	Description
PORT	Server port (default: 3000)
SWML_BASIC_AUTH_USER	Basic auth username
SWML_BASIC_AUTH_PASSWORD	Basic auth password
SWML_PROXY_URL_BASE	Proxy/tunnel base URL for webhook URLs

Documentation

Comprehensive guides and API reference are in the docs/ directory:

Guide	Description
Agent Guide	Getting started — creating agents, prompts, tools, call flow, dynamic config
Architecture	System design, component relationships, SWML rendering pipeline
SWAIG Reference	Complete SwaigFunctionResult API — all call control, audio, data, and action methods
DataMap Guide	Server-side tools — webhooks, expressions, templates, environment variables
Contexts & Steps	Multi-step conversation workflows, navigation, gather_info
Skills Guide	Skills framework — 18 built-in skills, custom skill development
Prefabs Guide	Pre-built agents — InfoGatherer, Survey, FAQ, Concierge, Receptionist
CLI Guide	Testing tool — dump SWML, execute tools, simulate serverless
Configuration	Constructor options, environment variables, ConfigLoader, AuthHandler
Security	Authentication, SSL/TLS, CORS, rate limiting, production checklist
Serverless Guide	Deploy to AWS Lambda, Google Cloud Functions, Azure Functions, CGI
API Reference	Complete reference for every exported class, method, and interface

Examples

See the examples/ directory:

• simple-agent.ts - Minimal agent with a tool
• pom-prompt.ts - Structured prompts with POM
• datamap-tools.ts - Server-side API tools with DataMap
• contexts-steps.ts - Multi-step conversation workflows
• multi-agent.ts - Multiple agents on one server
• dynamic-config.ts - Per-request agent customization
• call-flow.ts - Call flow verbs and recording

Run any example:

npx tsx examples/simple-agent.ts

Development

npm run build        # Compile TypeScript
npm test             # Run tests
npm run test:watch   # Watch mode
npm run dev          # Watch + rebuild

License

MIT