# Custom Voice Persona for AI Agents

Give your AI product a distinctive voice. Pick a TTS voice, set persona traits (tone, pace, formality), and tune turn-taking — your brand, audible.

### Why this matters

Embed Guava in your AI stack. Your prompts, your data, our voice infrastructure. Sub-1s latency. WebRTC + SIP. Compliance you can hand to your enterprise buyer. This example shows you how to automate custom voice persona for ai agents calls end-to-end with Guava's SDK — no telephony plumbing, no prompt engineering, just Python.

## Installation

Install from Guava's private PyPI index. A public package is coming soon — the install command will simplify to `pip install guava`.

```
# Step 1: Install Guava
pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com

# Public PyPI package coming soon — the install command will simplify to:
# pip install guava

# Step 2: Set your credentials
export GUAVA_API_KEY="..."
export GUAVA_AGENT_NUMBER="..."
```

## How it's built

Every Guava agent is a Python class. Walk through the key sections below, then grab the complete file at the end.

### Imports

Import the Guava SDK and any helpers you need. `guava.CallController` is the base class for every voice agent.

```
# Install: pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com
import guava
import os
```

### Agent setup

`set_persona()` defines how the agent presents itself. `set_task()` gives it its mission in plain English. The checklist drives the conversation — Guava works through it top-to-bottom, collecting `Field` values and speaking `Say` items as it goes.

```
class BrandedPersonaBot(guava.CallController):
    def __init__(self):
        super().__init__()
        self.set_persona(
            organization_name="Halcyon AI",
            agent_name="Nova",
            voice="halcyon-signature-en-us",   # custom voice cloned for the brand
            traits={
                "tone": "calm, confident",
                "pace": "measured",
                "formality": "professional but warm",
                "humor": "dry, minimal",
            },
            turn_taking={
                "interruption_sensitivity": "high",
                "pause_threshold_ms": 480,
            },
        )
        self.set_task(
            objective="Have a natural, brand-consistent conversation with the caller.",
            checklist=[
                "Greet the caller as Nova from Halcyon AI.",
                guava.OpenEnded(
                    description="Open conversation, defer to the Halcyon backend for any factual or product-specific replies.",
                    handler=lambda utterance: guava.echo(utterance),
                ),
                "Close the call by inviting the caller to continue in the Halcyon app.",
            ],
        )

guava.listen(
    controller=BrandedPersonaBot,
    agent_number=os.environ["GUAVA_AGENT_NUMBER"],
    api_key=os.environ["GUAVA_API_KEY"],
)
```

## Full example

The complete file — copy it, save it as `example.py`, and run it.

```
# Install: pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com
import guava
import os

class BrandedPersonaBot(guava.CallController):
    def __init__(self):
        super().__init__()
        self.set_persona(
            organization_name="Halcyon AI",
            agent_name="Nova",
            voice="halcyon-signature-en-us",   # custom voice cloned for the brand
            traits={
                "tone": "calm, confident",
                "pace": "measured",
                "formality": "professional but warm",
                "humor": "dry, minimal",
            },
            turn_taking={
                "interruption_sensitivity": "high",
                "pause_threshold_ms": 480,
            },
        )
        self.set_task(
            objective="Have a natural, brand-consistent conversation with the caller.",
            checklist=[
                "Greet the caller as Nova from Halcyon AI.",
                guava.OpenEnded(
                    description="Open conversation, defer to the Halcyon backend for any factual or product-specific replies.",
                    handler=lambda utterance: guava.echo(utterance),
                ),
                "Close the call by inviting the caller to continue in the Halcyon app.",
            ],
        )

guava.listen(
    controller=BrandedPersonaBot,
    agent_number=os.environ["GUAVA_AGENT_NUMBER"],
    api_key=os.environ["GUAVA_API_KEY"],
)
```

## Run it

Start the agent. It will connect to Guava's infrastructure and begin accepting calls on your assigned number.

```
python example.py
```