OAA 2.3.0 Runtime Distribution Thank you for downloading the OAA 2.3.0 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. 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.* is strongly recommended, 1.2.* is no longer supported, and there could be problems with using 1.3.*.) Contents -------- This runtime distribution contains what you need to run and monitor a small OAA application. Agent libraries are provided which enable you to create new agents in Java, C, Prolog and Compaq's Web Language, hereinafter abbreviated to WebL, its former name. Please follow instructions in the OAA tutorial and the OAA Developer's Guide and language reference documents (all available online) for doing so. 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.yahoo.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? Who is Adam Cheyer's manager? etc. In larger systems, the interpretation and execution of the natural language query 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 pkunzip. Make sure you keep the directory structure intact. - On UNIX, decompress and untar the distribution file. II. Defining host/port for your Facilitator Agent 1. 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. 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 "ChangeMe" in setup.pl to your hostname, ENCLOSED IN SINGLE QUOTES. %% OLD: default_facilitator(tcp(ChangeMe_SeeAbove, 3378)). 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. 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. 5. 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 newly reworked 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? What is the phone number of Ray Perrault? 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. 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? What is London's weather on Tuesday? The information comes live from http://weather.yahoo.com so if the agents don't find an answer for your request, go to the page and see if there is an answer there. 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 menu option in StartIt. 8. When all agents have disconnected, including StartIt, you can kill the Facilitator Agent. On PC, ctrl-C doesn't work, so just close the window and accept the complaining message. 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). 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 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 fix it quickly. Please send bug reports to oaa-bugs@ai.sri.com. 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. - Under Unix, some menus in StartIt and in the Monitor agent don't work reliably. In particular, the Kill All command and individual kill commands for Java agents have problems. The surest way to kill all the agents from StartIt is to Exit from StartIt, and then click OK when prompted. - 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 will 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.. 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.