> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> The entrypoint for creating Guava voice agents

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

<Tabs>
  <Tab title="Python">
    ```python agent.py theme={null}
    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"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript agent.ts theme={null}
    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!);
    ```
  </Tab>
</Tabs>

## Constructor

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

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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,
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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",
    })
    ```
  </Tab>
</Tabs>

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?`

<Tabs>
  <Tab title="Python">
    `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()`](/sdk-reference/set-persona) to change it for a single call.
  </Tab>

  <Tab title="TypeScript">
    `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()`](/sdk-reference/set-persona) to change it for a single call.
  </Tab>
</Tabs>

## Handlers

Register handlers to control and react to the call in real-time.

<Tabs>
  <Tab title="Python">
    | 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`](/sdk-reference/on-caller-speech) | Called each time the caller speaks. |
    | [`on_agent_speech`](/sdk-reference/on-agent-speech) | Called each time the agent speaks. |
    | [`on_question`](/sdk-reference/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`](/sdk-reference/on-task-complete) | Called when the Agent completes a [Task](/sdk-reference/tasks) previously set using `call.set_task`. |
    | `on_search_query` | Provide dynamic search results for a searchable [Field](/sdk-reference/field). |
    | [`on_action_request` / `on_action`](/sdk-reference/on-action-request-execute) | Called when the caller asks for a specific action, e.g. "can I reset my password?" |
    | [`on_session_end`](/sdk-reference/on-session-end) | Called when the session ends. Read `event.termination_reason` to find out why the call ended. |
    | [`on_reach_person`](/sdk-reference/reach-person) | Called when a `reach_person` task completes. |
    | `on_outbound_failed` | Called when an outbound call fails to dial. |
    | [`on_escalate`](/sdk-reference/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`](/sdk-reference/on-caller-dtmf) | Called when the caller presses a keypad key (DTMF). Previously named `on_dtmf`, which still works. |
    | [`on_agent_dtmf`](/sdk-reference/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. |
  </Tab>

  <Tab title="TypeScript">
    | 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`](/sdk-reference/on-caller-speech) | Called each time the caller speaks. |
    | [`onAgentSpeech`](/sdk-reference/on-agent-speech) | Called each time the agent speaks. |
    | [`onQuestion`](/sdk-reference/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. |
    | [`onTaskComplete`](/sdk-reference/on-task-complete) | Called when the Agent completes a [Task](/sdk-reference/tasks) previously set using `call.setTask`. |
    | `onSearchQuery` | Provide dynamic search results for a searchable [Field](/sdk-reference/field). |
    | [`onActionRequest` / `onAction`](/sdk-reference/on-action-request-execute) | Called when the caller asks for a specific action, e.g. "can I reset my password?" |
    | [`onSessionEnd`](/sdk-reference/on-session-end) | Called when the session ends. Read `event.termination_reason` to find out why the call ended. |
    | [`onReachPerson`](/sdk-reference/reach-person) | Called when a `reachPerson` task completes. |
    | `onOutboundFailed` | Called when an outbound call fails to dial. |
    | [`onEscalate`](/sdk-reference/on-escalate) | Called when an escalation is triggered. Read `event.requested_by` (`'human'` or `'agent'`) to determine which party requested the escalation. |
    | [`onCallerDtmf`](/sdk-reference/on-caller-dtmf) | Called when the caller presses a keypad key (DTMF). Previously named `onDtmf`, which still works. |
    | [`onAgentDtmf`](/sdk-reference/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. |
  </Tab>
</Tabs>

## Entrypoints / Channels

Attach the agent to a channel to start receiving calls.

<Tabs>
  <Tab title="Python">
    | 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](/guides/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. |
  </Tab>

  <Tab title="TypeScript">
    | 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](/guides/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. |
  </Tab>
</Tabs>

<Tip>
  To attach an agent to multiple channels, or run multiple agents in the same process, use [`guava.Runner`](/sdk-reference/runner).
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.