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

• calculator demonstrates the use of fulfillments to include custom logic in the Agent’s bejavior

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

Tip

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

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

User: Hello

Agent: Greetings, Human :)

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

class UserNameGive(user_name)

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.

Parameters

user_name (Person) – User said this is his name

class AgentNameGive(agent_name)

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.

Parameters

agent_name (Person) – Agent claims this is its name

class UserLikesMusic(music_genre="Rock 'n' Roll")

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.

Parameters

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

class GreetFriends(friend_names)

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.

Parameters

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

class UserAsksDay(date)

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)

Parameters

date (Date) – The date User wants to check

Intent Relations: Shop

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

Note

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)

   U: I’d like to buy a fish please

   A: What sort of fish would you like?

   Parameters

   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)

   U: I’d like to buy a kipper

   A: Alright, adding 1 kipper to cart

   Parameters

   amount (Integer) – The amount of kipper to buy

   fulfill(context, *args)

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

   class OrderFishAnswerKipper(amount=1, parent_order_fish=None)

   (“…what sort of fish would you like?”)

   U: kipper

   A: Kipper, good choice

   Parameters

   • 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)

   (“…adding one kipper to cart”)

   U: actually, make it 2

   A: Sure, 2 kippers for you

   Parameters

   • 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)

   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

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

add(item, amount)

Add an item to cart

Parameters

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

• amount (int) – Amount to add

update(item, amount)

Update an item in cart

Parameters

• 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

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)

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

Parameters

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

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

Fulfillment: Calculator

This module demonstrates fulfillment in action, by defining a simple calculator app. Here most of the responses cannot be defined in language files, because they are computed from intent parameters

class CalculatorOperator

These are simple math operators:

• “+”, “plus”

• “-“, “minus”

• “*”, “multiplied by”, “times”

• “/”, “divided by”, “over”

class SolveMathOperation(first_operand, second_operand, operator)

U: How much is 21 times two?

A: That’s 42

Parameters

• first_operand (Integer) –

• second_operand (Integer) –

• operator (CalculatorOperator) –

fulfill(context)

Compute the requested operation and sends the response back by triggering SolveMathOperationResponse. If an error occurs while solving the operation (e.g. a division by zero), SolveMathOperationError will be returned instead.

See intents.model.intent.Intent.fulfill() for more details about this method.

Parameters

• context (FulfillmentContext) – The fulfillment context, as it is

• by the Connector (passed) –

Returns

The Intent to trigger in response to the fulfillment

Return type

Intent

class SolveMathOperationResponse(operation_result)

This is triggered by SolveMathOperation to show the result to user. Note that this intent has a Session Parameter operation_result of type float. Session parameters are injected by software components; they are less constrained than NLU Parameters, but cannot be tagged in user utterances, therefore the only way to fire this intent is with a trigger (in our case, the result of SolveMathOperation.fulfill()).

Parameters

operation_result (float) –

class SolveMathOperationError

This is triggered by fulfillment if something goes wrong in calculations.

do_calculation(first_operand, second_operand, operator)

This is a helper function that solves a simple math operation

>>> do_calculation(2, 3, "+")
5

Parameters

• first_operand (int) –

• second_operand (int) –

• operator (str) –

Rich Responses: Travels

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

class UserWantsTravel

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

User: Recommend me a hotel

Agent: -hotel card-

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

class UserAskHolidayPicture

User: Send me a holiday picture

Agent: -picture-

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

class UserAskTrainStation

User: Where is the train station?

Agent: Address + -custom payload (location)-

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