> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# SwaigFunction

> Wrapper class for SWAIG function definitions with execution and serialization.

[agent-tool-decorator]: /docs/server-sdks/reference/typescript/agents/agent-base#tool

[define-tool]: /docs/server-sdks/reference/typescript/agents/agent-base/define-tool

[agentbase]: /docs/server-sdks/reference/typescript/agents/agent-base

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

[functionresult]: /docs/server-sdks/reference/typescript/agents/function-result

[swaig-function-definition]: /docs/swml/reference/calling/ai/swaig/functions

[swml-swaig-functions-reference]: /docs/swml/reference/calling/ai/swaig/functions

[execute]: /docs/server-sdks/reference/typescript/agents/swaig-function/execute

[toswaig]: /docs/server-sdks/reference/typescript/agents/swaig-function/to-swaig

[validateargs]: /docs/server-sdks/reference/typescript/agents/swaig-function/validate-args

SwaigFunction wraps a function as a SWAIG (SignalWire AI Gateway) tool
that the AI can invoke during a conversation. It manages the function's name,
description, parameter schema, security settings, and serialization to SWML.

In most cases you do not create SwaigFunction instances directly. The
[`defineTool()`][define-tool] method
on [`AgentBase`][agentbase] handles construction
internally. This class is documented for advanced use cases such as custom
registration via `registerSwaigFunction()`.

> **Info**
>
> For server-side API tools without a handler, see
> [`DataMap`][datamap]. For building the
> response returned from a handler, see
> [`FunctionResult`][functionresult].

> **Info**
>
> SwaigFunction serializes to a SWML [SWAIG function definition][swaig-function-definition].
> See the [SWML SWAIG functions reference][swml-swaig-functions-reference] for the
> full specification.

## **Constructor**

```typescript {3}
import { SwaigFunction } from '@signalwire/sdk';

const fn = new SwaigFunction(opts);
```

### SwaigFunctionOptions

**`name`** `string` — required

Unique name used to register and invoke this tool.

---

**`handler`** `SwaigHandler` — required

The handler invoked when the AI calls this tool. Receives parsed
arguments and optional raw request data. Can return a `FunctionResult`,
a plain object, or a string. May be async.

---

**`description`** `string` — required

Human-readable description shown to the AI so it knows when to call this tool.

---

**`parameters`** `Record<string, unknown>`

JSON Schema `properties` object describing the tool's parameters.

---

**`secure`** `boolean` — default: true

Whether the tool requires session token authentication. Pass `false` to
expose the tool on the shared, unauthenticated webhook URL.

---

**`fillers`** `Record<string, string[]>`

Language-keyed filler phrases to speak while the tool executes
(e.g., `{ "en-US": ["Let me check on that..."] }`).

---

**`waitFile`** `string`

URL of an audio file to play while the tool executes. Preferred over `fillers`.

---

**`waitFileLoops`** `number`

Number of times to loop `waitFile`.

---

**`webhookUrl`** `string`

External webhook URL. When set, the tool call is forwarded to this URL
instead of being handled locally.

---

**`required`** `string[]`

List of required parameter names.

---

**`extraFields`** `Record<string, unknown>`

Additional fields to include in the SWAIG definition.

---

**`isTypedHandler`** `boolean`

Whether the handler uses typed parameters.

---

### SwaigHandler type

```typescript {1}
type SwaigHandler = (
  args: Record<string, unknown>,
  rawData: Record<string, unknown>,
) => FunctionResult | Record<string, unknown> | string
   | Promise<FunctionResult | Record<string, unknown> | string>;
```

## **Properties**

**`name`** `string`

The tool name.

---

**`handler`** `SwaigHandler`

The handler.

---

**`description`** `string`

The tool description.

---

**`parameters`** `Record<string, unknown>`

The parameter schema object.

---

**`secure`** `boolean`

Whether token authentication is required.

---

**`fillers`** `Record<string, string[]> | undefined`

Filler phrases by language code.

---

**`waitFile`** `string | undefined`

URL of an audio file to play while the tool executes.

---

**`waitFileLoops`** `number | undefined`

Number of times to loop `waitFile`.

---

**`webhookUrl`** `string | undefined`

External webhook URL for remotely handled tools.

---

**`required`** `string[]`

List of required parameter names.

---

**`extraFields`** `Record<string, unknown>`

Additional SWAIG definition fields.

---

**`isTypedHandler`** `boolean`

Whether the handler uses typed parameters.

---

**`isExternal`** `boolean`

`true` when `webhookUrl` is set, indicating the tool is handled externally.

---

## **Methods**

#### [execute](/docs/server-sdks/reference/typescript/agents/swaig-function/execute)

Execute the tool with the given arguments.

#### [toSwaig](/docs/server-sdks/reference/typescript/agents/swaig-function/to-swaig)

Convert the tool to a SWAIG-compatible dictionary for SWML.

#### [validateArgs](/docs/server-sdks/reference/typescript/agents/swaig-function/validate-args)

Validate arguments against the parameter JSON Schema.

---

## **Examples**

### Manual registration

```typescript {3}
import { AgentBase, SwaigFunction, FunctionResult } from '@signalwire/sdk';

const fn = new SwaigFunction({
  name: 'lookup_account',
  description: 'Look up account status by ID',
  handler: async (args) => {
    const accountId = args.account_id as string;
    return new FunctionResult(`Account ${accountId} is active.`);
  },
  parameters: {
    type: 'object',
    properties: {
      account_id: { type: 'string', description: 'The account ID to look up' },
    },
    required: ['account_id'],
  },
  secure: true,
  fillers: { 'en-US': ['Let me check on that...'] },
});

const agent = new AgentBase({ name: 'my-agent' });
agent.registerSwaigFunction(fn);
await agent.serve();
```

### Using defineTool (preferred)

In most cases, use `defineTool()` instead of constructing SwaigFunction directly:

```typescript {6}
import { AgentBase, FunctionResult } from '@signalwire/sdk';

const agent = new AgentBase({ name: 'my-agent' });
agent.setPromptText('You are a helpful assistant.');

agent.defineTool({
  name: 'lookup_account',
  description: 'Look up account status by ID',
  parameters: {
    type: 'object',
    properties: {
      account_id: { type: 'string', description: 'Account ID' },
    },
    required: ['account_id'],
  },
  secure: true,
  handler: async (args) => {
    const accountId = args.account_id as string;
    return new FunctionResult(`Account ${accountId} is active.`);
  },
});

await agent.serve();
```

> Wrapper class for SWAIG function definitions with execution and serialization.

## Docs

- [execute](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swaig-function/execute.md): Execute the function with the given arguments.
- [toSwaig](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swaig-function/to-swaig.md): Convert the function to a SWAIG-compatible object for SWML.
- [validateArgs](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swaig-function/validate-args.md): Validate arguments against the parameter JSON Schema.