RELAYCall

ai

View as MarkdownOpen in Claude

Start an AI agent session on the call. The AI agent handles the conversation using the provided prompt, tools, and configuration. Returns an AIAction that you can use to stop the AI session or wait for it to complete.

For building AI agents with the full framework (prompts, tools, skills, contexts), use AgentBase. The ai() method is for lower-level RELAY control where you configure the AI inline.

See also amazonBedrock() for using Amazon Bedrock as the LLM backend.

This method executes the SWML ai verb on the call. See the SWML AI reference for the full specification of all supported parameters and behaviors.

Parameters

controlId
string | undefined

Custom control ID. Auto-generated if not provided.

agent
string | undefined

Fabric agent resource ID. When set, the AI uses a pre-configured agent from SignalWire Fabric instead of inline configuration.

prompt
Record<string, unknown> | undefined

The main prompt configuration.

prompt.text
string

The system prompt text that defines the AI agent’s behavior.

prompt.temperature
number

LLM temperature for the main prompt.

prompt.top_p
number

LLM top_p sampling parameter.

postPrompt
Record<string, unknown> | undefined

Post-prompt configuration for summarization or analysis after the conversation ends.

postPrompt.text
string

The post-prompt text.

postPromptUrl
string | undefined

URL to receive the post-prompt result via webhook.

postPromptAuthUser
string | undefined

Username for basic auth on the post-prompt webhook.

postPromptAuthPassword
string | undefined

Password for basic auth on the post-prompt webhook.

globalData
Record<string, unknown> | undefined

Data accessible to the AI agent and SWAIG functions throughout the session.

pronounce
Record<string, unknown>[] | undefined

Pronunciation rules for words or phrases the TTS engine should handle specially.

hints
string[] | undefined

Speech recognition hints to improve accuracy for domain-specific terms.

languages
Record<string, unknown>[] | undefined

Language configurations for multilingual support.

SWAIG
Record<string, unknown> | undefined

SWAIG (SignalWire AI Gateway) configuration for tool/function definitions.

aiParams
Record<string, unknown> | undefined

Additional AI parameters such as barge_confidence, end_of_speech_timeout, attention_timeout, and other LLM tuning settings.

onCompleted
(event: RelayEvent) => void | Promise<void>

Callback invoked when the AI session ends.

Returns

Promise<AIAction> — An action handle with stop() and wait() methods.

Example

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9client.onCall(async (call) => {
10  await call.answer();
11
12  // Start an AI agent on the call
13  const action = await call.ai({
14    prompt: { text: 'You are a helpful customer support agent for Acme Corp.' },
15    hints: ['Acme', 'support', 'billing'],
16    aiParams: { barge_confidence: 0.02 },
17  });
18
19  // Wait for the AI session to end (caller hangs up or AI stops)
20  await action.wait();
21  console.log('AI session ended');
22});
23
24await client.run();