Skills

This page focuses on the core concepts of a skill, how to create skills and update them for a new SDK version.

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. * You create a skill with the command gradlew createSkill --name=YourName [--folder=YourFolderPath] where the folder argument is optional. Example:

cd your/SDK/root
gradlew createSkill --name=FruitSeller --folder=../skills
  • 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.

SDK dependencies for skills

Each skill that you create is set up to use a specific version of the Furhat SDK. Currently, the skill usese two compoenents

  • skill-configuration containing relevant gradle tasks
  • furhat-commons, a library containing most of the features of the SDK.

References to both of these components are listed in the build.gradle file, and each have versions explicitly listed, or a "+" signaling to use the latest version available.

Upgrading of SDK dependency for skill

To update your SDK to a new version of the SDK, you go into your build.gradle file in the skill root and increment the furhat-commons version number to the same version as the SDK. For example, if you have the SDK version 1.4.1, then in your skill's build.gradle should list furhat-commons:1.4.1 as a dependency. The skill-configuration can stay untouched.

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.
    • build.gradle is the Gradle package management file that determines what Furhat SDK version your skill is using. See the section above for more info. This is also the place where you would add any other dependencies that your skill might need, for example http libraries.

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 deploy a skill to a furhat, you need to package the skill and then upload it through the robot's web-interface:

  • Navigate to your skill folder in your terminal
  • Use the command gradlew shadowJar on Windows, ./gradlew shadowJar on Mac and Linux. This will create a file named YourSkillName.skill in /build/libs in your skill repository.
  • Go to your robot's web-interface (see Furhat docs)
  • Go to the skills page and import the .skill file
  • Run the skill through the same page, once it's uploaded

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.