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

Install the SDK

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

Python
TypeScript

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

npm install @guava-ai/guava-sdk # Install using npm
yarn add @guava-ai/guava-sdk    # Install using yarn
pnpm add @guava-ai/guava-sdk    # Install using pnpm

Set Environment Variables

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

.env

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
TypeScript

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

Examples can be run directly from the TypeScript 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.
npx @guava-ai/guava-sdk restaurant-waitlist phone

# Start a test call with a local audio device.
npx @guava-ai/guava-sdk 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
npx @guava-ai/guava-sdk restaurant-waitlist webrtc

# Start an in-terminal text-only chat for testing.
npx @guava-ai/guava-sdk restaurant-waitlist chat

Getting started

Agent SDK

CLI reference

WebRTC

SIP calling

Phone numbers

Deployments

Compliance

Release notes

Create an account

Install the SDK

Set Environment Variables

Add the coding agent starter kit

Run an Example

​Create an account

​Install the SDK

​Set Environment Variables

​Add the coding agent starter kit

​Run an Example

Create an account

Install the SDK

Set Environment Variables

Add the coding agent starter kit

Run an Example