swaig-test

The swaig-test command loads an agent file and lets you render its SWML, list its SWAIG functions, call a function, and simulate serverless environments, all without deploying. It supports webhook functions, DataMap functions, and functions that point at an external webhook URL.

npx swaig-test <agent-file> [options]

swaig-test sends its requests through the agent’s own HTTP app, the way SignalWire would. It fetches the agent’s SWML with a simulated call, so basic auth, signature checks, the dynamic configuration callback, and function tokens all run as they do on a server. The callback runs once for --dump-swml. --exec reads the function from that SWML and calls it at the web_hook_url the SWML gives it. A DataMap function runs in a local DataMap simulator, and a function whose URL points elsewhere is called at that URL.

The agent file can be .ts, .js, .mjs, or .mts. The command picks the agent to test in this order:

The export named by --agent-class, either an instance or a class to instantiate.
With --route, the service whose route matches.
The export named agent, then the default export, then any exported instance, then any exported class.
An agent the file creates without exporting it, as in the quickstart.

One action flag is required. A target with no action exits with Error: one of --dump-swml, --list-tools, or --exec is required. The one exception is --simulate-serverless, which renders SWML for the platform on its own. Running swaig-test with no arguments prints the help text.

Options accept both --name value and --name=value. For -h, --help, --help-platforms, --help-examples, and --parse-only, see Help and validation.

Actions

Choose one action per invocation:

--list-tools

flag

List the agent’s SWAIG functions with their parameters. Each function is labeled LOCAL webhook or EXTERNAL webhook (with its URL); a DataMap function carries no label. With --raw or --format-json, prints a JSON array of name, description, parameters, and type, plus web_hook_url for an external function.

--list-agents

flag

List the agents and services exported from the file, with each instance’s name and route. Useful for multi-agent files. Exits 1 when the file has none. With --raw or --format-json, prints JSON, an empty array when the file has none, and exits 0.

--dump-swml

flag

Print the SWML document the agent serves, as indented JSON. Combine with --raw for compact JSON that suppresses logs.

--exec NAME

string

Call a SWAIG function by name. Everything after the function name belongs to the function, so put swaig-test’s own options before --exec. Pass arguments as --name value (see Function arguments). --exec with no function name, or followed directly by another -- option, exits with --exec requires a function name.

Common options

--raw

flag

Output raw JSON only, suppressing all logs. Designed for piping to jq.

-v, --verbose

flag

Enable verbose output with debug information: the request being sent, the function’s arguments, and, for --list-tools, each function’s full configuration.

--format-json

flag

Print the result as indented JSON.

--agent-class

string

Name of the exported agent class or instance to use. Cannot be combined with --route.

--route

string

Use the service with this route, such as /sales. Cannot be combined with --agent-class.

Function arguments

After --exec <function>, pass each argument as --name value. swaig-test types the value by the function’s parameter schema and converts dashes in the name to underscores.

Parameter type	How the value is read
`string`	Used as given
`integer`	Parsed as an integer; anything else is an error
`number`	Parsed as a number; anything else is an error
`array`	Split on commas
`boolean`	`true` or `false` after the name, or the bare flag for `true`

--arg name=value also works: the value is parsed as JSON, and falls back to a string. An argument the function doesn’t declare is still passed to the function, with a warning. A swaig-test option placed after --exec, such as --verbose, is read as a function argument; put it before --exec.

Function execution options

--minimal

flag

Send the smallest function request: the call ID and the arguments.

--fake-full-data

flag

Send a request with every key SignalWire may send. This is the default.

--custom-data

string

A JSON object merged into the function request. For a DataMap function, it supplies the call data the simulator reads, such as global_data. Without a global_data key, the simulator uses the global_data in the agent’s SWML.

Call and request options

These apply to --dump-swml, --list-tools, and --exec.

--call-type

stringDefaults to webrtc

Simulated call type: sip or webrtc.

--call-direction

stringDefaults to inbound

Simulated call direction: inbound or outbound.

--call-state

stringDefaults to created

Call state, set as call.state.

--call-id

string

The call_id the simulated request carries.

--project-id

string

Sets call.project_id.

--space-id

string

Sets call.space_id.

--from-number

string

Sets call.from, the caller’s address.

--to-extension

string

Sets call.to, the destination.

--user-vars

string

A JSON object set as vars.userVariables.

--query-params

string

A JSON object of query parameters for the SWML request. They are also added to vars.userVariables. Use this to test a dynamic configuration callback that reads the query string.

--header NAME=VALUE

string

A request header. Repeatable.

--method

stringDefaults to POST

Method of the SWML request: POST or GET. A GET request carries the call ID and query parameters in the query string.

--body

string

A JSON object of extra fields merged into the SWML request body.

--override PATH=VALUE

string

Set a value in the simulated request by dotted path, such as call.state=answered. The value is read as null, true, false, a number, JSON, or a string, in that order. Repeatable. A path the simulated request doesn’t contain adds a key and prints a warning.

--override-json PATH=JSON

string

Like --override, but the value must be JSON. Repeatable.

Environment and serverless simulation

--simulate-serverless

string

Run with a serverless platform’s environment, so the SWML’s webhook URLs are the platform’s. Valid values are lambda, cgi, gcf, and azure; cloud_function and azure_function are accepted as aliases. Any other value exits with an error naming the supported set. The simulated environment replaces other platforms’ variables set in your shell, and your shell’s variables are restored afterward.

