OAA 2.1.x Runtime Distribution Thank you for downloading the OAA 2.1 runtime package. Below you will find instructions for setting up your system and for running the sample application. Documentation and additional information about OAA can be found on the OAA homepage, at http://www.ai.sri.com/oaa. See also: README_PROLOG.txt. Requirements ------------ In order to run this demonstration package, you must have either a PC running Windows (95, NT, 98) or a Sun computer running SunOS or Solaris (or both). You must also install Java 2 (JDK 1.2.*), available from http://www.javasoft.com/ Note: JDK 1.3 can also be used, providing you obtain the required patched WebL.jar file (see below). Contents -------- This runtime distribution contains what you need to run and debug a small OAA application. Agent libraries are provided which enable you to create new agents in Java, Prolog and Compaq's Web Language, hereinafter abbreviated to WebL, its former name. Please follow instructions in the OAA tutorial and OAA Programmer's Guide for doing so. If you would like to see source code to the OAA libraries and tools, you may separately download the OAA Source Code distribution. This runtime distribution contains: Agent Coordination Server: - An OAA Facilitator, the heart of an OAA system. Tools: - Start-It: an agent which simplifies launching the many agents making up a community (application) - 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. 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 .bat files on PC are .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. Note: both the run-time distribution and the source distribution have "oaa2" as their top-level directories. (Run-time has oaa2/runtime and source has oaa2/src.) If you are installing both distributions, you may want to unpack them within the same "oaa2" directory, although this is not required. II. Defining host/port for your Facilitator Agent 1. Move oaa2\runtime\setup.pl to the root directory c:\ or if on UNIX, to your home directory. ==> Note, this is a MOVE, not a COPY. For proper installation, setup.pl should no longer be present in oaa2\runtime\ directory!!! 2. Run the Facilitator by executing \oaa2\runtime\fac.bat. 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), 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', 3378)). 4. Now all agents should be able to connect correctly. III. Download WebL 1. SRI does not have the right to distribute WebL. You will find a download page at the WebL homepage, http://www.compaq.com/WebL. 2. Copy the latest WebL jar file to oaa2\runtime\webloaa\WebL.jar IMPORTANT NOTE for users of Java 1.3: The WebL JAR file provided at the Compaq site needs to be patched for use with Java 1.3. Since the WebL site at Compaq no longer seems to be maintained, Adam Cheyer has generously posted the patched JAR file at: http://adam.cheyer.com/weblpatch.html TAKE CARE: With netscape 4.7, running under NT, when downloading using the (right-click) "Save Link as" command, this JAR file gets corrupted. If you get errors using this JAR file, you may need to download using Internet Explorer, or some other means. IV. Update startit properties for sample application (UNIX ONLY!) UNIX: You must edit the startit properties in oaa2/runtime/startit/configs/demo_unix.prop replace: //STARTIT_DISPLAY=myDisplay with: STARTIT_DISPLAY=yourhost Do not include "0.0" in yourhost. Running the Sample Application ------------------------------ NOTE: when invoking each of the scripts mentioned below (fac.bat or fac.sh, startit.bat or startit.sh, etc.), it is necessary to "cd" to the directory which holds the script before invoking it. 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. 1. Start the Facilitator (by running oaa2\runtime\fac.bat) 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. So under XP, start the facilitator by running fac.exe (in the win32 subdirectory of runtime). 2. Run oaa2\runtime\startit.bat. Note: you may find that StartIt, which is written in Java, runs much slower under Unix than under Windows. Its menus may also behave poorly (see below, Known Issues). Note: If you are running with Java 1.2.1 under Unix, you may get a "JIT" error message. This is due to a bug in the 1.2.1 Just In Time compiler. This can easily be corrected by editing oaa2/runtime/startit.sh, commenting the first definition of JITarg, and uncommenting the second. 3. Hit the big Start button to start all agents. The lights should become green as the agents connect. Note: under UNIX, it is sometimes necessary to adjust your xhost configuration, before startit is able to launch the agents. See Known Issues, below. 4. Some java agents (including Start-It!) may not autoconnect. Use the File|Connect menu to connect each agents to the Facilitator until all lights become green in Start-It. 5. 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 shell in which StartIt was invoked. Note that each agent may be started separately by running the script (.bat or .sh file), or by using Start-It. 6. 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 press Return. (If running the Java version of the Debug Interface, however, you will need to click on the little square, instead of typing 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: telephone numbers are not real ones... 7. Try some weather queries for your favorite 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 these queries rely on live Internet sources, you must have a network connection and no firewall. Queries in step 6 can be done on a local computer. 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. 8. When finished, kill all the agents by choosing the Kill All menu option in Start-It. Under Windows, it's normal that Start-It won't be able to kill some of the Java agents, as the Kill Process command in Java won't kill a process started in DOS window (like the batch files used to start these agents). 9. When all agents have disconnected, including Start-It, you can kill the Facilitator Agent. On PC, ctrl-C doesn't work, so just close the window and accept the complaining message. Backwards compatibility for OAA1 agents --------------------------------------- The 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. 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 new Java2 version of Swing libraries creates some "interesting" refresh effects with drawing icons in the Monitor agent. - Note: under UNIX, it is sometimes necessary to adjust your xhost configuration, before startit is able to launch the agents (even when they are configured to run on the same machine as startit). This is due to the way that startit uses rsh. Two 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). - Java agents, including Start-It, may run much slower under Unix than under Windows. - Under Unix, some menus in Start-It 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 Start-It is to Exit from Start-It, and then click OK when prompted. 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.