> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Tool classes

> Use Conversation, Voice, and utility classes to manage state and configure TTS providers in functions.

**This page requires Python familiarity.** If you are a non-technical operator, work with your developer to configure these classes.

Use these classes in your [functions](/agent-studio/tools/overview) to manage conversation state and voice configuration.

## Core class

### `Conversation`

The primary class for managing conversation state at runtime. Every function receives a `Conversation` instance as its first argument.

```python
def get_conversation_id(conv: Conversation):
    return conv.id
```

For full attributes and methods, see the [`conv` object](/agent-studio/tools/classes-and-objects/object) page.

## Voice classes

Use voice classes to configure TTS providers programmatically – for example, in a [start function](/agent-studio/tools/start-tool) or when using [multi-voice](/agent-studio/voice/voice-design/multi-voice).

### `VoiceWeighting`

Assign specific weightings to voices for [multi-voice](/agent-studio/voice/voice-design/multi-voice) setups, adjusting their prominence in a given context.

```python
VoiceWeighting(
      voice=ElevenLabsVoice(
        provider_voice_id="LcfcDJNUP1GQjkzn1xUU",
        similarity_boost=0.2,
        stability=0.4
      ),
      weight=0.25
    )
```

### TTS provider classes

#### ElevenLabs

Configures voice settings for [ElevenLabs](https://docs.elevenlabs.io/api-reference/voices) TTS, with control over stability and similarity.

```python
elevenlabs_voice = ElevenLabsVoice(
    provider_voice_id="a1b2C3d4E5f6G7h8I9j0",
    stability=0.5,
    similarity_boost=0.7
)
```

| Parameter           | Description                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `provider_voice_id` | The [ElevenLabs voice ID](https://help.elevenlabs.io/hc/en-us/articles/14599760033937-How-do-I-find-my-voices-ID-of-my-voices-via-the-website-and-through-the-API) |
| `stability`         | Consistency of tone and delivery (0.0–1.0)                                                                                                                         |
| `similarity_boost`  | How closely the voice matches the original (0.0–1.0)                                                                                                               |

#### Cartesia

Configures voice settings for [Cartesia](https://docs.cartesia.ai/api-reference/tts/tts) TTS. Uses `Emotion` objects for expressive control.

```python
from polyai.voice import CartesiaVoice, Emotion, EmotionKind, EmotionIntensity

cartesia_voice = CartesiaVoice(
    provider_voice_id="a1b2c3d4",
    speed=0.0,
    emotions=[Emotion(EmotionKind.POSITIVITY, EmotionIntensity.HIGH)]
)
```

| Parameter           | Description                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| `provider_voice_id` | The Cartesia voice to use                                                                        |
| `speed`             | Speech rate: -1.0 (slowest) to 1.0 (fastest)                                                     |
| `emotions`          | List of `Emotion` objects (see [voice reference](/agent-studio/tools/classes-and-objects/voice)) |
| `model_id`          | `"sonic"` or `"sonic-preview"`                                                                   |

#### PlayHT

Configures voice settings for [PlayHT](https://docs.play.ht/reference/api-getting-started) TTS.

```python
playht_voice = PlayHTVoice(
    provider_voice_id="en_us_male_1",
    style="conversational"
)
```

| Parameter           | Description             |
| ------------------- | ----------------------- |
| `provider_voice_id` | The PlayHT voice to use |
| `style`             | Speaking style or tone  |

#### Rime

Configures voice settings for [Rime](https://docs.rime.ai/api-reference/voices) TTS.

```python
rime_voice = RimeVoice(
    provider_voice_id="voice_id",
    speech_alpha=1.0,
    model_id="mistv2"
)
```

| Parameter           | Description                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `provider_voice_id` | Your configured Rime voice identifier. Contact your PolyAI rep or [Rime](https://docs.rime.ai) for the correct value. |
| `speech_alpha`      | Speech rate multiplier: \<1.0 faster, >1.0 slower                                                                     |
| `model_id`          | `"mistv2"` or `"mist"`                                                                                                |

#### Minimax

Configures voice settings for Minimax TTS.

```python
minimax_voice = MinimaxVoice(
    model_id="speech-02-hd",
    voice_id="voice_id",
    speed=1.0,
    emotion="happy"
)
```

| Parameter  | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `model_id` | `"speech-02-hd"`, `"speech-02-turbo"`, `"speech-01-hd"`, or `"speech-01-turbo"`       |
| `voice_id` | The Minimax voice ID                                                                  |
| `speed`    | Speech rate (0.5–2.0)                                                                 |
| `emotion`  | `"happy"`, `"sad"`, `"angry"`, `"fearful"`, `"disgusted"`, `"surprised"`, `"neutral"` |

#### Hume

Configures voice settings for [Hume](https://www.hume.ai/) TTS.

```python
hume_voice = HumeVoice(
    provider_voice_id="voice_uuid_or_name",
    version="2"
)
```

| Parameter           | Description                                |
| ------------------- | ------------------------------------------ |
| `provider_voice_id` | Voice UUID or name                         |
| `voice_description` | Optional description for voice personality |
| `version`           | `"1"` (octave-1) or `"2"` (octave-2)       |
| `instant_mode`      | Ultra-low latency mode (boolean)           |

#### Custom

Define voice configurations for a custom TTS provider.

```python
voice_config = CustomVoice(
    provider="MY_PROVIDER",
    provider_voice_id="voice_id"
)
```

| Parameter           | Description                  |
| ------------------- | ---------------------------- |
| `provider`          | Custom TTS provider name     |
| `provider_voice_id` | Voice ID within the provider |

For full voice configuration examples including ElevenLabs model IDs, Cartesia emotions, and cache behavior, see the [Voice class reference](/agent-studio/tools/classes-and-objects/voice).