Part 1: Introduction

Thank you for your interest in IAGO: Interactive Arbitration Guide Online.

IAGO is a platform and programming API designed to assist you in creating virtual agents that can negotiate with humans over the web.

IAGO is part of an ongoing effort to design agents that use human-like tactics in negotiation, and can eventually be used to teach negotiation skills in a simple and interactive way.

IAGO is a web-based program, and runs in a browser window on most modern browsers, including Google Chrome, Opera, and Internet Explorer and Edge. We do not recommend Firefox.

No installation is necessary to play against an IAGO agent, and negotiations are intended to be intuitive and fun.

For researchers, IAGO represents a tool for running real-world studies where participants, recruited through systems like Qualtrics or Amazon's Mechanical Turk, can be matched against agents designed by you.

Agent development is easy, and requires only basic understanding of the Java programming language to get started.

This tutorial is intended to familiarize you with the first steps in downloading the IAGO framework and building your first agent.

When you are ready, please continue to Part 2: Download

Part 2: Download

The IAGO zip file for developers can be downloaded by submitting a request via the main IAGO page. Alternatively, you may skip straight to development by downloading the IAGO VM, which runs Ubuntu Linux with a fully-configured IAGO already. If you do choose to build IAGO yourself, read onwards. Once you have downloaded and saved the zip file, please extract its contents to a new folder on your hard drive. This will be your development folder.

Inside the IAGO zip file, you will find two folders. The first folder, labeled "src", contains the source files that will help you get started using IAGO. These include two sample agents that can be used out of the box with IAGO, as well as some view files that allow you to customize the game features that define the interaction between your players.

The second folder is the WebContent folder, and contains the resources that will be deployed onto your web server when starting IAGO. Most of this folder will not need to be modified,
but you may choose to do so in order to create custom art for IAGO, or to update the IAGO core files should they become out of date.

Finally, you will find three files in the IAGO zip file. The first, "build.xml", contains an Ant build script for creating your IAGO deployment using the command line. If you do not have Ant
installed, please install it by referring to the appropriate tutorial. We do not recommend you use Ant to build from the command, as it requires additional configuration to include all relevant libraries and config files (many systems may fail to include the config.txt file located in the src directory without additional customization). Instead, we recommend using Eclipse to directly deploy IAGO.

The other two files are necessary for configuring IAGO_Core to run natively on Tomcat, and are not needed here.

Finally, via separate download link, you will also receive IAGO_Core.jar. Simply place IAGO_Core.jar inside your

We will now discuss the requirements for third party software for programming and deploying IAGO. Continue on to Part 3: Installation Prerequisites.

Part 3: Installation Prerequisites

Java

IAGO is a Java API, so you will need to download and install a Java Software Development Kit, or JDK. Oracle provides a detailed guide for installing Java on your computer, which can be found at the link provided in this tutorial description.

https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html

Please note that you may already have Java installed. The easiest way to determine this is to open up a command prompt or terminal and type in the following command:

java -version

If successful, the command should print out the version number of Java. If the command is not recognized, eithe rthe PATH variable for JAVA_HOME is not set, or Java is not installed at all. IAGO supports both Java 7 or Java 8. Please note that the JDK is required, not just the JRE. If you are confused about how to do this, refer to the tutorial on Java.

Ant

If you intend to build IAGO by hand, you may also require Apache Ant. Ant is a program that reads instructions on how to compile projects and automates this process for you. If you do not intend to manually build IAGO (by letting Eclipse do it), you do not need Ant.

Ant comes by default on some versions of Mac OS X. To test this, you can simply type the command:

ant -version

An Ant installation tutorial is provided by Apache. The link is available here.

http://ant.apache.org/manual/install.html

However, Ant can be easily be installed on OS X using the Homebrew command:

brew install ant

Please note that you should install Java prior to installing Ant.

Eclipse

We recommend using the Eclipse Interactive Development Environment to develop your IAGO agent. This simplifies the build and deployment process to a web server considerably. However, all of these steps are possible manually if you do prefer a different IDE.

As of this writing, the current version of Eclipse is Eclipse Oxygen. Eclipse can be downloaded from the link below.

https://www.eclipse.org/downloads/eclipse-packages/

We recommend you download the Java EE package, although any installation will work if all additional packages are downloaded.

Once you have installed Eclipse, you will need to select a workspace. The workspace is the location on the file system where files will be stored during development. Choose an empty folder, as you will be importing IAGO into this folder shortly.

