AgentBase

AgentBase is the central class in the SignalWire Server SDK. It provides a complete framework for building AI-powered voice agents, combining prompt management, tool definitions, skill loading, speech configuration, and web serving into a single composable interface.

AgentBase extends SWMLService, inheriting its SWML document serving and SWAIG tool registry (the /swaig endpoint and tool registration/ dispatch live on SWMLService). On top of that, AgentBase uses composition internally, assembling functionality from PromptManager, SwmlBuilder, SessionManager, ContextBuilder, and SkillManager. All setter methods return this for fluent method chaining.

AgentBase generates a SWML document with the ai verb. See the SWML reference for the full specification of all supported parameters and behaviors.

Constructor

import { AgentBase } from '@signalwire/sdk';
const agent = new AgentBase({
  name: 'support',
  route: '/support',
});

Constructor Parameters

name

stringRequired

Display name of the agent. Used in logging, SIP username mapping, and the default prompt fallback.

route

stringDefaults to /

HTTP route path where this agent is served. Used by AgentServer when hosting multiple agents on one process.

host

stringDefaults to 0.0.0.0

Network interface the HTTP server binds to.

port

number

Port the HTTP server listens on. Defaults to the PORT environment variable, falling back to 3000.

basicAuth

[string, string]

Explicit [username, password] tuple for HTTP Basic Auth on all endpoints. If not set, credentials are read from SWML_BASIC_AUTH_USER / SWML_BASIC_AUTH_PASSWORD env vars, or auto-generated on startup.

usePom

booleanDefaults to true

Enable Prompt Object Model for structured prompt building. Set to false to use plain text prompts only.

tokenExpirySecs

numberDefaults to 3600

Expiration time in seconds for SWAIG function authentication tokens.

autoAnswer

booleanDefaults to true

Automatically add an answer verb before the AI verb in the SWML document.

recordCall

booleanDefaults to false

Enable call recording. When true, a record_call verb is added to the SWML document.

recordFormat

stringDefaults to mp4

Recording file format. Common values: "mp4", "wav".

recordStereo

booleanDefaults to true

Record in stereo (separate channels for each party) when true.

defaultWebhookUrl

string

Base URL for SWAIG function webhooks. If not set, the SDK auto-detects from the incoming request or uses SWML_PROXY_URL_BASE.

nativeFunctions

string[]

List of native SWAIG function names to enable at construction time (e.g., ["check_time", "wait_for_user"]). Can also be set later via setNativeFunctions().

agentId

string

Unique identifier for this agent instance. Auto-generated as a random hex string if not provided.

suppressLogs

boolean

Suppress SDK log output. Useful in testing or when integrating with external logging.

enablePostPromptOverride

booleanDefaults to false

When true, register the /post_prompt_override route allowing external callers to replace the post-prompt text at runtime.

checkForInputOverride

booleanDefaults to false

When true, register the /check_for_input route allowing external callers to inject input checks at runtime.

configFile

string

Path to a JSON configuration file. When provided, its service section supplies defaults for name, route, host, and port. Constructor arguments still take precedence over file values.

schemaPath

string

Path to a custom SWML JSON Schema file used for validation. Falls back to the built-in schema when omitted.

schemaValidation

booleanDefaults to true

Enable SWML schema validation on rendered documents. Can also be disabled via SWML_SKIP_SCHEMA_VALIDATION env var.

signingKey

string

SignalWire Signing Key used to verify inbound webhook signatures. When set, the agent auto-mounts webhook signature validation middleware on POST /, /swaig, and /post_prompt — unsigned or mis-signed requests receive a 403. Falls back to the SIGNALWIRE_SIGNING_KEY environment variable. When both are unset, validation is disabled and a one-time startup warning is emitted. Treat this value as a secret.

webhookTrustProxy

booleanDefaults to false

When true, the webhook validation middleware honors X-Forwarded-Proto and X-Forwarded-Host when reconstructing the public URL for signature verification. Defaults to false because those proxy headers are spoofable. SWML_PROXY_URL_BASE always takes precedence.

