on_action_request() / on_action()

These handlers are used when the caller expresses an intent or action (e.g. "I'd like to pay my bill"). The flow is as follows.

1. The caller makes a request — e.g. "I'd like to check the status of my order."
2. Guava invokes on_action_request with a summary of the request — e.g. "the customer would like to check the status of their order."
3. You classify the request and return a SuggestedAction — e.g. SuggestedAction(key="order_status"). You can use our built-in IntentRecognizer helper, or build your own intent classifier. Return None if no action matches the request.
4. Guava decides whether to execute the action — it may proceed immediately or ask the caller to confirm.
5. Guava executes the action — The on_action handler registered under the matching suggested action key is called.

@agent.on_action_request
def on_action_request(call: guava.Call, request: str) -> SuggestedAction | None:
    # request: natural-language summary of what the caller wants
    # return: SuggestedAction(key=...) or None

@agent.on_action("action_key")
def handler(call: guava.Call) -> None:
    # Runs when Guava executes the action with the matching key
    ...

Interaction with on_question

A caller utterance can be both a question and an action (e.g. "Could you help me pay my bill?"). In this case Guava will invoke both callbacks in parallel and synthesize an appropriate response based on the results.

For example, if on_question returns "Yes, we handle bill payment" and on_action_request returns SuggestedAction(key="bill_pay"), Guava may immediately chain into executing the action, or it may respond "Yes — would you like to get started?" to confirm the action with the caller.

Example

from guava import Agent, SuggestedAction
from guava.helpers.openai import IntentRecognizer

agent = Agent(name="Nova", organization="Thai Palace", purpose="...")

ACTIONS = {
    "reservation": "for handling reservations",
    "waitlist": "additions to the waitlist",
    "delivery": "for takeout orders",
    "hiring": "for people looking for jobs",
    "order_for_pickup": "",
}

intent_recognizer = IntentRecognizer(ACTIONS)


@agent.on_action_request
def on_action_request(call: guava.Call, request: str) -> SuggestedAction | None:
    key = intent_recognizer.classify(request)
    return SuggestedAction(key=key) if key else None


@agent.on_action("reservation")
def reservation(call: guava.Call):
    call.set_task(...)


@agent.on_action("waitlist")
def waitlist(call: guava.Call):
    call.set_task(...)