> This page is for Server SDKs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# ai

> Start an AI agent session on a call.

[aiaction]: /docs/server-sdks/reference/python/relay/actions

[agentbase]: /docs/server-sdks/reference/python/agents/agent-base

[amazon-bedrock]: /docs/server-sdks/reference/python/relay/call/amazon-bedrock

[ai]: /docs/swml/reference/ai

[swml-ai-reference]: /docs/swml/reference/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`][aiaction] that you can use to stop
the AI session or wait for it to complete.

> **Tip**
>
> For building AI agents with the full framework (prompts, tools, skills, contexts),
> use [`AgentBase`][agentbase]. The `ai()` method
> is for lower-level Relay control where you configure the AI inline.

> **Info**
>
> See also [`amazon_bedrock()`][amazon-bedrock] for using Amazon Bedrock as the LLM backend.

> **Info**
>
> This method executes the SWML [`ai`][ai] verb on the call. See the
> [SWML AI reference][swml-ai-reference] for the full specification of all supported
> parameters and behaviors.

## **Parameters**

**`control_id`** `str | None` — default: None

Custom control ID. Auto-generated if not provided.

---

**`agent`** `str | None` — default: None

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

---

**`prompt`** `dict | None` — default: 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 | None` — default: None

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

---

**`post_prompt.text`** `str`

The post-prompt text.

---

**`post_prompt_url`** `str | None` — default: None

URL to receive the post-prompt result via webhook.

---

**`post_prompt_auth_user`** `str | None` — default: None

Username for basic auth on the post-prompt webhook.

---

**`post_prompt_auth_password`** `str | None` — default: None

Password for basic auth on the post-prompt webhook.

---

**`global_data`** `dict | None` — default: None

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

---

**`pronounce`** `list[dict] | None` — default: None

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

---

**`hints`** `list[str] | None` — default: None

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

---

**`languages`** `list[dict] | None` — default: None

Language configurations for multilingual support.

---

**`SWAIG`** `dict | None` — default: None

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

---

**`ai_params`** `dict | None` — default: None

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

---

**`on_completed`** `Callable[[RelayEvent], Any] | None` — default: None

Callback invoked when the AI session ends.

---

## **Returns**

[`AIAction`][aiaction] -- An action handle with `stop()` and `wait()` methods.

## **Example**

```python {14}
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()
```