docs/Quickstart

Quickstart

Create your Guava account and deploy your first AI phone agent.

1. Create your account at app.goguava.ai

2. Continue from your Guava dashboard or below:

Quick start
Ship your first voice agent
Three steps from zero to a live AI phone agent.
1
Install
One command gets you the guava CLI and Python SDK installed globally.
curl -fsSL …guava-cli… | sh
Installs to /usr/local/bin/guava
2
Create
Scaffold a new agent project with starter code, dependencies, and a config file.
guava create my-agent
Get your key from API Keys and a number from Phone Numbers.
3
Deploy
Push your agent to Guava's cloud. It answers calls and streams conversations here.
guava deploy up ./my-agent
Track status in Deployments. Every call appears in Conversations.

Getting Started

Installation / Setup

Guava provides SDKs for Python and TypeScript.

Prerequisites: Python >= 3.10 and a Guava API Key and Phone Number.

Install the Python SDK using your preferred method.

Method 1: pip

terminal
pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com

Method 2: uv

terminal
uv add gridspace-guava --index guava=https://guava-pypi.gridspace.com

Method 3: poetry

terminal
poetry source add --priority=explicit guava https://guava-pypi.gridspace.com
poetry add --source guava gridspace-guava

Set your environment variables.

.env
export GUAVA_API_KEY="sk-..."
export GUAVA_AGENT_NUMBER="+15551234567"

You're ready.

Running an Example

Examples can be found in the guava.examples submodule (Python) or in the examples/ directory of the @guava-ai/guava-sdk package (TypeScript). Running one starts a voice conversation through a phone or WebRTC session.

Outbound Phone Call

terminal
python -m guava.examples.scheduling_outbound +1... "John Doe"  # Use your own phone number and name to receive a call.

Inbound Phone Call

terminal
python -m guava.examples.thai_palace
# Now dial your agent's number while the script is running.

Inbound WebRTC

terminal
python -m guava.tools.create_webrtc_agent  # Create a WebRTC agent code.
python -m guava.examples.inbound_webrtc grtc-...  # Start the listener
# Go to https://guava-dev.gridspace.com/debug-webrtc and call the agent.

What just happened? Guava handled speech recognition, natural language understanding, turn-taking, and text-to-speech. You wrote the business logic.

Questions? hi@goguava.ai · Request a technical walkthrough at app.goguava.ai