Deploying to Heroku

Guava agents can be deployed to Heroku. They should be run as a background worker, rather than as part of a web server.

1. Add guava-sdk to your Heroku app.
2. Create an API Key on the Guava Dashboard.
3. Use the Heroku dashboard or CLI to add the key to your environment.
4. Add the following to your Procfile: guava-worker: python agent.py (or whichever file is your agent’s entrypoint).
5. Push your code and scale the new worker type.

What follows is a detailed guide.

Add guava-sdk as a dependency

Add the Python package guava-sdk as a dependency using the package manager of your choice.

echo "guava-sdk==0.24.0" >> requirements.txt # If using pip + requirements.txt
uv add guava-sdk # If using uv
poetry add guava-sdk # If using poetry

Add a Guava API Key to the Heroku Environment

Open the API Keys page in the Guava dashboard and click Create API Key. The key should be of the form gva-....

Next, add this key to your Heroku environment, either using the CLI or the Heroku dashboard.

heroku config:set GUAVA_API_KEY="gva-..."

Define your agent

Define your agent. In this example we'll create it in a file agent.py, but you can use anything. Note the entrypoint agent.listen_phone(...) at the bottom - this method attaches your agent to the phone number and does not exit.

import os
import guava

from typing_extensions import override
from guava import logging_utils

agent = guava.Agent(
    purpose="You are a helpful voice agent.",
    name="Hannah",
)

@agent.on_call_start()
def on_call_start(call: guava.Call):
    # Set your first task here using call.set_task(...)
    pass

if __name__ == "__main__":
    logging_utils.configure_logging()
    agent.listen_phone("+1...") # Replace with your agent's phone number.

Add the worker to your Procfile

Add the following section to your Procfile. This will create a new dyno type called "guava-worker".

# Run the Guava agent in a background process.
guava-worker: python agent.py

Push to Heroku

Commit and push your code to Heroku to trigger a deploy.

git add .
git commit -m "Added Guava agent."
git push heroku main # or master, depending on your setup

Scale the Guava worker up

Scale the newly added worker dyno.

heroku ps:scale guava-worker=1

Call your agent

Now, you should be able to call your agent. You can use heroku logs to check logs for your dynos.