Documentation | Guava

Agent

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

Example

import os
import guava

# Define our agent
agent = guava.Agent(
    name="Nova",
    organization="Acme Corp",
    purpose="Help customers with their orders.",
)

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

Handlers

Handler	Description
`on_call_received`	This handler is invoked on incoming calls. You can chose 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.

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("grtc-..."	None)`
`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.
`test_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.