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
str | NoneDefaults to None

Custom control ID. Auto-generated if not provided.

agent
str | NoneDefaults to None

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

prompt
dict | NoneDefaults to None

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
dict | NoneDefaults to None

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

post_prompt.text
str

The post-prompt text.

post_prompt_url
str | NoneDefaults to None

URL to receive the post-prompt result via webhook.

post_prompt_auth_user
str | NoneDefaults to None

Username for basic auth on the post-prompt webhook.

post_prompt_auth_password
str | NoneDefaults to None

Password for basic auth on the post-prompt webhook.

global_data
dict | NoneDefaults to None

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

pronounce
list[dict] | NoneDefaults to None

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

hints
list[str] | NoneDefaults to None

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

languages
list[dict] | NoneDefaults to None

Language configurations for multilingual support.

SWAIG
dict | NoneDefaults to None

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

ai_params
dict | NoneDefaults to None

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

on_completed
Callable[[RelayEvent], Any] | NoneDefaults to None

Callback invoked when the AI session ends.

Returns

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

Example

from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    # Start an AI agent on the call
    action = await call.ai(
        prompt={"text": "You are a helpful customer support agent for Acme Corp."},
        hints=["Acme", "support", "billing"],
        ai_params={"barge_confidence": 0.02},
    )
    # Wait for the AI session to end (caller hangs up or AI stops)
    await action.wait()
    print("AI session ended")
client.run()