ai

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 amazon_bedrock() 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

control_id

Optional[str]

Custom control ID. Auto-generated if not provided.

agent

Optional[str]

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

prompt

Optional[dict]

The main prompt configuration.

prompt.text

str

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

prompt.temperature

float

LLM temperature for the main prompt.

prompt.top_p

float

LLM top_p sampling parameter.

post_prompt

Optional[dict]

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

post_prompt.text

str

The post-prompt text.

post_prompt_url

Optional[str]

URL to receive the post-prompt result via webhook.

post_prompt_auth_user

Optional[str]

Username for basic auth on the post-prompt webhook.

post_prompt_auth_password

Optional[str]

Password for basic auth on the post-prompt webhook.

global_data

Optional[dict]

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

pronounce

Optional[list[dict]]

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

hints

Optional[list[str]]

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

languages

Optional[list[dict]]

Language configurations for multilingual support.

SWAIG

Optional[dict]

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

ai_params

Optional[dict]

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

on_completed

Optional[Callable[[RelayEvent], Any]]

Callback invoked when the AI session ends.

Returns

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

Example

1 from signalwire.relay import RelayClient
2 
3 client = RelayClient(
4     project="your-project-id",
5     token="your-api-token",
6     host="your-space.signalwire.com",
7     contexts=["default"],
8 )
9 
10 @client.on_call
11 async def handle_call(call):
12     await call.answer()
13 
14     # Start an AI agent on the call
15     action = await call.ai(
16         prompt={"text": "You are a helpful customer support agent for Acme Corp."},
17         hints=["Acme", "support", "billing"],
18         ai_params={"barge_confidence": 0.02},
19     )
20 
21     # Wait for the AI session to end (caller hangs up or AI stops)
22     await action.wait()
23     print("AI session ended")
24 
25 client.run()

1	from signalwire.relay import RelayClient
2
3	client = RelayClient(
4	project="your-project-id",
5	token="your-api-token",
6	host="your-space.signalwire.com",
7	contexts=["default"],
8	)
9
10	@client.on_call
11	async def handle_call(call):
12	await call.answer()
13
14	# Start an AI agent on the call
15	action = await call.ai(
16	prompt={"text": "You are a helpful customer support agent for Acme Corp."},
17	hints=["Acme", "support", "billing"],
18	ai_params={"barge_confidence": 0.02},
19	)
20
21	# Wait for the AI session to end (caller hangs up or AI stops)
22	await action.wait()
23	print("AI session ended")
24
25	client.run()