Skills

Preparations

Kotlin language

Skills (or applications) on the Furhat platform are built in our domain-specific-language (DSL) in the Kotlin programming language. To learn the fundamentals of Kotlin, we recommend the excellent documentation on kotlinlang.org. You don't need to be a Kotlin expert, or even an experienced developer, to build Furhat skills and will be able to pick up much along the way. General software engineering experience, both object-oriented and functional, is recommended for more advanced use-cases. For more information, see recommended competences

One of the great things about Kotlin is that you can use it interchangeably with Java, allowing you to import Java libraries and use preexisting Java code as you see fit.

Setting up IntelliJ IDEA

  • Make sure you have JDK 1.8.x installed
  • Make sure the Kotlin JVM version is used (File > Settings > Build, Execution, Deployment > Compiler > Kotlin Compiler and set to 1.8)
  • Set the default Working directory for Kotlin run configurations (Run -> Edit configurations -> Defaults -> Kotlin and set to $MODULE_DIR$)

Creating a skill

Follow the below steps to create your skill. Go to your SDK directory and run gradlew run to start the server. Access the web interface on localhost:8080. Go to the skills page of the web interface Create a skill and give it a name (for example FruitSeller).

Note: The skill will by default be created in the skills/ directory of your SDK directory

  • Import the skill into IntelliJ as a new project (or a new module if you already have a project). Select the build.gradle file in the skill folder and then use the default settings.

The contents of a skill

The building blocks of skills

A Furhat skill consists of the following building blocks:

The skill files

  • Code-wise, the skill boilerplate contains the following files:
    • main.kt is the starting point for your app. Starting off, it only needs to initiate the flow.
    • flow/general.kt is a boilerplate Idle state and Attention state with a default behavior for situation management.
    • flow/interaction.kt is a file with a Start state where you can start building your application. We recommend renaming this file to the purpose of the interaction. For a single-purpose skill, you might call it for example fruitseller.kt.
    • nlu/nlu.kt is a starting point to define your intents (and supporting entities) used in the parsing of speech.
    • users.kt is where we recommend to place user-data fields and extention methods of the UserManager (the class that the users helper object is an instance of)
    • assets is a folder where you for example can put a graphical interface.

Running a skill

Running a skill on the SDK development server

You can run a skill locally in two ways, from your IDE - IntelliJ IDEA or from the web interface. The benefit of running it from IntelliJ is that you can set breakpoints and use your console for debugging efficiently.

Running the skill from IntelliJ IDEA

  • Run the skill by going into the main.kt file and pressing the gradle icon to the left of the fun main()
  • Go to the web interface's dashboard page and notice that the skill is running
  • For consecutive runs you can just press the play button in IntelliJ or create your own run-configuration

Important note: If your skill crashes due to "not able to read skill.properties" then ensure that the working directory of your skill is set to the root folder of the skill. E.g C:/<PATH-TO-SDK>/skill/HelloWorld. To fix this for all future skills, go to Edit configurations -> Defaults -> Kotlin and change Working Directory to $MODULE_DIR$

Running a skill from web interface

You can also run skills from the web interface. Note, the compilation will be done separately (i.e not through IntelliJ IDEA) so you will have to compile it for every change made.

Running a skill on a robot

You can run a skill remotely on a robot in two ways, through IntelliJ IDEA or from the robot's hosted web interface (the skill is then deployed to the robot).

Running a skill on a robot from IntelliJ IDEA

  • Create a run-configuration for your skill (similar to "Running the skill locally from IntelliJ IDEA)
  • Add the JVM argument -Dfurhatos.skills.brokeraddress=<IP-ADDRESS-OF-ROBOT> with the IP of your robot. The port does not need to be specified.

Deploying a skill to a robot

  • To upload a skill to a furhat, zip the contents of the root folder of the skill.

Note: Often if you zip the root folder itself you will get a folder inside the zip-folder, this will not work. The contents of the folder needs to be in the root of the zip..

  • Import the zipped file. Your skill will now appear on the page.

Example skills

For inspiration, check out our example skills. We will continuously update and add new example skills here to show of new and improved features. Import the skills similarly to how you would import skills created locally.