When opening Eclipse for the first time, it will ask you where you want to place the workspace (this can be changed later).

Tomcat

In order to run IAGO, the best way is to host it on a web server, such as Apache Tomcat. We recommend Tomcat 7 or 8, which can be found here:

https://tomcat.apache.org/download-70.cgi

Tomcat offers a simple, downloadable installer for Windows systems. Once Tomcat is installed, it will register as a Windows service which can be enabled or disabled from the Services menu (Start --> Search --> "Services"). Additionally, Eclipse provides support for automated launching of Tomcat servers, once configured properly.

Part 4: Creating an Eclipse Project

With all the prerequisites complete, you can create a new Eclipse Project. First, we need to create the Tomcat server. Begin by opening the Server Perspective in Eclipse. Click the link to create a new server. Select Tomcat 7 or Tomcat 8 (under Apache), depending on which version you downloaded previously. You will need to select the Tomcat folder (containing bin). If you downloaded Tomcat through Eclipse automatically previously, you will not need to complete this step.

Next, you will need to create a project by right clicking in the Project Explorer. Enter New-->New Project. Open the Web Folder, and select "Dynamic Web Project". Eclipse may ask for a server on which to configure the project. If so, select the server you made previously. If not, you will need to double-click the server in the Server View, click the Modules tab, and then Add Module (select your project).

Your project is configured, but it contains no files yet! Simply copy the src and WebContent directories in your IAGO download into the new project within the file system and refresh eclipse (default: F5). Don't forget to ALSO copy IAGO_Core.jar into WEB-INF/lib!

Now, simply click the green arrow on the Server View to start the server. It may take 30 seconds or more the first time it starts, although it can be kept running (saving files in IAGO will redeploy them automatically).

Now, you should be able to pull up IAGO in a web browser using the following URL:

http://localhost:8080/IAGO/start

If you see a page with content and not a 404: Not Found page, you have successfully installed IAGO.

Once you can access IAGO using your web browser, try playing it. The splash page for IAGO provides a sample tutorial for the game. You may also open up developer tools in most modern browsers to view JS console messages and to assist with debugging.

Note that Tomcat does by default use port 8080 as opposed to the standard HTTP port of 80. Therefore, you must include the port information in the URL unless you change Tomcat's configuration in conf/server.xml.

You may further edit the configuration of Tomcat to your liking. For example, you may change the path at which IAGO is accesssed by adding a Context element. The recommended way to do this is to add a ROOT.xml file to the localhost directory in Tomcat, although you may instead edit server.xml directly.

You should now be able to develop for IAGO within Eclipse, which will allow for real-time debugging, visible console messages, and automatic deployment.

We do recommend that you view IAGO through a full web browser (Eclipse may try to use its "built-in" browser).

WARNING: You may find that the server fails to start because "another instance is running".  This may be due to the fact that the Windows service for Tomcat is still running on port 8080!  To solve this problem, either shut down the Windows service for Tomcat before launching in Eclipse, OR edit either Eclipse's server.xml or Tomcat's main server.xml to run on a different port (we use 8085).  Then, you may have BOTH the Windows Tomcat and the Eclipse Tomcat instance running simultaneously.

Part 5: A Brief Tour of IAGO's Code

You are now ready to design your own agent.  If you are interested in configuring the game itself, including the number of issues, the points awarded, and other structural items, please refer to the documentation for the GameSpec interface.  Several samples class implementing this interface, such as ResourceGameSpec, have been provided for you.

GameBridge contains the mechanics for hosting IAGO as a web app, and will not require modification.

IAGO comes with two sample agents for testing.  The DefaultAgent is a skeleton for your code, but the PinocchioAgent has more advanced behaviors, including preference estimation and fair exchange.  For a detailed description of that agent, please refer to the paper reference at AAMAS 2017, found at:

http://people.ict.usc.edu/~mell/publications/iago_4agent.pdf

Part 6: Troubleshooting

Information will be added here as available.

Configuring Tomcat within Eclipse on Linux:

You may find that Tomcat will not start on Linux even once configured to point at /usr/share/TomcatX. This is due to the fact that Linux separates Tomcat files to several other directories, including ones within /etc. You may solve this problem by symlinking log, config, and catalina.properties to /usr/share/TomcatX/log, config, and config/catalina.properties, respectively.