> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Abilities and actions

> The full catalog of actions an agent can take during a conversation.

An action is a discrete operation an agent performs during a conversation: play a message, transfer the call, query a knowledge base, run a workflow, and more. Actions never run on their own. They are grouped into a tool that the LLM decides to call, so the model controls *when* an ability fires while the configuration controls *what* it does.

## The tool model

A tool (`ToolCall`) exposes a single function to the LLM. When the model calls it, the agent runs the tool's ordered list of actions, then renders an output the model can read back.

| Field              | Type       | Default  | Description                                                      |
| ------------------ | ---------- | -------- | ---------------------------------------------------------------- |
| `name`             | string     | required | Function name the LLM invokes.                                   |
| `description`      | string     | required | When to call the tool. The model uses this to decide.            |
| `properties`       | object     | `{}`     | JSON-Schema-style argument definitions the LLM fills in.         |
| `required`         | string\[]  | `[]`     | Argument names that must be supplied.                            |
| `actions`          | `Action[]` | required | Ordered list of actions run when the tool is called.             |
| `actions_on_error` | `Action[]` | `[]`     | Actions run if one of the main actions raises an error.          |
| `output`           | string     | `null`   | Template rendered and returned to the LLM after the actions run. |

Actions execute in order. Each action whose `condition` passes runs; its result is merged into the tool's data so later actions and the `output` template can reference it.

<Note>
  Every action carries an optional `condition` expression. When set, the action runs only if the expression evaluates truthy against the current tool-call data. Leave it empty to always run the action.
</Note>

## Action catalog

Actions form a discriminated union keyed on `type`. The full set:

| `type`               | Title              | Purpose                                              |
| -------------------- | ------------------ | ---------------------------------------------------- |
| `play_message`       | Play Message       | Speak or send a message to the contact.              |
| `cold_transfer`      | Cold Transfer      | Hand the call to another number and drop off.        |
| `warm_transfer`      | Warm Transfer      | Brief a supervisor, then connect them to the caller. |
| `conference`         | Add to Conference  | Add the call to a conference bridge.                 |
| `dtmf`               | Send DTMF          | Send touch-tone digits or letters.                   |
| `hangup`             | Hangup             | End the call.                                        |
| `leave_room`         | Leave Room         | Remove the agent from the room.                      |
| `wait`               | Wait               | Pause for a number of seconds.                       |
| `update_endpointing` | Update Endpointing | Adjust turn-detection timing mid-call.               |
| `play_audio`         | Play Audio         | Play an audio file (loopable).                       |
| `stop_audio`         | Stop Audio         | Stop a currently playing audio file.                 |
| `workflow`           | Workflow           | Run a workflow by reference or inline.               |
| `knowledge_base`     | Knowledge Base     | Run a RAG query against a dataset.                   |

<Note>
  Transfers, conferencing, and DTMF have their own page. See [/agents/transfers](/agents/transfers) for the call-routing actions (`cold_transfer`, `warm_transfer`, `conference`, `dtmf`).
</Note>

### play\_message

| Field                 | Type   | Default  | Description                                                 |
| --------------------- | ------ | -------- | ----------------------------------------------------------- |
| `message`             | string | required | The message text. Supports templating.                      |
| `generate`            | bool   | `false`  | Generate a paraphrase instead of speaking the literal text. |
| `wait_for_playout`    | bool   | `true`   | Wait for the message to finish before the next action.      |
| `allow_interruptions` | bool   | `true`   | Allow the contact to interrupt the message.                 |
| `condition`           | string | `null`   | Run only if this expression is truthy.                      |

### workflow

Runs a [workflow](/workflows/overview) either by reference (`workflow_id` + `workflow_version`) or as an inline `definition`. The two sources are mutually exclusive.

| Field              | Type   | Default | Description                                                                                      |
| ------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------ |
| `workflow_id`      | string | `null`  | ID of a saved workflow. Requires `workflow_version`.                                             |
| `workflow_version` | int    | `null`  | Version of the saved workflow.                                                                   |
| `initial_step`     | string | `null`  | Step to start at. Required when using a reference; defaults to `trigger` for inline definitions. |
| `definition`       | object | `null`  | Inline workflow definition. Mutually exclusive with `workflow_id`/`workflow_version`.            |
| `reject_on_error`  | bool   | `false` | If true, abort the conversation when the workflow fails.                                         |
| `condition`        | string | `null`  | Run only if this expression is truthy.                                                           |

