docs/Intent Helpers

Intent Helpers

Guava provides two intent classification helpers for routing caller requests: IntentRecognizer for single-best-match classification, and IntentClarifier for surfacing multiple plausible matches when the caller's intent is ambiguous.

Both classes are imported from guava.helpers.openai.

IntentRecognizer

IntentRecognizer classifies a free-text caller utterance into one of your predefined intent labels. Use it inside on_action_request() to map vague caller language to clean routing decisions.

signature
from guava.helpers.openai import IntentRecognizer

IntentRecognizer(intent_choices: list[str] | dict[str, str], client: openai.OpenAI | None = None)
recognizer.classify(intent: str) -> str | None
ParameterTypeRequiredDescription
intent_choiceslist[str] | dict[str, str]YesThe set of intents to classify into. Pass a list of choice strings, or a dict mapping choice strings to plain-English descriptions (descriptions improve accuracy on similar-sounding choices).
clientopenai.OpenAINoAn OpenAI client to use. If omitted, a client is created automatically.

classify(intent: str) -> str | None — Returns the single choice string from intent_choices that best matches intent, or None if the model cannot match any choice. When intent_choices is a dict, the keys are the valid return values; values are used only as descriptions to guide the model.

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

agent = Agent(
    name="Support",
    organization="Acme Corp",
    purpose="Help the caller with their support request.",
)

intent_recognizer = IntentRecognizer(
    ['check order status', 'bill pay', 'anything else']
)

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

@agent.on_action("check order status")
def check_order_status(call: guava.Call):
    call.transfer("+15555555555", "Transfer the caller to the order status team.")

@agent.on_action("bill pay")
def bill_pay(call: guava.Call):
    call.transfer("+15555555555", "Transfer the caller to billing.")

@agent.on_action("anything else")
def anything_else(call: guava.Call):
    call.transfer("+15555555555", "Connect the caller with a live agent.")

IntentClarifier

IntentClarifier analyzes a caller's intent and returns the subset of choices that could plausibly match, ordered by likelihood. Use this when an intent may be ambiguous and you need to surface options for the caller to confirm.

signature
from guava.helpers.openai import IntentClarifier

IntentClarifier(intent_choices: list[str] | dict[str, str], client: openai.OpenAI | None = None)
clarifier.propose_choices(intent: str) -> list[str]
ParameterTypeRequiredDescription
intent_choiceslist[str] | dict[str, str]YesThe set of intents to match against. Same format as IntentRecognizer.
clientopenai.OpenAINoAn OpenAI client to use. If omitted, a client is created automatically.

propose_choices(intent: str) -> list[str] — Returns a list of choices that could match intent, ordered by likelihood:

  • One element if the intent clearly maps to a single choice.
  • Multiple elements if the intent is ambiguous.
  • Empty list if the intent matches none of the provided choices.

An empty list means the caller's intent is out-of-scope — not that an error occurred. When intent_choices is a dict, only the keys appear in the returned list.

scheduler_agent.py
import guava
from guava import Agent, SuggestedAction
from guava.helpers.openai import IntentClarifier

agent = Agent(
    name="Scheduler",
    organization="Acme Corp",
    purpose="Help callers manage their appointments.",
)

intent_clarifier = IntentClarifier(
    ['reschedule appointment', 'cancel appointment', 'check appointment time']
)

@agent.on_action_request
def on_action_request(call: guava.Call, request: str) -> SuggestedAction:
    matches = intent_clarifier.propose_choices(request)
    if len(matches) == 1:
        # Unambiguous — proceed directly
        return SuggestedAction(key=matches[0])
    elif len(matches) > 1:
        # Ambiguous — route to the most likely match; agent will confirm with caller
        return SuggestedAction(key=matches[0], description=f"Caller may have meant one of: {matches}")
    # len == 0: no match, return nothing so the agent keeps listening

Model details: Both IntentRecognizer and IntentClarifier use gpt-5-mini with a hardcoded reasoning.effort of "low". These settings are not configurable.

→ Next: DocumentQA

Questions? hi@goguava.ai