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
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. The same form will provide links to both options. We highly recommend that unless you are comfortable configuring your own system, that you download VirtualBox (or similar).
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.
We will now discuss the requirements for third party software for programming and deploying IAGO. Continue on to Part 3: Installation Prerequisites.
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.
hhttps://docs.oracle.com/en/java/javase/11/install/overview-jdk-installation.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 Java 11 (the latest Long-Term Release) but likely functions as far back as Java 7. 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.
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 2021-03. Eclipse can be downloaded from the link below.
https://www.eclipse.org/downloads/eclipse-packages/
We recommend you download the Java EE package/Eclipse IDE for Enterprise Java and Web Developers, 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).
In order to run IAGO, the best way is to host it on a web server, such as Apache Tomcat. We recommend Tomcat 8.5, which can be found here:
https://tomcat.apache.org/download-80.cgi
Newer versions (e.g., Tomcat 10) may work, but are not formally supported at this time. 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.
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 8.5/8 (under Apache), depending on which version you downloaded previously. You will need to select the Tomcat folder (containing the folder called "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, if it is not present.
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:
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.
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 IAGOTemplateVH is a skeleton for your code, but the IAGOJiminyAgent has more advanced behaviors, including preference estimation and fair exchange. For a detailed description of an agent, please refer to the paper reference at AAMAS 2017, found here.
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.
Discrepencies between this document and the readme:
The readme.txt file included with IAGO_Game_Edition is almost always more up to date than this document. In times of conflict, defer to it.
.