Documentation

Task

A task is the unit of work your agent completes on a call. Call call.set_task() to direct the agent toward a new goal. You can invoke call.set_task() on one of your handler callbacks, or at any time (even on another thread).

signature

call.set_task(
    # Unique identifier for this task, used to bind on_task_complete handlers.
    task_id: str,

    # High-level goal for the agent. Provides context when no checklist is given,
    # or alongside a checklist to frame the overall objective.
    objective: str = "",

    # Ordered list of items for the agent to complete during the call.
    checklist: list[Field | Say | str] | None = None,

    # Optional extra guidance on when to consider this task done. Useful for
    # open-ended tasks where the checklist alone doesn't define completion.
    completion_criteria: str = "",
)

Checklist items

The checklist drives the agent forward. Each item is one of three types:

Type	Purpose
`guava.Field`	Collect structured data from the caller
`guava.Say`	Speak a verbatim statement
`str`	Natural language instruction for the agent

guava.Say A guava.Say step is spoken verbatim — use it sparingly when exact wording matters.

Example

example.py

@agent.on_call_start
def on_call_start(call: guava.Call):
    call.set_task(
        "waitlist",
        objective="You are a virtual assistant for Thai Palace. Add callers to the waitlist.",
        checklist=[
            guava.Field(key="caller_name", field_type="text", description="Name for the waitlist"),
            guava.Field(key="party_size", field_type="integer", description="Number of people"),
            guava.Field(
                key="phone_number",
                field_type="text",
                description="Phone number to text when the table is ready",
            ),
            "Read the phone number back to the caller to confirm.",
        ],
    )

@agent.on_task_complete("waitlist")
def on_waitlist_done(call: guava.Call):
    logger.info("Added %s, party of %d, to waitlist.",
        call.get_field("caller_name"), call.get_field("party_size"))
    call.hangup("Thank the caller and let them know we'll text when their table is ready.")

→ Next: Fields

Questions? hi@goguava.ai

call.set_task(
    # Unique identifier for this task, used to bind on_task_complete handlers.
    task_id: str,

    # High-level goal for the agent. Provides context when no checklist is given,
    # or alongside a checklist to frame the overall objective.
    objective: str = "",

    # Ordered list of items for the agent to complete during the call.
    checklist: list[Field | Say | str] | None = None,

    # Optional extra guidance on when to consider this task done. Useful for
    # open-ended tasks where the checklist alone doesn't define completion.
    completion_criteria: str = "",
)

@agent.on_call_start
def on_call_start(call: guava.Call):
    call.set_task(
        "waitlist",
        objective="You are a virtual assistant for Thai Palace. Add callers to the waitlist.",
        checklist=[
            guava.Field(key="caller_name", field_type="text", description="Name for the waitlist"),
            guava.Field(key="party_size", field_type="integer", description="Number of people"),
            guava.Field(
                key="phone_number",
                field_type="text",
                description="Phone number to text when the table is ready",
            ),
            "Read the phone number back to the caller to confirm.",
        ],
    )

@agent.on_task_complete("waitlist")
def on_waitlist_done(call: guava.Call):
    logger.info("Added %s, party of %d, to waitlist.",
        call.get_field("caller_name"), call.get_field("party_size"))
    call.hangup("Thank the caller and let them know we'll text when their table is ready.")