Buyer-Seller Example Agency Readme

README.html

What is the Buyer Seller Agency?

A high level description is included locally in doc/buyerSeller.html or remotely at www.agentBuilder.com/Docmentation/appnote/buyerSeller.html.

A few caveats:

This is an example for registered users of AgentBuilder. If you do not have the AgentBuilder tookit, you will not be able to run the agents. You need the runtime system in order to execute the provided agents. If you are looking for more information about AgentBuilder see http://www.reticular.com/AgentBuilder/usermanual.html .

The agents in the Buyer-Seller agency use KQML to communicate, but do not adhere to the strict semantics as proposed by Yannis Labrou and Tim Finin in A Proposal for a new KQML Specification. A more rigorous example of the Buyer-Seller agency is to be released soon. It follows the semantics more rigorously and utilizes a facilitator agent.

What's In This Distribution?

This distribution contains three subdirectories which include the source code, the tool repository and the high level description.

src - This directory contains the source code for used PACs, the Makefile, the class files, the javadoc documentation for the .java files and the RADL files for each agent. PACs or Project Accessory Classes, are specific classes built for use by the agents. RADL or Reticular Agent Definition files contain a complete semantic description of an agent. The javadoc html files for the .java files can be found in src/javadoc/tree.html

doc - This directory contains the high level description in html format. This description is the same as the application note found on the AgentBuilder web site.

repository - This directory contains the data repository for the tool. In order to use it, the user's repository directory must be changed. Use the preferences dialog, found in the tool, to change repositories.

There is also a JNI (e.g., Java Native Interface) example included in this distribution. The agents found in the tool do NOT use this, nor do the RADL files found in the src directory (except for the store2-jni.radl). Read the README.jni, found in the src directory, to configure the store2 agent to use jni.

How Do I Run the Buyer-Seller Agency?

After downloading the BuyerSeller repository, you will need to import it into AgentBuilder toolkit. Start AgentBuilder, then in the Project Manager select the Edit -> Preferences... menu item and choose the Directories tab. Select the Repository row and click on the Browse... button. This will bring up the Directory Dialog. Find the directory where you downloaded the Buyer-Seller, select the repository subdirectory in the dialog and click on OK.

There are two separate ways to run the Buyer-Seller agents. The first is running all of the agents directly from the tool. The user may load and run the agents one at a time, the order isn't important. To do this select the Agent Manager from the Tools menu, open the Store 1 agent and select Options -> Run Agent. This will bring up Agent Engine Options dialog. You will need to include the BuyerSeller.jar file in the classpath. You will need to append :BuyerSeller.jar to the classpath and click on the Enter button. The BuyerSeller.jar file is included in this distribution in the src directory. Once you have done this, click on the OK button to start running the agent. You will need to follow the same steps to run Store 2 and the Buyer agent.

The second is to run the agents directly on the runtime system. To do this, the user must start the runtime system (on UNIX use the engine script, on MS Windows use the "AgentBuilder Engine" menu item found through the Start menu) to load the RADL files. The "buyer.radl", "store1.radl" and "store2.radl" files are in the src directory.

When you have the three agents running, you can select an item using the Buyer agent's interface and then click on Shop. Now, just sit back and watch the agent do your shopping for you!

How Do I Run the Buyer-Seller Agents on different machines?

By default all of the agents use CURRENT_IP_ADDRESS as their IP address. This means that they use the address of the local machine they are being executed upon. This makes it easy to move them from machine to machine. This is a problem if the agents are distributed over the internet on various machines. Then, for correct operation, each agent must have a specific IP address assignmented to them. This can be done by either editing the .radl files or changing the communication parameters in the agent manager.

You can alter the agent defintion by either editing the previously generated RADL file, or changing the agent configuration in the toolkit and regenerating the RADL file. To do this select the Agent Manager from the Tools menu, open the Store 1 agent and select Edit -> Properties. This will bring up Agent Properties dialog. Click on the Communications button. The Communications dialog should pop up. Then the IPAddress field may be edited. This will need to be done for each agent. To run the agents simply run them as described in the previous section.

The rest of the section describes how to manually edit the RADL files and run the agents from the RunTime system.

Manually Editing the Agent Definition File

In this simple agency of a buyer and two sellers the addresses of each agent is hardcoded into all three RADL files, and each agent must be executed on the same machine named. The CURRENT_IP_ADDRESS allows the agent to use the IPAddress of whatever machine it is run upon. Thus, for all agents to interact correctly, they must all be on the CURRENT_IP_ADDRESS.

Here, for example, is the buyer.radl initial agency beliefs section:

========================================================================
INITIAL AGENCY BELIEFS


( SELF "Buyer"  [CURRENT_IP_ADDRESS] [RMI:1300] [] [  "BuyerSeller Agency" ]  ) 
( AGENCY_TOOL "AgencyTool"  [CURRENT_IP_ADDRESS] [RMI:2000] [] [  "BuyerSeller Agency" ]  )

REMOTE_AGENTS
( "Store 1"  [CURRENT_IP_ADDRESS] [RMI:1301] [] [  "BuyerSeller Agency" ]  )
( "Store 2"  [CURRENT_IP_ADDRESS] [RMI:1302] [] [  "BuyerSeller Agency" ]  )

The IP address of the buyer agent is CURRENT_IP_ADDRESS , and the IP address of both store agents is CURRENT_IP_ADDRESS. The user should change the CURRENT_IP_ADDRESS string to be "sherman.reticular.com" or whatever machine.domain name is correct. The initial agency beliefs sections in store1.radl and store2.radl must agree with this initial agency beliefs section, although the ordering will be different because each will have a different SELF belief.

Running the agents from the Runtime System

For successful execution each program must be executed on the machine with the IP address named in its initial agency beliefs section. The following steps specify how to run the Buyer-Seller example with the runtime engine for UNIX:

Edit the RADL files so that the agency beliefs are consistent and match the machine(s) on which the programs will run. The IP address can be the machine name or number (e.g., quincy.reticular.com or 199.106.0.6). If they are all run on the same machine the files do NOT need to be edited.
Each agent has a graphical display, so the DISPLAY variable will need to be set for any agent running on a remote machine, and the host machine must allow access by the client machine.
In an xterm on the expected machine for the buyer agent type:
engine buyer.radl -no-console
In an xterm on the expected machine for the store1 agent type:
engine store1.radl -no-console
In an xterm on the expected machine for the store2 agent type:
engine store2.radl -no-console

Type 'engine -h' to see a list of possible options. The -no-console is recommended because each agent has its own interface, but it's not mandatory.

To run the Buyer-Seller example in a distributed manner with Windows requires a similar strategy. The only difference being that the user should start the engine from the Start menu.

Tech Support

Last modified: Tue Sep 22 10:49:17 PDT 1998