CART - Conversational Agent Research Toolkit Documentation Release 1.00 (Anonymized) May 06, 2021 Contents 1 Guide 1 1.1 About CART...............................................1 1.2 Installation................................................2 1.3 Using CART...............................................5 1.4 Modules................................................. 14 1.5 Tutorial.................................................. 14 1.6 License.................................................. 17 2 Indices and tables 19 i ii CHAPTER 1 Guide 1.1 About CART 1.1.1 Objectives The Conversational Agent Research Toolkit (CART) aims at enabling researchers to create conversational agents for experimental studies using computational methods. CART provides a unifying toolkit written in Python that integrates existing services and APIs for dialogue management, natural language understanding & generation, and frameworks that enable publishing the conversational agents as either a web interface or within messaging apps. Specifically developed for communication research, CART not only acts as an integration layer across these different services, but also aims to provides a configurable solution meeting the requirements of academic research. 1.1.2 Components CART acts as an integration layer between several services so it can generate a conversational agent that can interact with participants of an experiment, log the conversations, design experiments, and connect with questionnaires for self-reported measures. To do so, CART works with the following components: Dialogue Management CART currently uses DialogFlow as the primary tool to handle dialogue managemnt. This means that all the participant input, and the responses that the agent gives, are primarily setup in DialogFlow. Using specific tokens (see below), the researcher can customise the responses that the agent provides depending on the condition that the participant is in. Agent Publication CART currently uses the Microsoft Azure Bot Channel Registration to publish the conversational agent. Within CART, the Bot Framework is responsible for creating a webchat for users to chat with the agent. This webchat can be embedded in online surveys. The Bot Framework also allows the agent to be published in other channels (e.g., Skype, Telegram, Facebook Messenger) without needing to change the code within CART. 1 CART - Conversational Agent Research Toolkit Documentation, Release 1.00 Conversation Logging One of the key aspects of CART is the ability to log the conversations that participants in an experiment have with the agent. To do so, CART connects to a database under the control of the researcher. Experiment Design CART allows the researcher to create experiments in which the same agent acts in different ways depending on the condition that the participant is in. To do so, the researcher simply needs to add specific tokens in the Dialogue Management tool, and setup different conditions within CART itself. Online Questionnaire Integration After an agent is created and published, the researcher can integrate it to the flow of an online questionnaire (e.g., Qualtrics, SurveyMonkey). By turning on the questionnaire flow, the agent requests a unique ID from the participant, and returns a unique conversation code at the end of the conversation, so the researcher can link the conversation logs in the CART database with the responses in the online questionnaire. 1.2 Installation 1.2.1 Requirements Services and APIs CART acts as an integration layer between different services (and APIs), and specific configurations within CART itself. To use it, you will need: 1. Access to a SQL database 2. Access to a web service to publish CART (using Python 3.X) 3. An account with DialogFlow 4. An account with the Microsoft Bot Framework 5. A copy of the CART code Optionally, you also would need access to an online questionnaire tool (e.g., Qualtrics, SurveyMonkey) if you are integrating CART into a survey flow. Note: For #1 and #2, you can use your own server (if available), or AWS RDS (database) and Heroku (web service) as demonstrated in the Installation and Setup Guide. Python Packages CART uses a set of Python packages (e.g., PyMySQL, microsoftbotframework, google-cloud-dialogflow etc.). By downloading CART and running the step-by-step instructions in the installation guide (below), all the necessary pack- ages will be installed on the server. 2 Chapter 1. Guide CART - Conversational Agent Research Toolkit Documentation, Release 1.00 1.2.2 Installation and Setup Guide Important note: these steps show how to install and setup an agent using AWS RDS (as a database server) and Heroku (as a web service) along with DialogFlow and the MS Bot Framework. Advanced users can replace AWS RDS and Heroku by their own servers. Step 1. Download CART to your computer 1. Access [ANONYMIZED LINK OF THE GITHUB REPOSITORY] and select clone or download and download CART as a zip file. 2. Extract the zip file in a folder you want to store the agent Step 2. Rename the config.yaml file The config.yaml file, located at the folder cart, will contain all the basic configurations needed to connect to the services (MS Bot Framework and the SQL database), including usernames and passwords. Never make it publicly available. To create it, you need to: 1. Copy (or rename) the file called config_example.yaml to config.yaml 2. In the steps 3, 4 and 6 (below), you will need to update this file with information coming from each service. Step 3. Create an agent in DialogFlow 1. Log in to DialogFlow and select Create Agent. For CART, all tests have been done with the ES (simpler) version. 2. Follow the instructions from DialogFlow to enable the API, create a service account, and download the service key account file in JSON format. You will use it on step 5, as part of the web service configuration. Step 4. Create a database for logging CART requires the the URL (host) of a MySQL database, database name, and username and password to connect to and log the conversations between the agent and participants. The username provided needs to have all privileges (including CREATE) in the database. This information needs to be made included in the config.yaml file. If using AWS RDS, the following steps need to be followed: 1. Log into your AWS account and select RDS 2. Create a database using MySQL, and make sure to include the username and the password also in the config.yaml file 3. When asked for the database name, make sure to inform it, and also include it in the config.yaml file. 4. Select the endpoint of the database (check the dabatase details page), and paste it in the database_url field of config.yaml. 5. After the database is launched, make sure to check the security group (see database details), and open the inbound port to the server that you will be using. Notes: 1.2. Installation 3 CART - Conversational Agent Research Toolkit Documentation, Release 1.00 • Usually a micro or small instance in AWS is sufficient for testing purposes, and can later be upgraded to medium/large when the agent is live and handling several conversations at the same time (e.g., during an experiment) • For security reasons, it is recommended not to allow any IP to connect to your database. When using Heroku, see this list of plugins that can create a static IP for your app. • When running the agent in the server for the first time, it will automatically create two tables in the database: – logs, which records every interaction between the agent and the participant – conversations, which records each individual conversation (i.e., in general, each participant = one conversation) that is started with the agent. Step 5. Publish the agent as a web service After completing the steps above, it is time to publish the agent as a web service. This can be done using Heroku (as demonstrated below) or in any other server that supports Python and Flask applications. It is important to note that the server should also be able to serve pages in https. If using Heroku: 1. Log into your Heroku account and create a new app 2. Set the environment variables (called in Heroku “config vars”) for DialogFlow. See note 2, below, for details. 3. Select the deployment method 4. Deploy the app 5. After the build has been completed, select open app 6. Copy the URL of the app (it should start with the app-name, and end with herokuapp.com) to use in the next step Note 1: the URL of the app is needed so it can be registered in the MS Bot Framework (next step). The registration in the MS Bot Framework will also provide authentication credentials. These credentials will need to be added to the config.yaml file, and the agent will need to be published again in Heroku (as outlined in the next step). Note 2: Open the service account file downloaded on step 3(above) locally in a text editor, remove all line breaks, and substitute the double quotes (”) by single quotes (‘). In the web service, add this as an environment variable called DF_CREDENTIALS. Create another environment variable called DF_LANGUAGE_CODE and set its value to the appropriate language (e.g., en). Step 6. Connect the agent to the MS Bot Framework After a URL for the agent as a web service is available (e.g., for Heroku: https://NAMEOFTHEAPP. herokuapp.com/), the agent can be registered in the MS Bot Framework. To do so: 1. Log in your Microsoft Bot Framework account, selecting My Bots 2. Select create a bot. You will be redirected to Azure Bot Service 3. Select Bot Channels Registration 4. Provide the information required 5. The messaging endpoint will be the URL of the Heroku app + api/messages - example: https:// NAMEOFTHEAPP.herokuapp.com//api/messages 4 Chapter 1. Guide CART - Conversational Agent Research Toolkit Documentation, Release 1.00 6.