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

1from signalwire.relay import RelayClient
2
3client = 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
11async 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
25client.run()