# Embedded Voice for AI Assistants

Add voice to an existing AI assistant product. Guava handles the call; your backend handles reasoning. One callback, your model in the loop.

### 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 embedded voice for ai assistants 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`.

terminal

```
# 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.

example.py

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

### 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.

example.py

```
class EmbeddedAssistantBot(guava.CallController):
    def __init__(self, assistant_id: str, user_id: str):
        super().__init__()
        self.assistant_id = assistant_id
        self.user_id = user_id
        self.thread_id = None
        self.set_persona(
            organization_name="Acme AI",
            agent_name="Atlas",
        )
        self.set_task(
            objective="Carry on an open-ended conversation, deferring reasoning to the customer's AI backend.",
            checklist=[\
                "Greet the caller and ask how you can help today.",\
                guava.OpenEnded(\
                    description="Take any user utterance and call route_to_backend() to get the assistant's reply.",\
                    handler=self.route_to_backend,\
                ),\
            ],
        )

def route_to_backend(self, utterance: str) -> str:
        """Forward the user's words to the customer's AI backend and return its reply."""
        response = requests.post(
            "https://api.acme-ai.example/v1/threads/messages",
            json={
                "assistant_id": self.assistant_id,
                "user_id": self.user_id,
                "thread_id": self.thread_id,
                "message": utterance,
            },
            headers={"Authorization": f"Bearer {os.environ['ACME_API_KEY']}"},
            timeout=8,
        ).json()
        self.thread_id = response.get("thread_id")
        return response["reply"]

guava.listen(
    controller=EmbeddedAssistantBot,
    controller_args={"assistant_id": "asst_general", "user_id": "u_test_001"},
    agent_number=os.environ["GUAVA_AGENT_NUMBER"],
    api_key=os.environ["GUAVA_API_KEY"],
)
```

Platform performance

- <1s Response time
- 99.99% Uptime SLA
- 13+ Industries served

## Full example

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

example.py

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

class EmbeddedAssistantBot(guava.CallController):
    def __init__(self, assistant_id: str, user_id: str):
        super().__init__()
        self.assistant_id = assistant_id
        self.user_id = user_id
        self.thread_id = None
        self.set_persona(
            organization_name="Acme AI",
            agent_name="Atlas",
        )
        self.set_task(
            objective="Carry on an open-ended conversation, deferring reasoning to the customer's AI backend.",
            checklist=[\
                "Greet the caller and ask how you can help today.",\
                guava.OpenEnded(\
                    description="Take any user utterance and call route_to_backend() to get the assistant's reply.",\
                    handler=self.route_to_backend,\
                ),\
            ],
        )

## Run it

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

terminal

```
python example.py
```