swaig-test

The swaig-test command loads an agent file and allows you to test SWAIG functions, generate SWML output, and simulate serverless environments — all without deploying to production. It supports both webhook and DataMap functions.

swaig-test <agent_path> [options]

If no action flag is specified, swaig-test defaults to --list-tools.

Actions

Choose one action per invocation:

--list-tools

flag

List all SWAIG functions registered on the agent.

--list-agents

flag

List all agent classes discovered in the file. Useful for multi-agent files.

--dump-swml

flag

Generate and output the full SWML document. Combine with --raw for machine-readable JSON.

--exec FUNCTION

string

Execute a SWAIG function by name. Pass function arguments as --key value pairs after the function name.

Common options

-v, --verbose

flag

Enable verbose output with debug information, including raw result types and detailed post data.

--raw

flag

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

--agent-class

string

Specify which agent class to load when the file contains multiple agents. Mutually exclusive with --route.

--route

string

Specify which agent to load by its registered route (e.g., /healthcare). Mutually exclusive with --agent-class.

Function execution options

--minimal

flag

Use minimal post_data containing only the function arguments. This is the default behavior.

--fake-full-data

flag

Use comprehensive fake call data including call_id, from, to, and other fields that would normally be present in a real SignalWire request.

--custom-data

stringDefaults to {}

JSON string with custom post_data overrides merged into the request payload.

SWML generation options

--call-type

stringDefaults to webrtc

Simulated call type. Valid values:

"sip" — SIP-originated call
"webrtc" — WebRTC-originated call

--call-direction

stringDefaults to inbound

Simulated call direction. Valid values:

"inbound" — incoming call
"outbound" — outgoing call

--call-state

stringDefaults to created

Simulated call state value.

--from-number

string

Override the caller/from phone number in mock data.

--to-extension

string

Override the destination/to extension in mock data.

Data customization

--user-vars

string

JSON string injected as userVariables in the mock request. Used to test agents that customize behavior based on user variables.

--query-params

string

JSON string injected as query parameters in the mock request. Used to test dynamic agents that read query parameters.

string

Add an HTTP header in KEY=VALUE format. Can be specified multiple times.

--override

string

Override a specific value using dot-path notation (e.g., --override call.state=answered). Can be specified multiple times.

Serverless simulation

--simulate-serverless

string

Simulate a serverless platform environment. Valid values:

"lambda" — AWS Lambda
"cgi" — CGI deployment
"cloud_function" — Google Cloud Functions
"azure_function" — Azure Functions

The simulator sets platform-specific environment variables so the agent generates correct webhook URLs for the target platform.

--env

string

Set an environment variable in KEY=VALUE format. Can be specified multiple times. Applied after --env-file.

--env-file

string

Load environment variables from a file (one KEY=VALUE per line).

Platform-specific options

Run swaig-test agent.py --help-platforms for the full list. Key options per platform:

AWS Lambda: --aws-function-name, --aws-function-url, --aws-region, --aws-api-gateway-id, --aws-stage

CGI: --cgi-host (required), --cgi-script-name, --cgi-https, --cgi-path-info

Google Cloud: --gcp-project, --gcp-function-url, --gcp-region, --gcp-service

Azure: --azure-env, --azure-function-url

Extended help

--help-platforms

flag

Show detailed documentation for all serverless platform options.

--help-examples

flag

Show comprehensive usage examples covering all features.

--parse-only, --dry-run

flag

Validate the invocation’s arguments and exit without loading the agent or touching the network. Prints parse OK on success and exits non-zero on invalid arguments. Useful for checking documented commands in CI.

Examples

List tools and generate SWML

# List all registered SWAIG functions
swaig-test agent.py --list-tools
# Generate SWML document (pretty-printed)
swaig-test agent.py --dump-swml
# Generate raw JSON for piping
swaig-test agent.py --dump-swml --raw | jq '.'
# Extract just the SWAIG functions from SWML
swaig-test agent.py --dump-swml --raw | jq '.sections.main[1].ai.SWAIG.functions'

Execute functions

# Execute with CLI-style arguments
swaig-test agent.py --exec search --query "AI agents" --limit 5
# Execute with verbose debug output
swaig-test agent.py --verbose --exec search --query "test"
# Execute with fake call data for realistic testing
swaig-test agent.py --exec book_appointment \
  --name "John" --date "2025-01-20" \
  --fake-full-data --verbose

Arguments are automatically type-converted: numeric values become integers or floats, true/false become booleans, and everything else stays as a string.

Multi-agent files

# Discover agents in the file
swaig-test multi_agent.py --list-agents
# Target a specific agent by class name
swaig-test multi_agent.py --agent-class SalesAgent --list-tools
# Target a specific agent by route
swaig-test multi_agent.py --route /support --exec create_ticket --issue "Login problem"

Dynamic agent testing

# Test with query parameters
swaig-test dynamic_agent.py --dump-swml --query-params '{"tier":"premium"}'
# Test with headers and user variables
swaig-test dynamic_agent.py --dump-swml \
  --query-params '{"tier":"premium","region":"eu"}' \
  --header "X-Customer-ID=12345" \
  --user-vars '{"preferences":{"language":"es"}}'

Serverless simulation

# AWS Lambda
swaig-test agent.py --simulate-serverless lambda \
  --aws-function-name prod-agent \
  --aws-region us-west-2 \
  --dump-swml
# CGI with HTTPS
swaig-test agent.py --simulate-serverless cgi \
  --cgi-host example.com \
  --cgi-https \
  --dump-swml
# Google Cloud Functions
swaig-test agent.py --simulate-serverless cloud_function \
  --gcp-project my-project \
  --dump-swml
# With environment variables
swaig-test agent.py --simulate-serverless lambda \
  --env API_KEY=secret123 \
  --env-file .env \
  --exec my_function

Exit codes

Code	Meaning
`0`	Success
`1`	Error (file not found, invalid arguments, execution failure)