Add a Guava Voice Agent to Your Base44 App

This guide shows you how to add a Guava voice agent to a web app built with Base44. By the end, your Base44 app will have a floating widget that visitors can click to start a spoken conversation with your AI agent. No phone number is required.

You'll need two tools:
Base44 for building your web app
an AI coding platform with terminal access (such as Claude Code or Cursor) for setting up and managing your Guava agent. (The AI coding platform will handle all command-line steps that would otherwise require you to use the terminal.)

Quick Start

You'll need two items ready in order to follow this Quick Start:

• a deployed Guava agent
• a WebRTC code (starts with grtc-)

If you do not have both of these yet, follow the Full Guide below.

There are two ways to add the widget to your Base44 app. Choose the one that suits your preference:

• Script tag approach — The simplest option: no code changes, works in every Base44 project.
• React component approach — The more configurable option: better if you want to show the widget only on certain pages, or add special functionality. However, it requires Base44 to create a new component and wire it into your app, which adds a small amount of complexity.

Script tag approach

Paste this prompt into Base44's AI chat. Replace grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:

In index.html, add this script tag just before the closing </body> tag:

<script src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js" data-webrtc-code="grtc-YOUR_CODE_HERE"></script>

After Base44 makes the change, the preview will rebuild and a green voice orb will appear in the bottom-right corner of your app. Click it to start a call.

React component approach

Paste this prompt into Base44's AI chat. Replace grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:

Create a new component called GuavaVoiceAgent. It should use a useEffect hook to create a script element, set its src to "https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js", set a data-webrtc-code attribute to "grtc-YOUR_CODE_HERE", append it to the document body, and remove it on cleanup. Then render this component in App.tsx (or the layout component).

Full Guide

What is Guava?

Guava is a software development kit (SDK) for creating AI voice agents. In terms of this guide, Guava is a set of tools and resources that is usable via your preferred AI coding platform, that enables you to add an AI voice agent to your app.

What is the voice widget?

The voice widget is a small floating button (called the "orb") that appears on your web app. When a visitor clicks it, their browser opens a live voice conversation with your Guava agent. No phone number or phone call is needed; the conversation happens over Web Real-Time Communication (WebRTC), a technology that enables voice conversations within web apps and pages.

The orb is the default styling of the widget. You can restyle the widget to match your app's design, but that's beyond the scope of this guide.

Step 1 — Create a Guava account

Go to app.goguava.ai. Click Get Started in the top right, and create your account.

Step 2 — Create an API key

