> 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/typescript/relay/actions

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

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

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

[swml-ai-reference]: /docs/swml/reference/calling/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 [`amazonBedrock()`][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**

**`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`][aiaction]`>` -- An action handle with `stop()` and `wait()` methods.

## **Example**

```typescript {13}
import { RelayClient } from '@signalwire/sdk';

const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_API_TOKEN!,
  contexts: ['default']
});

client.onCall(async (call) => {
  await call.answer();

  // Start an AI agent on the call
  const action = await call.ai({
    prompt: { text: 'You are a helpful customer support agent for Acme Corp.' },
    hints: ['Acme', 'support', 'billing'],
    aiParams: { barge_confidence: 0.02 },
  });

  // Wait for the AI session to end (caller hangs up or AI stops)
  await action.wait();
  console.log('AI session ended');
});

await client.run();
```

> Start an AI agent session on a call.