AgentsCLI Tools

swaig-test

View as MarkdownOpen in Claude

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.

--header
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.

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

CodeMeaning
0Success
1Error (file not found, invalid arguments, execution failure)