Intent

An intent is a categorical representation of the User intention in a single conversation turn. For instance, utterances like “I want a pizza”, “I’d like to order a pizza” and such, could be mapped to a single OrderPizza intent.

Your agent will typically define a number of intents, representing all the types of messages the Agent can understand and answer to. This is done by defining Intent sub-classes and their language resources (see intents.language), and registering them to an intents.Agent class with intents.Agent.register().

class Intent[source]

Represents a predicted intent. This is also used as a base class for the intent classes that model a Dialogflow Agent in Python code.

In its simplest form, an Intent can be defined as follows:

from intents import Intent

class UserSaysHello(Intent):
    """A little docstring for my Intent"""

Intents will then look for language resources in the folder where your Agent class is defined, and specifically in language/<LANGUAGE-CODE>/smalltalk.user_says_hello.yaml. Note that the name of the module where the Intent is defined (smalltalk.py) is used as a prefix. More details in intents.language.

Intents can be more complex than this, for instance:

from dataclasses import dataclass
from intents import Intent, Sys

@dataclass
class UserSaysHello(Intent):
    """A little docstring for my Intent"""

    user_name: Sys.Person

    name = "hello_custom_name"

This Intent has a custom name, so it will appear as “hello_custom_name” when exported to Dialogflow, and its language file will just be hello_custom_name.yaml, without module prefix. See check_intent_name() for more details on the rules that intent names must follow.

Most importantly, this intent has a user_name parameter of type Sys.Person (check out intents.model.entity.Sys for available system entities). With adequate examples in its language file, it will be able to match utterances like “Hello, my name is John”, tagging “John” as an Entity. When a connector is instantiated, predictions will look like this:

>>> predicted = connector.predict("My name is John")
>>> predicted.intent
user_says_hello(user_name="John")
>>> predicted.intent.user_name
"John"
>>> predicted.fulfillment_text
"Hi John, I'm Agent"

Warning

Parameter names are meant to be unique within an Agent. That is, the same parameter must always be defined with the same type. This is because 1) Some services (e.g. Alexa) require so. 2) Predictions overwrite parameters in context based on their name: better make sure they are compatible.

Last, we notice the @dataclass decorator. We require it to be added explicitly, this way IDEs will recognize the Intent class as a dataclass and provide correct hints for names and types.

class IntentParameterMetadata(name, entity_cls, is_list, required, default)[source]

Model metadata of a single Intent parameter. IntentParameterMetadata objects are built internally by Intent.parameter_schema() based on the Intent dataclass fields.

Parameters

  • name (str) – Parameter name

  • entity_cls (_EntityMetaclass) – Parameter type

  • is_list (bool) – Parameter will match multiple values in the User utterance

  • required (bool) – If True, user will be prompted for parameter value when that can’t be tagged in his utterance

  • default (Any) – If set, this value will be used when parameter value can’t be tagged in the User’s utterance

check_intent_name(candidate_name)[source]

Raise ValueError if the given Intent name is not a valid name. Valid names

  • Only contain letter, underscore (_) and period (.) characters

  • Start with a letter

  • Don’t contain repeated underscores (e.g. __)

  • Don’t start wit i_. This is a reserved prefix for Intents system intents

Note that Agent.register will apply further checks to spot duplicate intent names. Note that names are case insensitive, and shouldn’t overlap with parameter names.

Parameters

candidate_name (str) – The Intent name to check