SWAIG-TEST(1)

NAME
swaig-test - test SWAIG functions and generate SWML documents for SignalWire AI agents

SYNOPSIS
swaig-test agent_path [options]
swaig-test agent_path --exec function_name [function_arguments]
swaig-test agent_path --dump-swml [options]

DESCRIPTION
swaig-test is a command-line tool for testing SignalWire AI Agent Interface (SWAIG) functions and generating SWML (SignalWire Markup Language) documents. It allows developers to test their agents locally without deploying to a server, simulate various call scenarios, and verify function behavior.

The tool loads a Python file containing one or more SignalWire agents, discovers the available SWAIG functions, and allows interactive testing with simulated call data. It supports both webhook-based functions and DataMap functions.

ARGUMENTS

agent_path
    Path to the Python file containing the SignalWire agent definition. This file should contain a class inheriting from AgentBase or an instantiated agent object.

OPTIONS

  Common Options

-h, --help
    Display help message and exit.

-v, --verbose
    Enable verbose output. Shows detailed information about function execution, post data, and results.

--raw
    Output raw JSON only, suitable for piping to tools like jq(1). Suppresses all decorative output and logging.

--agent-class CLASS
    Specify which agent class to use when the file contains multiple agent definitions. Required if the file has more than one agent.

--route ROUTE
    Specify service by route (e.g., /healthcare, /finance). Alternative to --agent-class for selecting agents.

  Actions (choose one)

--list-agents
    List all agents found in the specified file, showing their class names, types (class or instance), routes, and descriptions.

--list-tools
    List all SWAIG tools (functions) available in the agent, including their names, descriptions, and parameter schemas.

--dump-swml
    Generate and output the complete SWML document that would be returned by the agent. Useful for debugging agent configuration.

--exec FUNCTION
    Execute the specified function with arguments provided after the function name. All options must appear BEFORE --exec.

  Function Execution Options

--custom-data JSON
    JSON string with custom post_data overrides for function execution.

--minimal
    Use minimal post_data for function execution. Only includes essential fields required for the function call.

--fake-full-data
    Use comprehensive fake post_data including simulated call metadata, SIP headers, and user variables.

  SWML Generation Options

--call-type TYPE
    Set the call type for SWML generation. Valid values are sip or webrtc. Default is webrtc.

--call-direction DIR
    Set the call direction. Valid values are inbound or outbound. Default is inbound.

--call-state STATE
    Set the call state. Default is "created".

--from-number NUMBER
    Override the "from" phone number in the simulated call data.

--to-extension EXT
    Override the "to" extension in the simulated call data.

  Data Customization

--user-vars JSON
    JSON string for userVariables to include in the request.

--query-params JSON
    JSON string for query parameters to include in the request.

--override KEY=VALUE
    Override a specific value in the post data using dot notation. Can be specified multiple times. Example: --override call.state=answered

--header KEY=VALUE
    Add an HTTP header to the simulated request. Can be specified multiple times. Example: --header Authorization="Bearer token"

  Serverless Simulation

--simulate-serverless PLATFORM
    Simulate a serverless platform environment. Valid platforms are:

    •   lambda - AWS Lambda

    •   cgi - CGI environment

    •   cloud_function - Google Cloud Functions

    •   azure_function - Azure Functions

--env KEY=VALUE
    Set an environment variable for the simulation. Can be specified multiple times.

--env-file FILE
    Load environment variables from a file.

--help-platforms
    Show detailed help for platform-specific serverless options.

--help-examples
    Show comprehensive usage examples.

  Platform-Specific Options
These options are used with --simulate-serverless. Use --help-platforms for complete documentation.

--aws-function-name NAME
    AWS Lambda function name.

--aws-region REGION
    AWS region.

--cgi-host HOST
    CGI server hostname (required for CGI simulation).

--cgi-https
    Use HTTPS for CGI URLs.

--gcp-project ID
    Google Cloud project ID.

--azure-env ENV
    Azure Functions environment.

EXAMPLES

  Basic Usage
List all tools in an agent:

    swaig-test agent.py
    swaig-test agent.py --list-tools

  Executing Functions
Execute a function with arguments:

    swaig-test agent.py --exec search --query "AI" --limit 5
    swaig-test agent.py --verbose --exec get_info --topic "weather"

Important: All options (like --verbose, --call-id) must come BEFORE --exec. Everything after --exec function_name is treated as function arguments.

Correct:
    swaig-test agent.py --call-id my-session --exec add_todo --text "Buy milk"

Incorrect (won't work):
    swaig-test agent.py --exec add_todo --text "Buy milk" --call-id my-session

  SWML Generation
Generate SWML document:

    swaig-test agent.py --dump-swml
    swaig-test agent.py --dump-swml --raw | jq '.'
    swaig-test agent.py --dump-swml --call-type sip --from-number +15551234567

Extract specific fields:

    swaig-test agent.py --dump-swml --raw | jq '.sections.main[1].ai.SWAIG.functions'

  Multi-Agent Files
When a file contains multiple agents:

    swaig-test multi_agent.py --list-agents
    swaig-test multi_agent.py --agent-class MattiAgent --list-tools
    swaig-test multi_agent.py --route /healthcare --exec schedule_appointment

  Serverless Simulation
Test with AWS Lambda simulation:

    swaig-test agent.py --simulate-serverless lambda --dump-swml
    swaig-test agent.py --simulate-serverless lambda \
      --env API_KEY=secret \
      --exec my_function

Test with CGI simulation:

    swaig-test agent.py --simulate-serverless cgi \
      --cgi-host example.com \
      --cgi-https \
      --dump-swml

  Dynamic Configuration
Test agents with dynamic configuration:

    swaig-test agent.py --dump-swml \
      --query-params '{"tier":"premium"}' \
      --header "Authorization=Bearer token" \
      --user-vars '{"language":"es"}'

EXIT STATUS

0   Successful execution.

1   An error occurred. Check stderr for details.

ENVIRONMENT

SIGNALWIRE_LOG_MODE
    Controls logging verbosity. Set to "off" to suppress logs. Automatically set to "off" when using --raw or --dump-swml.

FILES

agent.py
    A Python file containing one or more SignalWire agent definitions. The file should import from signalwire_agents and define classes inheriting from AgentBase.

SEE ALSO
sw-agent-init(1), sw-search(1), jq(1)

SignalWire AI Agents SDK documentation: https://github.com/signalwire/signalwire-agents

AUTHORS
SignalWire Team <info@signalwire.com>

COPYRIGHT
Copyright (c) 2025 SignalWire. Licensed under the MIT License.