<Warning>
  You must supply either `workflow_id` + `workflow_version` or a non-empty inline `definition`, but not both. When using a reference, `initial_step` is required.
</Warning>

The workflow runs synchronously. The tool-call arguments and conversation data are passed as input, and the workflow's `output` (or its `context` if there is no output) becomes the action result.

### knowledge\_base

Runs a retrieval query against a [knowledge base](/knowledge-bases/using-with-agents) dataset and returns the top matches as `content` and `score` pairs.

| Field        | Type   | Default  | Description                                             |
| ------------ | ------ | -------- | ------------------------------------------------------- |
| `dataset_id` | string | required | The dataset to query.                                   |
| `query`      | string | required | Query text. Supports templating against tool-call data. |
| `top_n`      | int    | `5`      | Number of results to return.                            |
| `condition`  | string | `null`   | Run only if this expression is truthy.                  |

### wait

| Field       | Type   | Default | Description                            |
| ----------- | ------ | ------- | -------------------------------------- |
| `seconds`   | float  | `1.0`   | How long to pause.                     |
| `condition` | string | `null`  | Run only if this expression is truthy. |

### play\_audio / stop\_audio

| Field       | Type   | Default  | Description                                      |
| ----------- | ------ | -------- | ------------------------------------------------ |
| `audio_url` | string | required | URL to an MP3 or WAV file (`play_audio` only).   |
| `loop`      | bool   | `false`  | Loop the file until stopped (`play_audio` only). |
| `condition` | string | `null`   | Run only if this expression is truthy.           |

`stop_audio` takes only `condition` and stops the currently playing file.

### update\_endpointing

Adjusts turn-detection timing mid-call. Both delays are optional; leave one unset to keep its current value.

| Field                   | Type   | Default | Description                            |
| ----------------------- | ------ | ------- | -------------------------------------- |
| `min_endpointing_delay` | float  | `null`  | Minimum endpointing delay in seconds.  |
| `max_endpointing_delay` | float  | `null`  | Maximum endpointing delay in seconds.  |
| `condition`             | string | `null`  | Run only if this expression is truthy. |

### hangup / leave\_room

Both take only `condition`. `hangup` ends the call; `leave_room` removes the agent from the room.

## Which actions run on which channel

The action catalog is built for telephony. On the **async text and email engine** there is no audio playout or call control, so only three action types execute:

```text theme={null}
Async text / email engine
├── workflow         ✓ runs
├── knowledge_base   ✓ runs
├── play_message     ✓ runs (returns the rendered text as output)
└── everything else  ✗ skipped with a warning
```

| Action               | Voice / telephony | Async text / email                   |
| -------------------- | ----------------- | ------------------------------------ |
| `play_message`       | ✓                 | ✓ (rendered text returned, no audio) |
| `workflow`           | ✓                 | ✓                                    |
| `knowledge_base`     | ✓                 | ✓                                    |
| `cold_transfer`      | ✓                 | skipped                              |
| `warm_transfer`      | ✓                 | skipped                              |
| `conference`         | ✓                 | skipped                              |
| `dtmf`               | ✓                 | skipped                              |
| `hangup`             | ✓                 | skipped                              |
| `leave_room`         | ✓                 | skipped                              |
| `wait`               | ✓                 | skipped                              |
| `update_endpointing` | ✓                 | skipped                              |
| `play_audio`         | ✓                 | skipped                              |
| `stop_audio`         | ✓                 | skipped                              |

<Info>
  On async channels, `play_message` has no audio playout. The rendered message text is returned as the action output so the tool's `output` template can reference it. Any voice-only action is skipped and logged, not failed.
</Info>

## Related

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench" href="/agents/tools">
    How the LLM decides to call a tool and what arguments it passes.
  </Card>

  <Card title="Transfers and call routing" icon="phone-arrow-up-right" href="/agents/transfers">
    Cold transfer, warm transfer, conference, and DTMF in depth.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    Build the workflows a `workflow` action runs.
  </Card>

  <Card title="Knowledge bases with agents" icon="book" href="/knowledge-bases/using-with-agents">
    Connect datasets a `knowledge_base` action can query.
  </Card>
</CardGroup>