For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
GuidesReference
GuidesReference
    • Core
      • Overview
    • Agents
      • Overview
      • AgentBase
      • AgentServer
      • BedrockAgent
      • CLI Tools
        • mcp-gateway
        • sw-agent-dokku
        • sw-agent-init
        • sw-search
        • swaig-test
      • Configuration
      • ContextBuilder
      • DataMap
      • FunctionResult
      • Helper Functions
      • LiveWire
      • MCP Gateway
      • PomBuilder
      • Prefabs
      • Search
      • SkillBase
      • Skills
      • SWAIGFunction
      • SWMLBuilder
      • SWMLService
      • WebService
    • RELAY
      • Overview
      • Actions
      • Call
      • Constants
      • Events
      • Message
      • RelayClient
      • RelayError
    • REST Client
      • Overview
      • Addresses
      • Calling
      • Chat
      • Compat
      • Datasphere
      • Fabric
      • Imported Numbers
      • Logs
      • Lookup
      • MFA
      • Number Groups
      • Phone Numbers
      • Project
      • PubSub
      • Queues
      • Recordings
      • Registry
      • RestClient
      • Short Codes
      • SignalWireRestError
      • SIP Profile
      • Verified Callers
      • Video
LogoLogoSignalWire Docs
Log inSign up
Support
On this page
  • Actions
  • Common Options
  • Function Execution Options
  • SWML Generation Options
  • Data Customization
  • Serverless Simulation
  • Platform-Specific Options
  • Extended Help
  • Examples
  • List Tools and Generate SWML
  • Execute Functions
  • Multi-Agent Files
  • Dynamic Agent Testing
  • Serverless Simulation
  • Exit Codes
AgentsCLI Tools

swaig-test

|View as Markdown|Open in Claude|
Was this page helpful?
Edit this page
Previous

Configuration

Next
Built with

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)