***

title: SwaigFunction
slug: /reference/typescript/agents/swaig-function
description: Wrapper class for SWAIG function definitions with execution and serialization.
max-toc-depth: 3
---------------------

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

[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/ai/swaig/functions

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

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

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

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>

<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.
</Info>

## **Constructor**

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

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

### SwaigFunctionOptions

<ParamField path="name" type="string" required={true} toc={true}>
  Unique name used to register and invoke this tool.
</ParamField>

<ParamField path="handler" type="SwaigHandler" required={true} toc={true}>
  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.
</ParamField>

<ParamField path="description" type="string" required={true} toc={true}>
  Human-readable description shown to the AI so it knows when to call this tool.
</ParamField>

<ParamField path="parameters" type="Record<string, unknown>" toc={true}>
  JSON Schema `properties` object describing the tool's parameters.
</ParamField>

<ParamField path="secure" type="boolean" default="false" toc={true}>
  Whether the tool requires session token authentication.
</ParamField>

<ParamField path="fillers" type={"Record<string, string[]>"} toc={true}>
  Language-keyed filler phrases to speak while the tool executes
  (e.g., `{ "en-US": ["Let me check on that..."] }`).
</ParamField>

<ParamField path="waitFile" type="string" toc={true}>
  URL of an audio file to play while the tool executes. Preferred over `fillers`.
</ParamField>

<ParamField path="waitFileLoops" type="number" toc={true}>
  Number of times to loop `waitFile`.
</ParamField>

<ParamField path="webhookUrl" type="string" toc={true}>
  External webhook URL. When set, the tool call is forwarded to this URL
  instead of being handled locally.
</ParamField>

<ParamField path="required" type="string[]" toc={true}>
  List of required parameter names.
</ParamField>

<ParamField path="extraFields" type="Record<string, unknown>" toc={true}>
  Additional fields to include in the SWAIG definition.
</ParamField>

<ParamField path="isTypedHandler" type="boolean" toc={true}>
  Whether the handler uses typed parameters.
</ParamField>

### 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**

<ParamField path="name" type="string" toc={true}>
  The tool name.
</ParamField>

<ParamField path="handler" type="SwaigHandler" toc={true}>
  The handler.
</ParamField>

<ParamField path="description" type="string" toc={true}>
  The tool description.
</ParamField>

<ParamField path="parameters" type="Record<string, unknown>" toc={true}>
  The parameter schema object.
</ParamField>

<ParamField path="secure" type="boolean" toc={true}>
  Whether token authentication is required.
</ParamField>

<ParamField path="fillers" type={"Record<string, string[]> | undefined"} toc={true}>
  Filler phrases by language code.
</ParamField>

<ParamField path="waitFile" type="string | undefined" toc={true}>
  URL of an audio file to play while the tool executes.
</ParamField>

<ParamField path="waitFileLoops" type="number | undefined" toc={true}>
  Number of times to loop `waitFile`.
</ParamField>

<ParamField path="webhookUrl" type="string | undefined" toc={true}>
  External webhook URL for remotely handled tools.
</ParamField>

<ParamField path="required" type="string[]" toc={true}>
  List of required parameter names.
</ParamField>

<ParamField path="extraFields" type="Record<string, unknown>" toc={true}>
  Additional SWAIG definition fields.
</ParamField>

<ParamField path="isTypedHandler" type="boolean" toc={true}>
  Whether the handler uses typed parameters.
</ParamField>

<ParamField path="isExternal" type="boolean" toc={true}>
  `true` when `webhookUrl` is set, indicating the tool is handled externally.
</ParamField>

## **Methods**

<CardGroup cols={2}>
  <Card title="execute" href="/docs/server-sdks/reference/typescript/agents/swaig-function/execute">
    Execute the tool with the given arguments.
  </Card>

  <Card title="toSwaig" href="/docs/server-sdks/reference/typescript/agents/swaig-function/to-swaig">
    Convert the tool to a SWAIG-compatible dictionary for SWML.
  </Card>
</CardGroup>

***

## **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();
```