Agent

guava.Agent is the entrypoint for creating Guava voice agents. Create an Agent instance, attach handlers, then attach to a channel.

Python
TypeScript

agent.py

import os
import guava

# Define our agent
agent = guava.Agent(
    name="Nova",
    organization="Acme Corp",
    purpose="Help customers with their orders.",
    pronunciations={"Acme": "Ack-mee", "Waukesha": "/ˈwɔːkɪʃɔː/"},
)

# Register handlers
@agent.on_call_start
def on_call_start(call: guava.Call):
    ...

# Attach to a channel
agent.listen_phone(os.environ["GUAVA_AGENT_NUMBER"])

agent.ts

import * as guava from "@guava-ai/guava-sdk";

// Define our agent
const agent = new guava.Agent({
  name: "Nova",
  organization: "Acme Corp",
  purpose: "Help customers with their orders.",
  pronunciations: {"Acme": "Ack-mee", "Waukesha": "/ˈwɔːkɪʃɔː/"},
});

// Register handlers
agent.onCallStart(async (call) => {
  ...
});

// Attach to a channel
agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);

Constructor

Use the constructor parameters to configure your Agent’s persona and goal.

Python
TypeScript

guava.Agent(
    # The name the agent uses to identify itself to callers.
    name: str | None = None,

    # The organization the agent represents.
    organization: str | None = None,

    # High-level description of the agent's role.
    purpose: str | None = None,

    # Map words to custom pronunciations.
    pronunciations: dict[str, str] | None = None,

    # How quickly the agent speaks.
    speech_speed: Literal["x-slow", "slow", "medium", "fast", "x-fast"] | None = None,
)

new guava.Agent({
  // The name the agent uses to identify itself to callers.
  name?: string,

  // The organization the agent represents.
  organization?: string,

  // High-level description of the agent's role.
  purpose?: string,

  // Map words to custom pronunciations.
  pronunciations?: Record<string, string>,

  // How quickly the agent speaks.
  speechSpeed?: "x-slow" | "slow" | "medium" | "fast" | "x-fast",
})

Custom pronunciations can be passed as a dictionary mapping plaintext strings to either International Phonetic Alphabet (IPA) transcriptions wrapped in slashes, e.g. /pɪˈkɑːn/, or plaintext phonetic respellings, e.g. "peekan". Inline phonetic control can be supplied using SSML: My favorite nut is the <phoneme alphabet="ipa" ph="pɪˈkɑːn">pecan</phoneme>. What's yours?

Python
TypeScript

speech_speed sets how quickly the agent speaks, as one of the presets "x-slow", "slow", "medium" (the default), "fast", or "x-fast". The preset applies to every call the agent handles; use call.set_persona() to change it for a single call.

speechSpeed sets how quickly the agent speaks, as one of the presets "x-slow", "slow", "medium" (the default), "fast", or "x-fast". The preset applies to every call the agent handles; use call.setPersona() to change it for a single call.

Handlers

Python
TypeScript

Handler	Description
`on_call_received`	This handler is invoked on incoming calls. You can choose whether to reject or accept the call. The default behavior if not provided is to accept every call.
`on_call_start`	Called when a call begins. Unlike `on_call_received`, this handler is invoked for both incoming and outgoing calls. Use this handler to set initial tasks and context for the Agent.
`on_caller_speech`	Called each time the caller speaks.
`on_agent_speech`	Called each time the agent speaks.
`on_question`	Called when the caller asks the agent a question it cannot answer from context alone. The provided answer is relayed back to the caller.
`on_task_complete`	Called when the Agent completes a Task previously set using `call.set_task`.
`on_search_query`	Provide dynamic search results for a searchable Field.
`on_action_request` / `on_action`	Called when the caller asks for a specific action, e.g. “can I reset my password?”
`on_session_end`	Called when the session ends. Read `event.termination_reason` to find out why the call ended.
`on_reach_person`	Called when a `reach_person` task completes.
`on_outbound_failed`	Called when an outbound call fails to dial.
`on_escalate`	Called when an escalation is triggered. Read `event.requested_by` (`'human'` or `'agent'`) to determine which party requested the escalation.
`on_caller_dtmf`	Called when the caller presses a keypad key (DTMF). Previously named `on_dtmf`, which still works.
`on_agent_dtmf`	Called when the agent presses keypad keys (DTMF). Read `event.requested_by` (`'agent'` or `'developer'`) to tell an agentic press from one you asked for.

