Field
A Field is a Task checklist item instructing the Guava agent to collect structured data from the caller. The agent elicits the value through natural conversation, validates it against the specified type, and marks the checklist item complete when satisfied.
signature
guava.Field(
# Identifier used to retrieve the value via get_field() after collection.
key: str,
# Natural-language instruction to the LLM about how to collect this value.
# Use when you do not particularly care how the agent phrases its question.
description: str = '',
# Encourages the agent to ask for the field in a particular way. Use instead
# of description when you want more control over the phrasing.
question: str = '',
# Controls parsing and validation. "calendar_slot" and "multiple_choice"
# require either choices or searchable=True.
field_type: Literal[
'text', 'date', 'datetime', 'integer', 'multiple_choice', 'calendar_slot'
] = 'text',
# If False, the agent can skip this field if the caller is unwilling to provide it.
required: bool = True,
# Static list of valid options for "calendar_slot" and "multiple_choice" fields.
# Use when the list is small. Large lists should use searchable=True.
choices: list[str] = [],
# When True, enables dynamic search for "multiple_choice" and "calendar_slot"
# fields. The agent searches for options matching the caller's query at runtime.
searchable: bool = False,
)Basic Examples
examples.py
# Basic text field
field = guava.Field(
key="caller_name",
description="Get the caller's name",
)
# Integer field with question
field = guava.Field(
key="caller_age",
question="How old are you?",
field_type="integer",
)
# Multiple choice with static choices
field = guava.Field(
key="caller_preference",
description="Get the caller's preferred fruit",
field_type="multiple_choice",
# Use searchable=True instead when there's a large number of choices
choices=["apple", "banana", "orange"],
required=False,
)Search Fields
Some fields can have a very large set of valid options.
For example, a destination_airport field may include thousands of airports worldwide.
In other cases, options must be generated dynamically, such as an appointment_time field populated from a booking system.
This is where search fields come in handy. Set searchable=True on the field, then register an @agent.on_search_query handler.
When the agent needs options, it calls your handler with a natural-language query string.
Return two lists: a primary list of matches, and a fallback list shown only when no primary matches are found.
search_field.py
field = guava.Field(
key="airport",
description="Find a suitable airport for the caller",
field_type="multiple_choice",
searchable=True,
)
@agent.on_search_query("airport")
def search_airports(call: guava.Call, query: str):
matching_airports: list[str] = []
other_airports: list[str] = []
...
# Do some work to generate a few matching airport
# options based on the caller's query.
# 'query' will be human natural language
# (e.g. "I need to fly out of an airport in
# southern california")
...
# The second list only becomes relevant if there
# are no matches to the caller's query. It is used
# to at least present something to the caller in
# case there are no perfect matches.
return matching_airports, other_airportsField Types Reference
| Type | Example collected value | Return type from get_field() |
|---|---|---|
text | "I want to cancel my appointment" | str |
date | {"year": 2024, "month": 3, "day": 15} | dict with keys year, month, day (all int) |
integer | 42 | int |
multiple_choice | "apple" | str (guaranteed to be one of choices or returned by choice_generator) |
calendar_slot | "2022-12-31T17:30" | ISO-8601 datetime str |
Note: The choices list for calendar_slot fields must be ISO-8601 datetimes (e.g. "2022-12-31T17:30").
Questions? hi@goguava.ai
guava.Field(
# Identifier used to retrieve the value via get_field() after collection.
key: str,
# Natural-language instruction to the LLM about how to collect this value.
# Use when you do not particularly care how the agent phrases its question.
description: str = '',
# Encourages the agent to ask for the field in a particular way. Use instead
# of description when you want more control over the phrasing.
question: str = '',
# Controls parsing and validation. "calendar_slot" and "multiple_choice"
# require either choices or searchable=True.
field_type: Literal[
'text', 'date', 'datetime', 'integer', 'multiple_choice', 'calendar_slot'
] = 'text',
# If False, the agent can skip this field if the caller is unwilling to provide it.
required: bool = True,
# Static list of valid options for "calendar_slot" and "multiple_choice" fields.
# Use when the list is small. Large lists should use searchable=True.
choices: list[str] = [],
# When True, enables dynamic search for "multiple_choice" and "calendar_slot"
# fields. The agent searches for options matching the caller's query at runtime.
searchable: bool = False,
)# Basic text field
field = guava.Field(
key="caller_name",
description="Get the caller's name",
)
# Integer field with question
field = guava.Field(
key="caller_age",
question="How old are you?",
field_type="integer",
)
# Multiple choice with static choices
field = guava.Field(
key="caller_preference",
description="Get the caller's preferred fruit",
field_type="multiple_choice",
# Use searchable=True instead when there's a large number of choices
choices=["apple", "banana", "orange"],
required=False,
)field = guava.Field(
key="airport",
description="Find a suitable airport for the caller",
field_type="multiple_choice",
searchable=True,
)
@agent.on_search_query("airport")
def search_airports(call: guava.Call, query: str):
matching_airports: list[str] = []
other_airports: list[str] = []
...
# Do some work to generate a few matching airport
# options based on the caller's query.
# 'query' will be human natural language
# (e.g. "I need to fly out of an airport in
# southern california")
...
# The second list only becomes relevant if there
# are no matches to the caller's query. It is used
# to at least present something to the caller in
# case there are no perfect matches.
return matching_airports, other_airports