Documentation | Guava

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.

PythonTypeScript

# Field Example
field = guava.Field(
    key="caller_name",
    description="Get the caller's name",
)

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.
    description: str = '',

# Encourages the agent to ask for the field in a particular way.
    question: str = '',

# Controls parsing and validation.
    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.
    choices: list[str] = [],

# When True, enables dynamic search for "multiple_choice" and "calendar_slot" fields.
    searchable: bool = False,
)

Basic Examples

# 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",
    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.

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] = []
    ...
    return matching_airports, other_airports

Field Types Reference