SemanticGate

A semantic gate is a yes/no question about the call that must pass before a SWAIG function runs. Attach gates with the gates option on defineTool() or defineTypedTool(), or with DataMap.gate(). A function takes 1 to 8 gates (see the constants). A decision model checks all of them together right before the function would run. If any gate fails, the function doesn’t run, and the AI gets the on_fail output of the first failing gate in list order.

The decision model reads conversation (the recent dialogue), semantic_state (the call’s global_data.semantic_state, or {}), and proposed_function (the function’s name, description, and the arguments the AI is calling it with), plus visual_input (the caller’s newest video frames) when a gate sets visualInput. Name what each question is about with those names in backticks. They label what the decision model reads; nothing is substituted. The decision model reads literally and doesn’t do arithmetic or compare dates, so put a computed result in the state with setSemanticState() instead of asking for it.

Gates map to the SWML gate object. For how to write questions and pick thresholds, see the semantic gates guide. Call-wide settings are on setSemanticGates().

The SDK checks gates when the tool is defined, and again when the SWML is rendered, and throws for anything the platform would refuse. That includes gates on these function names: startup_hook, hangup_hook, check_for_input, end_call, hangup, check_time, wait_for_user, wait_seconds, adjust_response_latency, next_step, change_context, gather_submit, get_visual_input, get_ideal_strategy, pause_conversation.

Parameters

question

stringRequired

The yes/no question, at most 8 KB (UTF-8). ${...} variables from the call’s global data are expanded when the gate is checked; @{...} functions are not.

threshold

numberRequired

Above 0 and at most 1. The gate passes when the decision model’s probability of “yes” is at or above this value.

onFail

string | FunctionResult | Record<string, unknown>Required

What the AI gets when this is the first gate that fails, at most 8 KB. A string is the response text. A FunctionResult contributes its response, actions, and postProcess. An object is used as written, in the data_map output shape (response, optional action). Say that the function didn’t run: the constructor throws when there’s no response. Actions run as written, without ${...} expansion. Realtime (speech-to-speech) agents don’t use tool_prompt, so put everything in tool_result for them.

opts

SemanticGateOptions

Optional settings.

opts.id

string

1 to 64 letters, digits, or underscores, unique within the function. Defaults to gate_1, gate_2, and so on, by position.

opts.trueMeans

string

What “yes” means, at most 2 KB. Sent as criteria.true.

opts.falseMeans

string

What “no” means, at most 2 KB. Sent as criteria.false.

opts.visualInput

boolean | number

How many of the caller’s newest video frames the decision model sees with this gate, as visual_input: true is 1, false or 0 is none, or a whole number up to 5. Every gate on a function sees as many frames as the gate that asks for the most. If the call has no video frame to show, the gate fails without being asked. Omitted by default.

Methods

toDict

Return the gate as the object sent in the function definition.

gateDefinitions

Check a function’s gates and return them as plain objects.

applyGateFields

Check and normalize the gates and gate fillers in a function definition.

SemanticGate constants

The limits and reserved function names enforced on gates.

Examples

import { AgentBase, FunctionResult, SemanticGate } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'account-agent', route: '/account' });
agent.setPromptText('You help callers manage their account.');
const explicitRequest = new SemanticGate(
  'Has the caller explicitly asked to cancel their account in `conversation`?',
  0.95,
  new FunctionResult({
    tool_result: 'cancel_account was not run.',
    tool_prompt: 'Ask the caller to confirm that they want to cancel.',
  }),
  {
    id: 'explicit_request',
    trueMeans: 'The caller says they want to cancel.',
    falseMeans: 'The caller asked about cancelling, or said something else.',
  },
);
agent.defineTool({
  name: 'cancel_account',
  description: "Cancel the caller's account",
  gates: [explicitRequest],
  gateFillers: { 'en-US': ['One moment.'] },
  handler: async () => new FunctionResult('The account is cancelled. Tell the caller.'),
});
await agent.serve();