Multi-Agent Demo Guide
======================

This demo is an example of a very simple multi-agent system where
independent agents running on different machines can cooperate to
solve problems.  It is written mostly in Logic & Objects and uses
mailboxes for communication.  Logic & Objects files have the a
'.lo' suffix.



Background
==========

The demo is in the domain of arithmetic.  Each of three agents
have knowledge about different operations in arithmetic.  For
example, agent a1 knows how to add and subtract, and agent a2
know how to multiply and divide.  When agent a2 is asked to
solve an addition, it needs to request help from agent a1.
This is done without specific user intervention provided a2
has a way of finding out what other agents are capable of
performing addition.  In a complex problem such as finding
the hypotenuse of a right-angled triangle given the other
two sides, this may involve a lot of behind-the-scenes
communciation.

To demonstrate that a user may become an active agent in the
system, we have included code to allow a user to stand in
for agent a2.



Setting Up the Demo
===================

A) Start four shells preferably running on different machines
   (but displaying on the same screen).  In three of the shells,
   cd to this directory (examples/arithmetic).

B) In the fourth shell, start a mailbox server program by

	mbx_server mbx1

   You should see the message

	Server [mbx1] started on machine NAME

   where NAME is the name of the machine on which it is running.

   If you get the message 'error: service mbx1 not found', then
   the mailbox services have not been installed correctly.
   Please refer to section D of the INSTALLATION guide.

   If you get the message 'error: server is already running or
   socket is in use', then the server is probably already
   running and you may continue.



Running the Demo
================

1) In shell 1, start agent a1 like so :

	icp -n -z 'load(agent),init_agent(a1)'

   You should see the prompt :

	Name of machine running mailbox server ? 

   at which point you should enter the name of the machine
   running the mailbox server program i.e. NAME in step B above
   and terminate with '.' and <RETURN>.  You should see the
   confirmation message:

	initialised agent : a1 

2) In shell 2, start agent a2 like so :

        icp -n -z 'load(agent),init_agent(a2)'

   Follow the same procedure as step 3 to initialise agent a2.

3) In shell 3, start agent a3 in the same manner.

	icp -n -z 'load(agent),init_agent(a3)'

4) Now that all three agents have been initialised, you can ask
   any of the agents to solve arithmetic problems.  e.g. in the
   window of agent a2, type

	solve(hypotenuse(3,4,H)).

   This will cause a sequence of messages to be sent among the
   three agents before a solution is obtained.  The messages are
   traced on the display.  The problems are of the form

	solve(Goal)

   where Goal is one of :

	a) add(X,Y,Answer)
	b) subtract(X,Y,Answer)
	c) multiply(X,Y,Answer)
	d) divide(X,Y,Answer)
	e) square(X,Answer)
	f) squareroot(X,Answer)
	g) cube(X,Answer)
	h) double(X,Answer)
	i) hypotenuse(X,Y,Answer)
  
   X and Y should be integers and Answer should be a variable at 
   the time of call.  These queries may be posed to any of the
   three agents.

5) To replace agent a2 by a human, type

	halt.

  in the window of agent a2 and restart with code for a human agent

	icp -n -z 'load(agent),init_agent(human2)'

  Now the user is responsible for solving multiplication and division
  problems.  Try

	solve(hypotenuse(3,4,H)).

  again to see the difference.  When a request arrives, a new window
  is created displaying the query and prompting for an answer.  The
  answer is a prolog term so it should be followed by '.' and <RETURN>.

6) To exit, type

	halt.

   in the agent windows, and type CTRL-C to stop the mailbox server
   program.



NOTES:
======

In this example, all agents have full knowledge of the capabilities of
the other agents.  Typically, this is not the case.  We can modify this
example by making each agent explicitly register its capabilities with
the mailbox server using mbx_bind/2.  Then whenever an agent has a
problem which it cannot solve, it can query the mailbox server program
using mbx_getid/2 to get the ID of an agent which has that capability.
