ParameterSchema

ParameterSchema is a fluent builder that produces the JSON Schema parameters object for a SWAIG tool. Properties appear in the order you add them, and the result is identical to the hand-written JSON Schema object. Create one with paramSchema().

defineTool() and defineTypedTool() accept the wrapped { type: 'object', properties, required } object this builder produces, so pass build()’s result directly as parameters, as in the example below.

import { paramSchema } from '@signalwire/sdk';

Methods

Every method except build() returns the builder for chaining.

property(name, type, description?, extra?)

this

Add a property with an explicit JSON Schema type (string, number, integer, boolean, array, or object). extra merges additional JSON Schema keywords such as enum, pattern, format, or items into the property.

string(name, description?, extra?)

this

Add a string property.

integer(name, description?, extra?)

this

Add an integer property.

number(name, description?, extra?)

this

Add a number property.

boolean(name, description?, extra?)

this

Add a boolean property.

array(name, items?, description?)

this

Add an array property. items is the JSON Schema for each element, such as { type: 'string' }. Omit it for an untyped array.

enum(name, values, description?, type?)

this

Add a property constrained to a closed set of values, emitted as enum in the order given. type defaults to string.

recordFormat(name, description?)

this

Add a record_call format property with enum: ['wav', 'mp3', 'mp4'].

recordDirection(name, description?)

this

Add a record_call direction property with enum: ['speak', 'listen', 'both'].

tapDirection(name, description?)

this

Add a tap direction property with enum: ['speak', 'hear', 'both'].

codec(name, description?)

this

Add a tap codec property with enum: ['PCMU', 'PCMA'].

required(...names)

this

Mark already-added properties as required. Names are recorded in the order given; duplicates are ignored.

build()

ParameterSchemaObject

Return the plain { type: 'object', properties, required? } object. required is present only when at least one property was marked required.

Constants

The closed sets behind the typed helpers are exported as as const arrays, each with a matching union type.

RECORD_FORMATS

RecordFormat[]

['wav', 'mp3', 'mp4']

RECORD_DIRECTIONS

RecordDirection[]

['speak', 'listen', 'both']

TAP_DIRECTIONS

TapDirection[]

['speak', 'hear', 'both']

TAP_CODECS

TapCodec[]

['PCMU', 'PCMA']

Example

import { AgentBase, FunctionResult, paramSchema } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'dispatch', route: '/dispatch' });
const params = paramSchema()
  .string('pickup', 'Street address for the pickup')
  .enum('vehicle', ['sedan', 'van', 'wheelchair'], 'Vehicle type')
  .integer('passengers', 'Number of riders')
  .required('pickup', 'vehicle')
  .build();
agent.defineTool({
  name: 'book_ride',
  description: 'Book a taxi for the caller',
  parameters: params,
  handler: async (args) => {
    return new FunctionResult(`Booked a ${args.vehicle} to ${args.pickup}.`);
  },
});