Agent

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

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"])

Constructor

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

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,
)

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?

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.

Handlers

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.

Entrypoints / Channels

Attach the agent to a channel to start receiving calls.

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.

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

→ Next: Task

Questions? hi@goguava.ai

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"])

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,
)