> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# swaig-test

> Test SWAIG functions and generate SWML documents locally without deploying.

[ref-datamap]: /docs/server-sdks/reference/python/agents/data-map

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][ref-datamap] functions.

```bash
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`** `string` — default: \{}

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

---

## SWML Generation Options

**`--call-type`** `string` — default: webrtc

Simulated call type. Valid values:

* `"sip"` -- SIP-originated call
* `"webrtc"` -- WebRTC-originated call

---

**`--call-direction`** `string` — default: inbound

Simulated call direction. Valid values:

* `"inbound"` -- incoming call
* `"outbound"` -- outgoing call

---

**`--call-state`** `string` — default: 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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) |