An API key lets Guava (via the Guava CLI, which you'll install in the next step) connect to your account.

To create an API key:

1. In your Guava account, go to the API Keys page.
   
2. Click + Create API Key at the top right.
   
3. Name your key something related to your app or voice widget.

Your key will always be available on the API Keys page, so you can copy-paste it whenever you need. Saving a backup in a password manager is good practice, but not required.

Step 3 — Install the Guava CLI

The Guava CLI (Command Line Interface) is the tool that connects your agent code to Guava's platform. Your AI coding platform can operate it for you. You won't need to type terminal commands. (But you could if you want to.)

Paste this prompt into your AI coding platform:

Install the Guava CLI on my machine.

Next, connect the CLI to your Guava account. This is a one-time step. Even if you are already signed in to Guava in your browser, the CLI needs its own login. Paste this prompt into your AI coding platform:

Log in to my Guava account using the Guava CLI.

A browser tab will open. Sign in with the account you created in Step 1. Once you sign in, the CLI stores your credentials so you won't have to repeat this step.

Step 4 — Get your agent starter file

Both options below produce a project folder on your computer with a Python file (__main__.py or main.py) that defines your agent's behavior and goals. You don't need to know Python: once you have the project folder, you can use your preferred AI coding platform to make changes in plain language.

Choose the option that best fits your situation:

• Start from scratch — This creates a blank starter agent that can hold a conversation, but has not yet been given a specific task, role, or use case. This is a good option if you either prefer to create your agent from scratch, or you want to create a voice agent that's significantly different from all preexisting examples.

• Start from an example — This provides you with a ready-made agent that already does something similar to what you want. Best if you'd rather modify an existing agent than build one from scratch. This option requires accessing the Guava examples library public repository on GitHub, but the guide will walk you through those steps.

Start from scratch

Paste the prompt below into your AI coding platform. It will create a project folder called my-agent with starter code that defines a basic voice agent. This starter agent can hold a spoken conversation, but it hasn't been given a specific task, role, or use case. You'll customize that in Step 7.

Create a new Guava agent project called my-agent.

You now have an agent project folder called my-agent. Feel free to rename it to something more personalized, for example: first-webapp-concierge. You'll develop and customize your agent soon. For now, proceed to Step 5.

Start from an example

Guava maintains a library of ready-made example agents organized by industry (healthcare, retail, insurance, and more). You can browse the library, download an agent that's close to what you want, and customize it from there.

The examples library is hosted on GitHub, a website where code projects are stored and shared. You don't need a GitHub account, because the Guava example agents library is shared publicly. You'll visit the Guava example library page, browse the available agents, and download the one you want as a ZIP file.

1. Browse the examples. Go to github.com/goguava-ai/guava-starter. Click the examples folder to see the list of industries. Click into any industry folder to see the available agents (for example, examples → healthcare → appointment_scheduling). Identify the example agent you'd like to use.

2. Download the library. Once you've found an agent you like, go back to the main page. Click the green Code button near the top right, then click Download ZIP. This downloads the entire examples library as a single ZIP file. Find the downloaded file (usually in your Downloads folder) and double-click it to unzip.

3. Create your agent project. Copy the agent folder you chose (for example, examples/healthcare/appointment_scheduling/) to a location where you keep your projects. Feel free to rename it to something more personalized, for example: first-webapp-concierge. This copy is your working agent project, the one you'll customize, test, and deploy through the rest of this guide.

4. Connect your AI coding platform. Open your agent project folder in your AI coding platform. This will be how you develop and customize your agent soon. For now, proceed to Step 5.

Step 5 — Create your WebRTC code

A WebRTC code connects the voice widget displayed on your web app to your agent running on Guava's servers. You'll use this code in two places: your agent's code (so it knows to listen for widget connections) and your Base44 app (so the widget knows which agent to connect to).

In your Guava account dashboard, go to the WebRTC Codes page and click Create WebRTC Code. Your new code will appear. Copy it and save it somewhere. Unlike the API key from Step 2, this code may not be retrievable later, so make sure you save it now. You'll need it in the next two steps.

Advanced: You can also create a WebRTC code using the Guava CLI. See the WebRTC Widgets docs for details.

Step 6 — Connect your WebRTC code to your agent

Your agent needs to know which WebRTC code to use so that visitors who click the widget on your Base44 app connect to the right agent. You'll use the same code again in Step 9 when you add the widget to your Base44 app.

Open your agent folder in your preferred AI coding platform and paste this prompt, replacing grtc-YOUR_CODE_HERE with the code you created in Step 5:

Update my agent to use the WebRTC code grtc-YOUR_CODE_HERE for voice widget connections.

Step 7 — Customize and test your agent

Now it's time to design your AI voice agent. Repeat steps 7A and 7B until you're happy with the agent you've created.

Step 7A — Customize your agent

Your agent's behavior and goals are defined in the Python file in your project folder. You can change any of this by describing what you want in plain language to your AI coding platform. Refer your AI coding platform to the Agent docs for the full list of things you can configure in your agent: persona, tasks, conversation flow, and more.

Step 7B — Test your changes

Before deploying your agent, test it on your own computer to make sure it works the way you want. Paste this prompt into your AI coding platform:

Run my Guava agent locally so I can test it.

Your AI coding platform will start the agent and provide a link that opens a voice conversation in your browser. Try out the conversation flow, check that it asks the right questions and responds the way you intended. If something isn't right, describe the changes you want to your AI coding platform, then test again. Repeat until you have the AI voice agent you want.

Step 8 — Deploy your agent

Deploying sends a copy of your agent to Guava's servers so it can run around the clock and handle real visitors on your website. Your local files stay on your computer; deploying does not remove them.

Paste this prompt into your AI coding platform:

Deploy my Guava agent.

Step 9 — Add the widget to your Base44 app

At the end of this step, your voice agent will be live on your Base44 app.

(Note: This is the point where the Quick Start begins. If you're resuming work from this step, you can keep reading here, or switch to the Quick Start.)

There are two ways to add the widget to your Base44 app. Choose the one that suits your preference:

• Script tag approach — The simplest option: no code changes, works in every Base44 project.

• React component approach — The more configurable option: better if you want to show the widget only on certain pages, or add special functionality. However, it requires Base44 to create a new component and wire it into your app, which adds a small amount of complexity.

Script tag approach

Paste this prompt into Base44's AI chat. Replace grtc-YOUR_CODE_HERE with the WebRTC code you created in Step 5:

In index.html, add this script tag just before the closing </body> tag:

<script src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js" data-webrtc-code="grtc-YOUR_CODE_HERE"></script>

After Base44 makes the change, the preview will rebuild and a green voice orb will appear in the bottom-right corner of your app. Click it to start a call.

React component approach

Paste this prompt into Base44's AI chat. Replace grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:

Create a new component called GuavaVoiceAgent. It should use a useEffect hook to create a script element, set its src to "https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js", set a data-webrtc-code attribute to "grtc-YOUR_CODE_HERE", append it to the document body, and remove it on cleanup. Then render this component in App.tsx (or the layout component).

Step 10 — Keep improving (optional)

Your agent is live on your Base44 app. As you get feedback from real conversations, you can keep refining it. From your Guava account, you can monitor your agent's status on the Deployments page and review every conversation on the Conversations page.

• Adjust what your agent says and does — make changes in your AI coding platform and redeploy with guava deploy up ./my-agent (replace my-agent with your project folder name if you renamed it). See the Agent docs for the full API.
• Add a knowledge base — let your agent answer questions from your own documents. See DocumentQA.
• Customize the widget — see WebRTC Widgets for widget appearance, states, and advanced configuration.