Properties

name

string

The agent’s display name. Set at construction time.

route

string

HTTP route path where this agent is served.

host

string

Network interface the HTTP server binds to.

port

number

Port the HTTP server listens on.

agentId

string

Unique identifier for this agent instance.

signingKey

string | null

The Signing Key used for webhook signature validation, from the constructor option or SIGNALWIRE_SIGNING_KEY. null when validation is disabled.

Static Members

PROMPT_SECTIONS

Array<{ title: string; body?: string; bullets?: string[]; numbered?: boolean }>

Class-level attribute. Subclasses can set this to declaratively define prompt sections instead of calling promptAddSection() in the constructor.

Examples

Basic agent with a tool

import { AgentBase, FunctionResult } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'support-agent', route: '/support' });
agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' });
agent.setPromptText('You are a friendly customer support agent.');
agent.addHints(['SignalWire', 'SWML', 'SWAIG']);
agent.setParams({ temperature: 0.7, end_of_speech_timeout: 1000 });
agent.defineTool({
  name: 'check_order',
  description: 'Look up the status of a customer order',
  parameters: {
    type: 'object',
    properties: {
      order_id: { type: 'string', description: 'The order ID to look up' },
    },
  },
  required: ['order_id'],
  handler: async (args) => {
    const orderId = args.order_id;
    return new FunctionResult(`Order ${orderId} shipped on March 28.`);
  },
});
await agent.run();

Subclass with declarative prompt sections

import { AgentBase, FunctionResult } from '@signalwire/sdk';
class SupportAgent extends AgentBase {
  static override PROMPT_SECTIONS = [
    {
      title: 'Role',
      body: 'You are a customer support agent for Acme Corp.',
    },
    {
      title: 'Guidelines',
      bullets: ['Be polite and professional', 'Escalate billing disputes'],
    },
  ];
  protected override defineTools(): void {
    this.defineTool({
      name: 'transfer_call',
      description: 'Transfer the caller to a live agent',
      handler: async () => {
        return new FunctionResult('Transferring now.').connect('+15551234567');
      },
    });
  }
}
const agent = new SupportAgent({ name: 'support', route: '/support' });
await agent.run();

Methods

addAnswerVerb

Configure the answer verb that connects the call.

addFunctionInclude

Add a remote function include to the SWAIG configuration.

addHint

Add a single speech recognition hint to improve transcription accuracy.

addHints

Add multiple speech recognition hints at once.

addInternalFiller

Add filler phrases for a specific function and language.

addLanguage

Add a language configuration with voice settings for multilingual conversations.

addMcpServer

Add an external MCP server for tool discovery and invocation.

addPatternHint

Add a speech recognition hint with pattern matching and replacement.

addPostAiVerb

Add a SWML verb to run after the AI conversation ends.

addPostAnswerVerb

Add a SWML verb to run after the call is answered but before the AI starts.

addPreAnswerVerb

Add a SWML verb to run before the call is answered.

addPronunciation

Add a pronunciation rule to correct how the AI speaks a specific word or phrase.

addSkill

Load and activate a skill on the agent.

addSkillByName

Look up a skill class in the global registry and add it by name.

removeSkillByName

Remove every skill instance matching a given name.

resetContexts

Clear every context from the agent’s ContextBuilder.

getPromptPom

Return the current POM-structured prompt.

setPromptPom

Replace the prompt with the supplied POM array.

setPronunciations

Replace every pronunciation rule in a single call.

setInternalFillers

Set every internal-filler entry in one call.

setFunctionIncludes

Replace the SWAIG function-includes list.

autoMapSipUsernames

Auto-register the agent’s route as the SIP username target.

validateToolToken

Validate a per-tool HMAC token.

clearSwaigQueryParams

Remove every SWAIG query-param override.

enableDebugRoutes

Expose the agent’s debug HTTP endpoints.

addSwaigQueryParams

Append query parameters to all SWAIG webhook URLs.

asRouter

Get the agent’s Hono app for mounting as a sub-router.

