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]

This is a base class for user defined intents, which are the fundamental building blocks of your Agent.

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.UserSaysHello.yaml. Note that the name of the module where the Intent is defined ( 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

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

    user_name: Sys.Person

    name = "hello_custom_name"
    lifespan = 10

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

This intent has a lifespan member. This is used in intents.model.relations to determine how long should the Intent stay in the conversation context after it is predicted.

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
>>> predicted.intent.user_name
>>> predicted.fulfillment_text
"Hi John, I'm Agent"


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.

fulfill(context, **kwargs)[source]

Override this method to define a custom procedure that will be invoked when the Intent is predicted, possibly triggering another intent as a result. For instance:

class UserConfirmsPayment(Intent):

    parent_order: UserOrdersSomething = follow()

    def fulfill(self, context):
        if shop_api.is_item_available(parent_order.item_id):
            return OrderSuccessResponse()
            return OrderFailedResponse()

In the example, when UserConfirmsPayment is predicted, it will run some business logic, and choose a different response depending on the result. Note that response objects are full-fledged Intents, and even though they probably won’t include example utterances, they can define parameters, relations, and their own fulfillment() implementation, that will be executed recursively.

More details about fulfillments can be found in the fulfillment module documentation.


context (FulfillmentContext) – Context information about the fulfillment request (confidence, language, …)

Return type



A FulfillmentResult object, that can contain a followup intent to trigger, or just some responses to post back to user.

classmethod parent_intents()[source]

Return a list of the Intent parent classes. This wraps cls.mro() filtering out non-Intent parents (e.g. object), Intent and cls itself.

>>> AskEspresso.parent_intents()
[AskCoffee, AskDrink]
Return type



A list of parent Intent classes

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.

>>> OrderPizzaIntent.parameter_schema
    'pizza_type': IntentParameterMetadata(name='pizza_type', entity_cls=<...PizzaType'>, is_list=False, required=True, default=None),
    'amount': IntentParameterMetadata(name='amount', entity_cls=<...Sys.Integer'>, is_list=False, required=False, default=1)
  • name (str) – Parameter name

  • entity_cls (EntityType) – 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

class FulfillmentContext(confidence, fulfillment_text, fulfillment_messages, language)[source]

FulfillmentContext objects are produced by Connectors and are input arguments to Intent.fulfill().

  • confidence (float) –

  • fulfillment_text (str) –

  • fulfillment_messages (IntentResponseDict) –

  • language (LanguageCode) –

class FulfillmentResult(trigger=None, fulfillment_text=None, fulfillment_messages=None)[source]

FulfillmentResult are produced by Intent.fulfill, and then converted by Connectors into Service-actionable responses.


At the moment this class is only used internally. It is safe to return simple Intent instances in Intent.fulfill()

  • trigger (Optional[Intent]) –

  • fulfillment_text (Optional[List[str]]) –

  • fulfillment_messages (Optional[List[IntentResponse]]) –

static ensure(fulfill_return_value)[source]

Convert the given object to a FulfillmentResult instance, if it is not already one.


fulfill_return_value (Union[FulfillmentResult, Intent]) – An object, as it is returned by Intent.fulfill()


ValueError – If input object is not a valid return value for Intent.fulfill()


A FulfillmentResult object representing input

Return type