Handler	Description
`onCallReceived`	This handler is invoked on incoming calls. You can choose whether to reject or accept the call. The default behavior if not provided is to accept every call.
`onCallStart`	Called when a call begins. Unlike `onCallReceived`, this handler is invoked for both incoming and outgoing calls. Use this handler to set initial tasks and context for the Agent.
`onCallerSpeech`	Called each time the caller speaks.
`onAgentSpeech`	Called each time the agent speaks.
`onQuestion`	Called when the caller asks the agent a question it cannot answer from context alone. The provided answer is relayed back to the caller.
`onTaskComplete`	Called when the Agent completes a Task previously set using `call.setTask`.
`onSearchQuery`	Provide dynamic search results for a searchable Field.
`onActionRequest` / `onAction`	Called when the caller asks for a specific action, e.g. “can I reset my password?”
`onSessionEnd`	Called when the session ends. Read `event.termination_reason` to find out why the call ended.
`onReachPerson`	Called when a `reachPerson` task completes.
`onOutboundFailed`	Called when an outbound call fails to dial.
`onEscalate`	Called when an escalation is triggered. Read `event.requested_by` (`'human'` or `'agent'`) to determine which party requested the escalation.
`onCallerDtmf`	Called when the caller presses a keypad key (DTMF). Previously named `onDtmf`, which still works.
`onAgentDtmf`	Called when the agent presses keypad keys (DTMF). Read `event.requested_by` (`'agent'` or `'developer'`) to tell an agentic press from one you asked for.

Entrypoints / Channels

Attach the agent to a channel to start receiving calls.

Python
TypeScript

Entrypoint	Description
`listen_phone("+1...")`	Listen for inbound phone calls on the given phone number.
`listen_webrtc(code?)`	Listen for inbound WebRTC connections to the given agent code. If not provided, a temporary agent code is automatically created.
`listen_sip("guavasip-...")`	Listen for inbound SIP connections to the given SIP code.
`call_phone(from_number, to_number, variables?)`	Place a single outbound phone call.
`call_local()`	Call the agent using your local audio device (for testing).
`attach_campaign(campaign)`	Attach an agent to an outbound Campaign.
`chat(variables?)`	Start an interactive terminal chat session with the agent (for testing).
`test(variables?)`	Starts a live test session for programmatic testing.
`roleplay(roleplay_prompt, variables?)`	Run an automated test where an LLM roleplays as the caller.

Entrypoint	Description
`listenPhone("+1...")`	Listen for inbound phone calls on the given phone number.
`listenWebrtc(code?)`	Listen for inbound WebRTC connections to the given agent code. If not provided, a temporary agent code is automatically created.
`listenSip("guavasip-...")`	Listen for inbound SIP connections to the given SIP code.
`callPhone(from_number, to_number, variables?)`	Place a single outbound phone call.
`callLocal()`	Call the agent using your local audio device (for testing).
`attachCampaign(campaign)`	Attach an agent to an outbound Campaign.
`chat(variables?)`	Start an interactive terminal chat session with the agent (for testing).
`test(variables?)`	Starts a live test session for programmatic testing.
`roleplay(roleplayPrompt, variables?)`	Run an automated test where an LLM roleplays as the caller.

To attach an agent to multiple channels, or run multiple agents in the same process, use guava.Runner.

Getting started

Agent SDK

CLI reference

WebRTC

SIP calling

Phone numbers

Deployments

Compliance

Release notes

Constructor

Handlers

Entrypoints / Channels

​Constructor

​Handlers

​Entrypoints / Channels

Constructor

Handlers

Entrypoints / Channels