--env KEY=VALUE

string

Set an environment variable. Repeatable. Applied after --env-file.

--env-file

string

Load environment variables from a file, one KEY=VALUE per line. Blank lines and lines starting with # are skipped, and matching quotes around a value are removed.

AWS Lambda

Use with --simulate-serverless lambda.

--aws-function-name

string

Function name (AWS_LAMBDA_FUNCTION_NAME).

--aws-function-url

string

Function URL (AWS_LAMBDA_FUNCTION_URL).

--aws-region

string

Region (AWS_REGION).

--aws-api-gateway-id

string

Serve at an API Gateway URL, https://ID.execute-api.REGION.amazonaws.com/STAGE. Ignored, with a warning, when --aws-function-url is set.

--aws-stage

stringDefaults to prod

API Gateway stage. Applies only with --aws-api-gateway-id.

CGI

Use with --simulate-serverless cgi.

--cgi-host

stringRequired

Server host name. Required with --simulate-serverless cgi.

--cgi-script-name

string

Script path (SCRIPT_NAME).

--cgi-https

flag

Serve over HTTPS.

--cgi-path-info

string

PATH_INFO.

Google Cloud Functions

Use with --simulate-serverless gcf.

--gcp-project

string

Project (GOOGLE_CLOUD_PROJECT).

--gcp-function-url

string

Function URL (FUNCTION_URL).

--gcp-region

string

Region (GOOGLE_CLOUD_REGION).

--gcp-service

string

Service name (K_SERVICE).

Azure Functions

Use with --simulate-serverless azure.

--azure-env

string

Environment (AZURE_FUNCTIONS_ENVIRONMENT).

--azure-function-url

string

Function URL (AZURE_FUNCTION_URL).

Help and validation

--parse-only

flag

Validate the command-line arguments, print parse OK, and exit without loading the agent file, touching the filesystem, or making network requests. --dry-run is an alias. Accepted anywhere on the command line, including after --exec.

-h, --help

flag

Print the help text. It ends with a pointer to sw-tsdocs.

--help-platforms

flag

Print the serverless platform options.

--help-examples

flag

Print usage examples.

Examples

The examples below run against this agent:

agent.ts

import { AgentBase, FunctionResult } from '@signalwire/sdk';
export const agent = new AgentBase({ name: 'ride-desk', route: '/' });
agent.setPromptText('You are a dispatcher for a taxi company.');
agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rachel' });
agent.defineTool({
  name: 'book_ride',
  description: 'Book a taxi',
  parameters: {
    type: 'object',
    properties: {
      pickup: { type: 'string', description: 'Pickup address' },
      passengers: { type: 'integer', description: 'Number of passengers' },
    },
    required: ['pickup'],
  },
  handler: (args) =>
    new FunctionResult(`Booked a ride from ${args.pickup} for ${args.passengers ?? 1}.`),
});

List tools

npx swaig-test agent.ts --list-tools

Available SWAIG functions:
  book_ride - Book a taxi (LOCAL webhook)
    Parameters:
      pickup (string) (required): Pickup address
      passengers (integer): Number of passengers

Generate SWML

# Print the SWML document
npx swaig-test src/agent.ts --dump-swml
# Compact JSON for piping
npx swaig-test src/agent.ts --dump-swml --raw | jq '.sections.main'
# Render the SWML a dynamic agent serves for a request
npx swaig-test src/agent.ts --dump-swml \
  --query-params '{"tier":"premium"}' \
  --header "X-Customer-ID=12345"

Execute functions

npx swaig-test agent.ts --exec book_ride --pickup "123 Gough Street" --passengers 2

RESULT:
Response: Booked a ride from 123 Gough Street for 2.

# Options for swaig-test go before --exec
npx swaig-test src/agent.ts --verbose --exec search --query test --limit 5
# Change the simulated call
npx swaig-test src/agent.ts --call-type sip --call-state answered \
  --exec transfer --dest sales
# Set a value by dotted path
npx swaig-test src/agent.ts --override call.project_id=my-project --dump-swml
# The older --arg form still works
npx swaig-test src/agent.ts --exec search --arg query="AI agents"

Multi-agent files

npx swaig-test multi-agent.ts --list-agents

Agents found in multi-agent.ts:
  sales (instance)
    Name: sales
    Route: /sales
  support (instance)
    Name: support
    Route: /support

# Target a service by route
npx swaig-test multi-agent.ts --route /sales --list-tools
# Or target an export by name
npx swaig-test src/agents.ts --agent-class SalesAgent --list-tools

Serverless simulation

# AWS Lambda in a chosen region
npx swaig-test src/agent.ts --simulate-serverless lambda \
  --aws-region us-west-2 --dump-swml
# CGI over HTTPS
npx swaig-test src/agent.ts --simulate-serverless cgi \
  --cgi-host example.com --cgi-https --exec my_function
# Google Cloud Functions, with environment variables
npx swaig-test src/agent.ts --simulate-serverless gcf \
  --env SWML_BASIC_AUTH_USER=user \
  --env-file .env --dump-swml

Validate arguments only

npx swaig-test src/agent.ts --parse-only

parse OK

Exit codes

Code	Meaning
`0`	Success
`1`	Runtime failure: the agent file didn’t load, the function wasn’t found, an argument didn’t fit its type, or the function call returned a non-2xx status
`2`	Usage error: an unknown option, a missing value or agent file, conflicting options, or no action given