on_task_complete()

on_task_complete is called when a Task previously set with call.set_task() is completed by the agent. Use it to persist collected data, trigger downstream workflows, or move the call to the next stage.

Signature

There are two forms:

signature
# Per-task form (recommended)
@agent.on_task_complete("task_name")
def handler(call: guava.Call) -> None:
    ...

# Generic form — fires for all tasks
@agent.on_task_complete
def handler(call: guava.Call, task_id: str) -> None:
    ...
  • Per-task form (recommended): @agent.on_task_complete("task_name") binds the handler to a specific task_id. The handler receives only the Call object.
  • Generic form: @agent.on_task_complete (bare decorator) fires for every completed task. The handler receives the Call object and the task_id string, letting you dispatch on it manually.

You cannot mix both forms on the same agent — using per-task handlers alongside a generic handler raises a TypeError.

  • on_task_complete fires once all checklist items are resolved and the agent has signaled completion.
  • Use call.get_field() inside the handler to read values collected during the task.
  • The call is still live when this handler runs — you can issue commands such as call.set_task(), call.hangup(), or call.transfer().

Example

waitlist_controller.py
import logging
import guava
from guava import Agent

logger = logging.getLogger(__name__)

agent = Agent(
    organization="Thai Palace",
    purpose="Add callers to the waitlist",
)

@agent.on_call_start
def on_call_start(call: guava.Call):
    call.set_task(
        "waitlist",
        objective="Add the caller 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 ready"),
            "Read the phone number back to the caller to confirm.",
        ],
    )

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

Questions? hi@goguava.ai