clearPostAiVerbs

Remove all post-AI verbs from the call flow.

clearPostAnswerVerbs

Remove all post-answer verbs from the call flow.

clearPreAnswerVerbs

Remove all pre-answer verbs from the call flow.

defineContexts

Define multi-step conversation contexts and workflows.

defineTool

Define a SWAIG tool that the AI can invoke during conversations.

defineTypedTool

Define a tool with a typed handler and automatic schema inference.

defineTools

Override hook that registers tools during construction.

enableDebugEvents

Enable real-time debug event webhooks from the AI module during calls.

enableMcpServer

Expose the agent’s tools as an MCP server endpoint.

enableSipRouting

Enable SIP-based call routing for this agent.

extractSipUsername

Extract a SIP username from a request body (static method).

getApp

Get the Hono application instance.

getBasicAuthCredentials

Retrieve the agent’s Basic Auth credentials and their origin.

getFullUrl

Get the full URL for this agent’s endpoint.

getMcpServers

Get the list of configured MCP servers.

getName

Get the agent’s display name.

getPostPrompt

Retrieve the current post-prompt text.

getPrompt

Retrieve the current rendered prompt text.

getRegisteredTools

Get summaries of all registered tools.

getTool

Look up a registered tool by name.

handleMcpRequest

Handle an MCP JSON-RPC 2.0 request.

hasSkill

Check whether a specific skill is currently loaded.

isMcpServerEnabled

Check if the MCP server endpoint is enabled.

listSkills

List all currently loaded skills.

manualSetProxyUrl

Manually set the proxy URL base for webhook callbacks.

setNativeFunctions

Set the list of native platform functions.

onDebugEvent

Lifecycle hook for debug events received at /debug_events.

onFunctionCall

Pre-execution hook called before each SWAIG function invocation.

onSummary

Handle post-prompt summaries generated after a conversation ends.

onSwmlRequest

Lifecycle hook called on every SWML request before rendering.

promptAddSection

Add a new section to the agent’s structured prompt.

promptAddSubsection

Add a subsection to an existing prompt section.

promptAddToSection

Append content to an existing prompt section.

promptHasSection

Check whether a named section exists in the agent’s prompt.

registerSipUsername

registerSwaigFunction

removeSkill

Unload a skill from the agent.

renderSwml

Render the complete SWML document.

run

Start the HTTP server (alias for serve).

serve

Start the Hono HTTP server to serve SWML and SWAIG endpoints.

setDynamicConfigCallback

Set a callback for per-request dynamic agent configuration.

setGlobalData

Replace the global data object available to the AI.

setLanguages

Replace all language configurations at once.

setParam

Set a single AI parameter by key.

setParams

Configure AI model parameters such as temperature and timeouts.

setPostPrompt

Set the post-prompt for generating call summaries.

setPostPromptLlmParams

Set LLM parameters for the post-prompt.

setPostPromptUrl

Override the URL where post-prompt summaries are delivered.

setPromptLlmParams

Set LLM parameters for the main prompt.

setPromptText

Set the agent’s system prompt as raw text.

setupGracefulShutdown

setWebHookUrl

Override the default webhook URL for SWAIG function calls.

updateGlobalData

Merge data into the global data object.

validateBasicAuth

Custom basic-auth validation hook.

onRequest

Public hook called on every inbound request before rendering.

pom

Get the agent’s prompt as a PromptObjectModel snapshot.

getRawPrompt

Retrieve the raw stored prompt text, unrendered.

getContexts

Retrieve the agent’s contexts as a serialized dictionary.

createToolToken

Create a per-call SWAIG token for a tool.

setLanguageParams

Set engine-specific params on an added language.

getLanguageParams

Read engine-specific params on an added language.

setMultilingual

Answer in whatever language the caller speaks.

onError

Hook that runs when any tool handler throws.

replaceGlobalData

Replace the global data object, discarding prior keys.

registerRoutingCallback

Route requests dynamically from the POST body.

handleRequest

Dispatch a request from plain HTTP primitives.