Skip to main content

Local Development Workflow

Because Skills are designed as webhooks, they are often implemented as a serverless function, such as an Azure Function or an AWS Lambda. A Skill consists of an HTTP endpoint which expects to receive a POST request from the Soul Machines platform, and should respond with a JSON-formatted HTTP response.

Skills may be developed locally in much the same way as any other cloud function or webhook. For rapid iteration it is recommended to do most development independent of a Digital Person, although testing with a live Digital Person is also supported.

While in development, a Skill may be tested in the following ways:

  1. Command-line REPL
    Each starter template includes a command line REPL for sending mock user inputs directly to the Skill as you develop it. You can type the test user input into the command line and see the full response returned from the Skill. Read more

  2. Postman
    You can send a mock HTTP Request using Postman on your desktop. Using Postman allows you to configure more detailed request parameters than in the command line REPL. Read more

  3. DDNA Studio
    You can register a temporary Skill in DDNA Studio and link it to your local development environment. This approach requires you to create a public URL for your localhost environment, but also enables you to test your Skill with a live Digital Person. Read more

Command Line REPL​

We recommend initially testing your Skill locally using the REPLs provided with each template. This means testing and developing your Skill independent of a Digital Person or DDNA Studio. Instructions for using the REPLs are provided in the READMEs of each template repository.

The REPL is a command-line tool where you can type some "user input" as text, and preview the response from the Skill. This is the fastest way to develop a Skill where your focus is the input and output text of the Skill (i.e. what the user would say, and what the Digital Person would say back).

For more in-depth debugging and development, you may like to use a tool like Postman to send mock POST requests to your Skill endpoint and explore the response as JSON.

Postman​

For more detailed interactions, you may wish to send a mock HTTP POST request to your Skill. You can achieve this using the free Postman desktop app.

Configure Postman to send an ExecuteRequest JSON payload to the Skill, and you'll be able to configure additional properties of the request, such as the memory state or context data.

DDNA Studio​

To develop your Skill using a deployed Digital Person, you will need to make your Skill publicly accessible to DDNA Studio by using a tunneling service such as localtunnel to expose your localhost on a public URL.

1. Make sure your Skill is running locally​

Use the REPL or Postman to test that your Skill is able to receive a request and respond to it correctly over your localhost server.

2. Expose your local Skill on a public URL​

In order to test your Skill with a live Digital Person, you will need to expose your local development environment as a public URL, so that the Digital Person is able to access your locally running Skill.

This public URL must also be persistent, i.e. it can not change each time you start your development environment. This is because the URL must be provided as part of the Skill Definition, and it is laborious to modify the Skill definition frequently.

To obtain a persistent URL, you may need to continuously deploy your Skill to the cloud during development, or use a service such as localtunnel to expose your localhost to the Internet. The --subdomain flag can be used with localtunnel to request a specific URL for consistency.

Another popular service is ngrok, but note that the free version of ngrok does not provide a persistent URL, and you may need to upgrade to the paid plan.

A live Digital Person can not connect directly to your localhost address from the Internet, and configuring a Skill Definition to use a localhost address will not work.

3. Register the Skill in Studio using your development URL​

Note: Self-registering a Skill in DDNA Studio is not yet supported, but a Soul Machines customer success contact can arrange it for you.

Create a new Skill in DDNA Studio and upload your Skill Definition to it. Ensure that your Skill Definition is configured to use your public URL, for example the URL generated for you by ngrok.

4. Configure training phrases for your Skill​

Note: Configuration of training phrases for a Skill via DDNA Studio is not yet supported, but a Soul Machines customer success contact can arrange it for you.

Each Skill requires a set of training phrases to be defined, so that the platform can successfully match a user's request with the correct Skill. A training phrase is something the user may say that your Skill is designed to handle.

The process of defining training phrases is very similar to the concept of defining an "intent" in any NLP platform. The training phrases you provide are used to create an intent that will match with your Skill.

The Skill developer should take care to ensure that this set of training phrases (potential user inputs) associated with a Skill are carefully selected to uniquely and accurately represent the Skill in question. Intents must be able to easily differentiate between each Skill. Soul Machines will review your training phrases when we add them to our system, and will advise if we think they need to be adjusted for best performance.

5. Create a DDNA Studio Project that uses the Skill​

Create a new project or select an existing project and open the Edit form.

Use the Manage Conversation and Skills section of the form to find your Skill and add it to the project. See Connect Conversation and Add Skills for more information.

6. Launch the Project and talk to the Digital Person​

After deploying your changes, you can launch the Digital Person and test your Skill. You will need to speak one of the training phrases that has been associated with your Skill.

It is important to note that your Skill may not be triggered if your base conversation or another Skill has been configured to handle the same training phrase or intent.