OAA 2.3.2 Runtime Distribution Thank you for downloading the OAA 2.3.2 distribution package. Below you will find instructions for using the "runtime" part of the distribution; that is, for setting up and running the sample application system. Documentation and additional information about OAA can be found in the other README files and on the OAA homepage, at http://www.ai.sri.com/oaa. A (possibly) more up-to-date or more complete version of this file may be found here: http://www.ai.sri.com/oaa/distribution/v2.3/2.3.2/documentation.html#release Requirements ------------ In order to run the small demonstration system, you must have either a PC running Windows (98, NT, 2000, XP), a Sun computer (sparc family) running Solaris (2.6 or greater), an X86 machine running Linux, or a Macintosh running OS-X. You must also have an installation of Java, available from http://www.javasoft.com/. JDK 1.4 or later is strongly recommended, 1.2 is no longer supported, and there could be problems with using 1.3. Under Linux, some problems have been reported with using GNU java. These problems were solved by switching to Sun java. Contents -------- The runtime hierarchy contains what you need to run and monitor a small, precompiled OAA application. This runtime distribution contains: Agent Coordination Server: - An OAA Facilitator, the heart of an OAA system. Tools: - StartIt: an agent which simplifies launching the many agents making up a community (application system) - Monitor: An agent which helps graphically visualize an agent community and then log, monitor and profile interagent communication - Debug: An agent which enables a developer to send tasks or messages to the agent community or to an individual agent, expressed either in English or in the Interagent Communication Language (ICL) This agent is distributed in both Java and C. Sample Application: - DCG_NL: A simple natural language agent that accepts dynamic vocabulary and grammar rules - Small agent written in WebL for finding the weather forecast for thousands of cities from http://weather.com - Small agent written in WebL for creating a small employee database out of a web page The sample application allows simple natural language queries to the web such as: What is the weather in London for tomorrow? What is the weather in Boston, MA? Who is Adam Cheyer's manager? What is Adam Cheyer's phone number? etc. Note: In larger systems, the interpretation and execution of natural language queries is a distributed process -- as more agents connect, what the user can say and do expands dynamically, as each agent brings its own vocabulary. Installation Instructions ------------------------- Note: paths are given here using the PC-style \ for directories; on UNIX, replace \ with /. Also the .bat files on PC are (roughly) equivalent to the .sh files under UNIX. I. Decompress the distribution - On PCs, use winzip or equivalent. - On UNIX, decompress and untar the distribution file. II. Creating a setup file for the agents - Copy (and rename) doc\setup1.pl to the root directory, c:\setup.pl, under Windows, or if on UNIX, to setup.pl in your home directory. ==> Note that this is copy to a new name (setup.pl). Agents look for files named setup.pl. In the doc directory, we use the name setup1.pl to ensure that agents will not find that copy. Note: In the past it was necessary to run the facilitator before running StartIt. Now it is possible to invoke the facilitator from StartIt's GUI. The configuration file for the sample application is configured for this style of facilitator invocation. Before entering the next section, be sure that java is in your execution path (PATH environment variable). Running the Sample Application ------------------------------ Note: In order to use the StartIt agent (which is highly recommended) *with agents running remotely* (that is, on machines different than where StartIt is running), it is necessary to have both ssh and sshagent installed. However, to finish testing the sample agents, it is assumed that all agents are running on a single machine, so ssh and sshagent installation can be checked later. (Please refer to the StartIt documentation online for additional information regarding this: http://www.ai.sri.com/oaa/distribution/v2.3/doc/agents/startit/ 1. cd to runtime\scripts, and run startit.bat (or startit.sh). After a brief delay, you should see the StartIt GUI. 2. Start the Facilitator first, by clicking on the button labeled "Facilitator", then selecting "Start" from the drop-down menu. The light next to the button should turn green after a few seconds. Note: Under UNIX, if you shut down the Facilitator, then attempt to restart it on the same port, there is sometimes a delay before the same port is usable again. In this case, the StartIt button will remain yellow, and the output window will show that the Facilitator is unable to access the port. You must then kill the Facilitator, and either try again after a brief wait, or change to a different port number in the StartIt GUI. 2a. (optional) Select "Show Output Window" from the "View" menu of StartIt. In this output window, you can see the facilitator's output messages, as well as those of the other agents that will be started shortly. 3. Hit the big Start button to start all the other agents. The lights should become yellow, then green as the agents connect. Depending on the particular platform, it might take up to a minute or so for all of them to start. 4. You should now see 2 additional GUIs come up, for the Debug and Monitor agents. You can use the Monitor agent to graphically visualize the connected agents. Clicking on the "record" button will log interagent messages. The other 3 agents have no GUIs, but their output messages (if any) will be echoed into the StartIt output window. 5. Type a query. In the OAA Debug Interface, type in the English field Who is Adam Cheyer's boss? and click on the little square to the right. (If running the C version of the Debug Interface, however, you will need to press Return.) You should see an answer come back in the main log window. Data for the employee database comes from the html file: oaa2\runtime\webloaa\scripts\empldb.html Note: in some Java environments, the response to your initial query may show up only partially (that is, you'll see one line of response when there should be two). If this occurs, try repeating the input. Another sample question to try is: What is the phone number of Ray Perrault? Note: telephone numbers are not real ones... 6. Try some weather queries for some well-known cities (just about any in the world...) What is the weather in Boston, MA? The information comes live from http://weather.com so if the agents don't find an answer for your request, go to the page and see if it has information about the city you have mentioned. If the sample query above don't work, that indicates that weather.com has significantly changed their output format since the OAA release date, and the weather agent WebL script needs updating. Note: since the weather queries rely on a live Internet source, you must have an Internet connection, which is not obstructed by a firewall. NOTES regarding the Debug Interface: if you type in an English Request that isn't "understood" by the NL agent, you (unfortunately) get back no results (and no indication of what went wrong) in the Debug Interface. If you type an English request that IS understood, it will be translated into an ICL goal, and that goal will be sent to the facilitator to obtain solutions. Some goals may not be solvable by the set of demo agents. When a goal is not solvable, you'll see a "No solutions found" message in the Debug Interface. 7. When finished, kill all the agents by choosing the "Kill All and Exit" command (Kill menu) in StartIt. Running the Sample Application Using Shell Scripts -------------------------------------------------- As an alternative to using StartIt, invocation scripts are found in runtime\scripts. The ".sh" scripts are for use under UNIX, whereas the ".bat" scripts are for use under Windows. The same demo agents can be started individually using these scripts. When using these scripts, it is best to "cd" to the scripts directory before invoking them. You should always invoke the facilitator before invoking any other agents meant to connect to that facilitator. NOTE: In some cases, minor editing of these invocation scripts may be needed. For instance, under Linux, /usr/bin/csh, in the .sh scripts, may need changing to /bin/csh. Note: there's been a report that, under Windows XP, when using fac.bat, the facilitator is likely to crash when agents disconnect, BUT that this problem disappears when running fac.exe directly. It is recommended to try fac.bat first. Then, if there are problems, under XP, start the facilitator by running fac.exe (in the win32 subdirectory of runtime\facilitator). Configuring for multi-platform use ---------------------------------- The default setup file is configured for all agents running on a single machine; that is, it specifies the facilitator's host as 'localhost'. In order to run agents on several machines, all of which connect to a single facilitator, it is necessary to configure some or all of the setup file(s) to use a network-based hostname for the facilitator. ('localhost' won't work if the facilitator is on a different machine). The network-based hostname can be either a symbolic IP address (such as 'myhost.ai.sri.com'), or a numeric IP address (such as '216.239.37.99'). This configuration may be achieved simply by replacing 'localhost' with the symbolic or numeric IP address, keeping the single quotes at beginning and end. The allow_localhost assertion: allow_localhost(true). may be left in the setup file, even when using a network-based hostname. If you are unsure which hostname string will work, you can use the following procedure to determine it: 1. Edit the setup file (the one that the facilitator loads at startup), replacing the existing hostname with an underscore (this is also one way of writing an ICL variable); for example: default_facilitator(tcp(_, 3378)). 2. Run the Facilitator by executing runtime\scripts\fac.bat (or fac.sh). The Facilitator should connect, and print out your local hostname in a message: Loading setup file: 'C:/setup.pl' Listening at tcp(tree.ai.sri.com, 3378). Ready. 3. Carefully note the exact wording of your hostname (e.g. tree.ai.sri.com), and change the variable X in setup.pl to your hostname, ENCLOSED IN SINGLE QUOTES; for example: default_facilitator(tcp('tree.ai.sri.com', 3378)). Note: depending on the configuration of your machine, your host name may or may not be in this kind of dotted notation. Regardless, just use whatever the facilitator reports, and enclose it within single quotes. 4. Now return to the facilitator window, and kill it using Control-C. 5. As noted above, if you have setup files in other locations that will be used by agents connecting to this facilitator, they should also be updated as in step (3). Backwards compatibility for OAA1 agents --------------------------------------- The *Quintus-generated* OAA2 Facilitator is capable of serving a mixture of OAA2 and/or OAA1 agents. It has a backwards compatibility module which translates between messages in OAA1 format and those in OAA2 format. If you want to make use of this feature, it is necessary to specifically invoke fac_qp (under UNIX) or fac_qp.exe (under Windows). (The fac.bat and fac.sh scripts will invoke the Sicstus-generated facilitator.) However, it has not been tested in all possible combinations. For example, agents written with the OAA1 Perl library haven't been tried with the OAA2 Facilitator, and OAA1 SICSTUS agents haven't been tried very much with the OAA2 QUINTUS Facilitator. Please feel free to make use of backwards compatibility. If you uncover any situations in which it isn't working properly, we'd very much like to hear about it and will do our best to fix it quickly. Please send bug reports to oaa-bugs@ai.sri.com, or (better yet) subscribe to the oaa-users list (see below) and report your troubles there. If you run a mixture of OAA1 and OAA2 agents, you will need to have both of the following in your setup.pl file: rootdata(Port, Host). % for OAA1 agents default_facilitator(tcp(Host, Port)). % for OAA2 agents For example: rootdata(3344, 'xxx.ai.sri.com'). default_facilitator(tcp('xxx.ai.sri.com', 3344)). Known Issues ------------ - The use of 'localhost' as the host value in setup.pl doesn't always work (even if that's the value reported by the facilitator in Installation step 2 above). If it doesn't work, try using 'localdomain.localhost'. - Note: ssh is now the default connection protocol used by StartIt. But if you decide to specify rsh, be aware that rsh may be disabled for security reasons, which will prevent StartIt from invoking other agents (even when they are configured to run on the same machine as startit). In these cases, it will be necessary to adjust your xhost/rhost configuration. Things to try: (1) xhost +mymachine (2) If (1) doesn't help, create a personal .rhosts file in your home directory, including the line: mymachine mylogin (3) Under Linux, in particular, make sure that .rhosts is writable *only* by user (and not by group or other). If you prefer not to change your rsh/xhost configuration, you can bypass the use of StartIt altogether. Just run the each of the following scripts from the UNIX command line: nlg.sh debug_c.sh webloaa_empl.sh webloaa_weather.sh monitor.sh (optional) - Java agents, including StartIt, may run much slower under Unix than under Windows. - On the Macintosh, invoking an agent by clicking on its icon may not work correctly; that is, certain required dynamic libraries may not be found. - Under Windows, the "About" windows of the Debug and Monitor agents may appear briefly and then disappear as the main window gets raised above them. The "Help" windows sometimes will appear too small or will only be partly visible at the edge of the screen. - One user has reported the following exception from the Java library: java.security.AccessControlException: access denied (java.lang.RuntimePermission modifyThread) It occurs when a Java agent calls oaaSetupCommunication to connect to a facilitator. We don't fully understand why this occurs in some settings but not others. This problem can be addressed by adding the following lines to the effective java.policy file: grant { permission java.lang.RuntimePermission "modifyThread"; }; grant { permission java.lang.RuntimePermission "modifyThreadGroup"; }; Other Backwards Compatibility Issues ------------------------------------ - The 2.3.1 monitor agent will not work with the 2.3.2 (and beyond) facilitator, UNLESS the facilitator is run with the return_goal_with_solutions flag. Additional Information ---------------------- Additional information about OAA, including online documentation, is available on the OAA WebSite at http://www.ai.sri.com/oaa. Reporting Problems ------------------ To report any problems with this installation, please make use of the OAA Users mailing list. - To subscribe to or unsubscribe from the mailing list, please send mail to oaa-users-request@ai.sri.com, with either "subscribe" or "unsubscribe" in the Subject. You will receive an acknowledgement of your request. - To send mail to the list, send to oaa-users@ai.sri.com. - To browse the mail archives, visit the OAA OAA WebSite at http://www.ai.sri.com/oaa, and click on Contact & Community.