Example Agent

This is an example Agent that has a number of Intent categories. Each category demonstrates a specific set of features of the Intents library, and particularly:

  • smalltalk shows the fundamentals of Intents and their Parameters

  • shop demonstrates how to use Intent Relations to control the conversation flow

  • restaurant shows how to define Custom Entities

  • travels demonstrates the use of rich responses, such as Images, Cards and Quick Replies


Most of the interesting stuff about the Example Agent comes from its source code and may not be shown in documentation pages. Hit the [source] link (or browse the full code at https://github.com/dariowho/intents/tree/master/example_agent/) to know more about your topic of interest

class ExampleAgent[source]

An example agent that greets its users, and not much more…

Agent fundamentals: Smalltalk

These intents demonstrate the fundamentals of a Conversation: Intents and Entities.

class Hello[source]
User: Hello
Agent: Greetings, Human :)

The simplest possible intent: a greetings exchange with no parameters.

class UserNameGive(user_name)[source]
User: My name is Guido
Agent: Hi Guido

This demonstrates the use of a system entity that is recognized in the User utterance. Check example_agent.restaurant for custom entities.


user_name (Person) – User said this is his name

class AgentNameGive(agent_name)[source]
Agent: Howdy Human, my name is $agent_name

Note that this is Agent sending an unsolicided message to User, rather than predicting a response. The language file of the Intent will have no Example Utterances, meaning that the Intent can be triggered, but will never be predicted.


agent_name (Person) – Agent claims this is its name

class UserLikesMusic(music_genre="Rock 'n' Roll")[source]
User: I like music
Agent: I love Rock ‘n’ Roll!
User: I like Reggae music
Agent: I love Reggae!

This intent demonstrates the use of default parameter values: when User doesn’t specify a genre, Agent will assume it’s Rock ‘n’ Roll.


music_genre (MusicGenre) – User said he likes this genre, defaults to “Rock ‘n’ Roll”

class GreetFriends(friend_names)[source]
User: Say hi to my friends Al, John and Jack
Agent: Hello Al, John and Jack

This intent demonstrates the use of List parameters. In the example above, the friend_names parameter will be valued [“Al”, “John”, “Jack”].

Also, friend_names is a required parameter. When User doesn’t specify names, we want to ask her to do so in a slot filling manner. This is done by defining slot_filling_prompts in the Intent language file.


friend_names (List[Person]) – A list of friends to greet

class UserAsksDay(date)[source]
User: What day is it?
Agent: When?
User: today
Agent: That would be 2021-06-19

This is equivalent to GreetFriends; they are both intents with a required parameter that is prompted to User when missing in the original utterance.

One peculiarity of this one is the use of Sys.Date: prediction services are able to turn spoken time references (“today”, “last week”, “in a month”, …) into absolute values.

The date parameter is automatically casted to a python datetime.date object when this Intent is predicted (Sys.Date inherits from datetime.date):

>>> predicted = connector.predict("What day will be tomorrow?")
>>> predicted.intent.date
Sys.Date(2021, 6, 20)

date (Date) – The date User wants to check

Intent Relations: Shop

This module demonstrates the use of intent relations to create complex conversation flows.


Intent relations are under definition, they will be extended in next releases.

Let’s break down a complex interaction involving shop intents.

  1. U: I want a fish
    A: What sort of fish do you want?

    Standard Intent OrderFish starts the conversation.

    class OrderFish(amount=1)[source]
    U: I’d like to buy a fish please
    A: What sort of fish would you like?

    amount (Integer) – The amount of fish to buy

  2. U: A kipper
    A: Kipper, good choice. Adding 1 to cart

    Intent OrderFishAnswerKipper follows OrderFish. This means that the first can’t be predicted if the latter wasn’t predicted recently; this makes sense because an utterance like “a kipper” would sound really weird without context. Note that OrderFishAnswerKipper is a subclass of OrderKipper, and therefore inherits its OrderKipper.fulfill() method.

    Check out the source code of the intents below to see how the follow relation is implemented.

    class OrderKipper(amount=1)[source]
    U: I’d like to buy a kipper
    A: Alright, adding 1 kipper to cart

    amount (Integer) – The amount of kipper to buy

    fulfill(context, *args)[source]

    Use CartApi to add kippers to cart. The amount is specified by OrderKipper.amount

    class OrderFishAnswerKipper(amount=1, parent_order_fish=None)[source]
    (“…what sort of fish would you like?”)
    U: kipper
    A: Kipper, good choice
    • amount (Integer) – The amount of kipper to buy

    • parent_order_fish (Optional[OrderFish]) – The OrderFish intent from context

  3. U: Actually I want more
    A: How many would you like?

    ChangeAmount follows OrderKipper. Since OrderFishAnswerKipper is a subclass of OrderKipper, our agent can predict ChangeAmount at this point of the conversation. However, this intent defines a required parameter ChangeAmount.amount. Since amount can’t be tagged in the user utterance, the Agent will respond with one of the slot filling prompts for parameter “amount” (see intents.language).

    class ChangeAmount(amount, parent_order_kipper=None)[source]
    (“…adding one kipper to cart”)
    U: actually, make it 2
    A: Sure, 2 kippers for you
    • amount (Integer) – The new amount of kipper. Note that this overwrites all the other values for parameter “amount” in context, even if they come from other intents

    • parent_order_kipper (Optional[OrderKipper]) – The OrderKipper intent from context

    fulfill(context, *args)[source]

    Use CartApi to update the amount of kippers in cart to ChangeAmount.amount

  4. U: 3 please
    A: Alright, I changed the amount to 3

    User fills the slot, and ChangeAmount can finally be predicted.

class CartApi[source]

A mock API for a Customer cart. In real life, this connects to a service of some sort.

add(item, amount)[source]

Add an item to cart

  • item (str) – Name of the item to add

  • amount (int) – Amount to add

update(item, amount)[source]

Update an item in cart

  • item (str) – Name of the item to update

  • amount (int) – New amount to set

Custom Entities: Restaurant

This Intents demonstrate the use of Custom Entities, which are used to recognize simple food orders.

class PizzaType[source]

This entity represents different types of pizza, such as Margherita, Diavola, etc.

Language data for this entity can be found in example_agent/language/en/ENTITY_PizzaType.yaml.

class OrderPizza(pizza_type, amount=1)[source]

User is ordering a pizza, like “I want two Margherita please”

  • pizza_type (PizzaType) – The type of pizza User wants to order

  • amount (Integer) – The amount of pizzas User wants to order

Rich Responses: Travels

The travels module demonstrates the use of rich responses, such as images, cards and quick replies.

class UserWantsTravel[source]
User: I want to travel
Agent: How can I help? + -quick replies-

Check out example_agent/language/en/travels.UserWantsTravel.yaml for language data.

class UserAskHotelRecommendation[source]
User: Recommend me a hotel
Agent: -hotel card-

Check out example_agent/language/en/travels.UserAskHotelRecommendation.yaml for language data.

class UserAskHolidayPicture[source]
User: Send me a holiday picture
Agent: -picture-

Check out example_agent/language/en/travels.UserAskHolidayPicture.yaml for language data.

class UserAskTrainStation[source]
User: Where is the train station?
Agent: Address + -custom payload (location)-

Check out example_agent/language/en/travels.UserAskTrainStation.yaml for language data.