Use
===

Multi-agent processing is enabled by selecting the line

DFLAGS = -DMULTI_AGENT_ENABLED

in the file make.body followed by a recompilation of the system.  (Be sure to
make clobber before issuing make).  The multi-agent version of Soar appears
no different than the existing Soar system unless you replace the use of any
.init.soar file with a .init.soar.multi file. (Both are checked for in the
current directory and if neither exists, both are checked for in the home
directory.  If both exist, then the .init.soar file takes precedence.)  The
.init.soar.multi file initializes a "global" agent which serves only to
manage the other agents.  The contents of the .init.soar.multi file would
normally begin with the command, create-agents.  This new command informs
multi-agent Soar of the names of agents to be run.  E.g.,

create-agents eight farmer

would create two agents.  Upon reading each name, multi-agent Soar will look
for a directory by the same name to load an .init.soar file for that agent
(the home directory is checked if it does not exist in the current
directory).  The .init.soar file for the agent is read in just as is done for
single agents in the single-agent Soar.

One additional command has been added to the interface to specify how much
processing is to be done when an agent is called in the scheduler.  The
command agent-go has (almost) the same syntax as the go command.  The only
difference between agent-go and go is that agent-go only defines the go
settings, while the go command both defines the settings and executes the
agent for the duration indicated by those settings.  A typical setting might
be:

agent-go farmer 1 d

which runs the agent for one decision cycle when called.  If all agents have
this setting, then their processing will be interleaved every decision cycle.
Of course, agents can differ in their processing settings.  E.g., one agent
can run for 1 decision cycle and another can run for 2 decision cycles (or
any other acceptable go command setting).

While processing the create-agents command, each agent is defined in turn and
its .init.soar file is read in.  All communication with the process is still
via standard I/O so the output is interleaved.  When the init files have been
read in and each agent initialized, a prompt is issued on standard output:

Soar agent control>

(The Soar agent control is a "dummy" Soar agent used to control the
operations of the other agents, simulations, etc.  Currently, the only
difference between the agent called "control" and the other agents is that
control's processing is defined by the .init.soar.multi file and the agent is
not available for scheduling in the scheduler.)

The user can select a specific agent to communicate with by entering the
select-agent command:

Soar agent control> select-agent farmer
Soar agent farmer>

Hence, the prompt changes indicating the agent the user is currently issuing
commands to.  At a prompt, the user can issue any Soar command and it will be
passed on to that agent.

To run the agents continuously in a round-robin fashion, the new command
schedule is entered:

Soar agent control> schedule

and the agents will be executed in turn, using whatever processing duration
was defined for them.  The schedule command can be issued to any agent.  The
selection of an agent to run by the scheduler is indicated when the system
outputs a line such as:

Selecting agent eight

This helps clarify the output of agents since they are interleaved on the
standard output.  The processing of agents is terminated by a control-C, ^C,
and control returns to the main prompt, i.e., for the control agent.  You
must interrupt the agents if you want to enter commands since the target
agent is not well defined in an interleaved I/O scheme.