Virtual Agent Lab with Watson

I recently put together a lab to help developers understand how to integrate the Natural Language Classifier, Retrieve and Rank, and Dialog services to build a virtual agent for support desk. We typically complete this lab (among others) during Architecture Workshops which are a formal offering of the Watson Ecosystem so the instructions are a little less explicit then you might expect, but no reason developers could not complete the lab independently if you work with the WDC documentation and API reference. The code can be found on github.


Virtual Agent is a self-service engagement application that helps a user access support information and troubleshoot issues in a self-service fashion. It follows an interaction between an end user and a virtual agent for a fictional company called Gemstone Medical. For a list of the interactions that are included check out

This lab uses the Dialog, Natural Language Classifier, and Retrieve and Rank services. It was designed to be completed during the Ecosystem Architecture Workshop. For additional sample apps check out the Watson Application Starter Kits

Let’s get started.

Creating an IBM Bluemix Account

  1. Go to
  2. Create a Bluemix account if required.
  3. Log in with your IBM ID (the ID used to create your Bluemix account)

Note: The confirmation email from Bluemix mail take up to 1 hour.

Create Watson services

  1. Create the Dialog, Natural Language Classifier, and Retrieve and Rank services in Bluemix.
  2. Capture the name and credentials for each service.
Fig. 1 Capture your service credentials

Configure and test the dialog service

Note: Steps 1–5 are optional. They show you how to set up and use the separate dialog test tool.

  1. Test the sample dialog flow by deploying the Dialog Tool. While the dialog tool is not required to build this application, it will help you manage and test your dialog flows going forward.
  2. Follow the instructions in the Dialog Tool README to bind your dialog service to the dialog tool.
  3. Upload the gem_dialog.xml flow file through the dialog tool UI.
  4. Experiment with “Have a Conversation” to see how the dialog flow works in practice.
  5. Note: The Natural Language Classifier is not implemented in the dialog tool so the flow will not work as an end-user would expect. However you can observe the machine to machine interaction that will exist between the dialog service and application.
  6. Unbind your Dialog Service from the dialog tool application and bind it to your Virtual Agent application.
  7. Create a new dialog flow by calling the create dialog API endpoint with the gem_dialog.xml flow file. Create Dialog API Reference
  8. Capture the Dialog ID.

Train and test the Natural Language Classifier service

  1. Create a new classifier instance with the gem_training_questions.csv training file. Create Classifier API Reference
  2. Capture the Classifier ID.

Configure, train and test the Retrieve and Rank service

  1. Create a Solr cluster and capture Cluster ID. Create Cluster API Reference
  2. Review the contents of the gem_solr_config directory. Review schema.xml and notice the fields that are defined. When the cluster is READY, upload the solr config to your solr cluster. Upload Config API Reference
Fig. 2 schema.xml
  1. Create collection. Create Collection API Reference
  2. Review the sample solr documents in fda_medwatch_docs.json. Notice how each document contains the fields that are defined in the schema.xml. Notice how the structure of the json file follows standard Solr API construction for adding and committing documents. Index the documents. Index Documents API Reference
Fig. 3 collection json
  1. Create and train ranker. TBD. Create Ranker API Reference

Deploy application

  1. Download the application zip file from this git repository.
  2. Ensure that you have the Cloud Foundry CLI installed.
  3. Modify the manifest.yml file to include a unique application name and the name of the services you created
Fig. 4 manifest.yml
  1. Log in to Bluemix cf login
  2. From the app root directory, push app to Bluemix. This will copy all files to Bluemix and bind your services to the application. cf push
  3. Go to Environment Variables in Bluemix and create 3 user-defined environment variables: DIALOG_ID, CLASSIFIER_ID and SOLR_CLUSTER_ID. Input the IDs that you captured when configuring these services.
Fig. 5 Set environment variables in Bluemix
  1. Because you have defined environment variables, you do not need to hardcode credentials or IDs in the application code itself, however you should take note of where this can be done.
  2. Walk the application code, specifically,,, and Start with the initial GET request in the Flask server code and follow each function call.
Fig. 6 Flask server code

Modify the dialog xml and classifier to create a new troubleshooting flow

  1. There are 3 simple dialog flows within the Live Content folder in the dialog xml: Product_Info, Troubleshooting and Issue_lookup. Create a new folder in the dialog xml called Troubleshooting_2.
  2. Write out a new dialog flow to represent a new issue that an end user might need to troubleshoot.
  3. Add that flow to your dialog xml. Update your dialog service with your new dialog xml and update your DIALOG_ID in Environment Variables.
  4. Add a new class to your NLC training data to represent the user intent that enters this new flow and train your classifier. Update the CLASSIFIER_ID in Environment Variables.


Once your application is deployed, follow the script in Test your new dialog flow.

Fig. 7 Virtual agent interface


You have completed the Virtual Agent Lab! You are now ready to build your own virtual agent application powered by Watson

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.