***

title: ai
slug: /reference/typescript/relay/call/ai
description: Start an AI agent session on a call.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[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/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.
</Tip>

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

<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.
</Info>

## **Parameters**

<ParamField path="controlId" type="string | undefined" toc={true}>
  Custom control ID. Auto-generated if not provided.
</ParamField>

<ParamField path="agent" type="string | undefined" toc={true}>
  Fabric agent resource ID. When set, the AI uses a pre-configured agent
  from SignalWire Fabric instead of inline configuration.
</ParamField>

<ParamField path="prompt" type="Record<string, unknown> | undefined" toc={true}>
  The main prompt configuration.
</ParamField>

<Indent>
  <ParamField path="prompt.text" type="string" toc={true}>
    The system prompt text that defines the AI agent's behavior.
  </ParamField>

  <ParamField path="prompt.temperature" type="number" toc={true}>
    LLM temperature for the main prompt.
  </ParamField>

  <ParamField path="prompt.top_p" type="number" toc={true}>
    LLM top\_p sampling parameter.
  </ParamField>
</Indent>

<ParamField path="postPrompt" type="Record<string, unknown> | undefined" toc={true}>
  Post-prompt configuration for summarization or analysis after the
  conversation ends.
</ParamField>

<Indent>
  <ParamField path="postPrompt.text" type="string" toc={true}>
    The post-prompt text.
  </ParamField>
</Indent>

<ParamField path="postPromptUrl" type="string | undefined" toc={true}>
  URL to receive the post-prompt result via webhook.
</ParamField>

<ParamField path="postPromptAuthUser" type="string | undefined" toc={true}>
  Username for basic auth on the post-prompt webhook.
</ParamField>

<ParamField path="postPromptAuthPassword" type="string | undefined" toc={true}>
  Password for basic auth on the post-prompt webhook.
</ParamField>

<ParamField path="globalData" type="Record<string, unknown> | undefined" toc={true}>
  Data accessible to the AI agent and SWAIG functions throughout the session.
</ParamField>

<ParamField path="pronounce" type={"Record<string, unknown>[] | undefined"} toc={true}>
  Pronunciation rules for words or phrases the TTS engine should handle
  specially.
</ParamField>

<ParamField path="hints" type="string[] | undefined" toc={true}>
  Speech recognition hints to improve accuracy for domain-specific terms.
</ParamField>

<ParamField path="languages" type={"Record<string, unknown>[] | undefined"} toc={true}>
  Language configurations for multilingual support.
</ParamField>

<ParamField path="SWAIG" type="Record<string, unknown> | undefined" toc={true}>
  SWAIG (SignalWire AI Gateway) configuration for tool/function definitions.
</ParamField>

<ParamField path="aiParams" type="Record<string, unknown> | undefined" toc={true}>
  Additional AI parameters such as `barge_confidence`, `end_of_speech_timeout`,
  `attention_timeout`, and other LLM tuning settings.
</ParamField>

<ParamField path="onCompleted" type="(event: RelayEvent) => void | Promise<void>" toc={true}>
  Callback invoked when the AI session ends.
</ParamField>

## **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_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();
```