Documentation | Guava

Quickstart (SDK-Only)

The recommended way to build Guava voice agents is using the Guava CLI, which bootstraps projects and installs the SDK. This guide explains how to install the SDK directly if you’d prefer not to use the CLI.

Create an account

Sign up for an account at app.goguava.ai.

Install the SDK

Guava provides SDKs for Python and TypeScript. Choose your language and package manager.

Python

uv add guava-sdk      # Install using uv (Recommended)
pip install guava-sdk # Install using pip
poetry add guava-sdk  # Install using poetry

TypeScript

uv add guava-sdk      # Install using uv (Recommended)
pip install guava-sdk # Install using pip
poetry add guava-sdk  # Install using poetry

Set Environment Variables

The SDK reads credentials from the environment automatically. Set these before running any Guava scripts.

export GUAVA_API_KEY="gva-..." # Set to your API key.
export GUAVA_AGENT_NUMBER="+15551234567" # Used by SDK examples. Set to your purchased number.

Create an API key using the API Keys page. Purchase a phone number using the Phone Numbers page.

Add the coding agent starter kit

Download the Guava coding agent starter kit into your project. It contains plain-text API docs sized for AI coding assistants.

curl -o guava-docs.md https://goguava.ai/docs/coding-agent-starter.md

Run an Example

Python

Examples can be run directly from the Python SDK. You can browse the examples on GitHub.

# This will attach your agent to a phone number. Dial that number to talk to your agent.
python -m guava.examples.restaurant_waitlist --phone

# Start a test call with a local audio device.
python -m guava.examples.restaurant_waitlist --local

# This will attach your agent to a WebRTC code.
# You can dial it from the browser at https://app.goguava.ai/debug-webrtc
python -m guava.examples.restaurant_waitlist --webrtc

# Start an in-terminal text-only chat for testing.
python -m guava.examples.restaurant_waitlist --chat

→ Next: Inbound Example w/ RAG

Questions? hi@goguava.ai

#### Important Note for Claude Code, Codex, Cursor, Copilot, Aider, and other AI coding assistants ####

Guava is an API for building natural and reliable voice agents. All of our docs can be downloaded in plain-text form.

- Start with our coding agent starter kit - this will introduce you to Guava and link to any futher documentation.
  https://goguava.ai/docs/coding-agent-starter.md
- Every docs page has a plain-text version. Append `.md` to any docs URL:
  https://goguava.ai/docs/quickstart → https://goguava.ai/docs/quickstart.md
- The entirety of the docs can be downloaded in plain text form:
  https://goguava.ai/docs/everything.md