oaa_RegisterCallback(app_done, ProcedureName)

    oaa.oaaRegisterCallback("app_done", listener)

    oaa_RegisterCallback(app_setup_trigger, ProcedureName)

    oaa.oaaRegisterCallback("app_setup_trigger", listener)

4.6 Invocation Arguments and the Setup File

1. on the command line
2. in environment variables
3. in a setup file.

1. Use these arguments on the command line:

       fac -oaa_connect "tcp('mymachine.ai.sri.com', 3345)" ...
   

   Some Java agents -- in particular, agents constructed using the WebL library -- may not check command line arguments. In this case, use the "-D" property specification described next.

2. Set environment variable OAA_CONNECT (for non-Java agents) to contain this string:

       tcp('mymachine.ai.sri.com', 3345)
   

   Java agents don't normally have access to environment variables. The appropriate alternative to use with a Java agent is setting the OAA_CONNECT property on the command line:

       -DOAA_CONNECT="tcp('mymachine.ai.sri.com', 3345)"
   

3. Place the following in a setup file:

       oaa_connect( tcp('mymachine.ai.sri.com', 3345)).
   

   (Note, however, that oaa_connect should be used with care in a setup file. Another alternative, default_facilitator, works better for most situations.)

When creating new invocation arguments for specific client agents, developers are encouraged to follow these same conventions. Library procedure oaa_ResolveVariables may be used to search the command line, environment, and setup file.

4.6.1 The Setup File

The agent library contains code that loads a setup file if it is present in any of the following locations:

1. A location (file path) specified on the command line (or in an environment variable) using -setup_file (or SETUP_FILE)
2. setup.pl in the agent's current directory
3. setup.pl in the "home directory" of the user who is running the agent (under UNIX, ~/setup.pl; under Windows NT, %HOMEDRIVE%%HOMEPATH%\setup.pl; under Windows 95/98, /setup.pl of the current drive)
4. setup.pl in the root directory ("/" under UNIX, "C:\" under Windows).

A setup file is loaded when library procedure oaa_ResolveVariables is called for the first time, with setup/3 specified in its argument list.

4.6.2 Facilitator Invocation Arguments

• -usage
  This causes the Facilitator to print usage info and immediately exit.
• -oaa_listen Address
  This tells the Facilitator what port to listen on, for connections from agents.
• -oaa_connect Address
  This causes the Facilitator to connect to a parent, thus making it a node Facilitator.
• -setup_file FilePath
  (Command line or environment variable only.) This causes the facilitator to use the specified file as the setup file.
• -write_setup_file Filename
  This causes the Facilitator to write out the address information for the port on which it is listening. The contents of the file will look like this:

  default_facilitator(tcp(HostName, PortNumber)). 
  

• -init_file FilePath (Prolog only)
  This loads an initialization file (for instance, a database state file) into the agent at startup time. Init files contain ICL commands that can be executed by oaa_Interpret, such as oaa_Declare, oaa_AddData, oaa_AddTrigger, potentially even oaa_Solve. A database state file contains one or more oaa_Declare's followed by a set of commands having this form:

  oaa_AddData(Clause,[address(self)])

  for each data predicate declared.
• -oaa_name Name
  May be used to set the symbolic name of an agent (client or facilitator). Overrides whatever name may be specified in the agent's source, in a call to oaa_Register.
  Note: In facilitator code, this internally specified name is 'root', which is fine for single facilitator systems, and for the non-parented facilitator in a hierarchical multi-facilitator system. In these multi-facilitator systems, however, it is usually desireable to use oaa_name to give a distinctive name to the other facilitators.
• -write_connections_file Filename
  This causes the Facilitator to write detailed information about its communications connections. For a root Facilitator, there will normally be just a single entry. For a node facilitator, this connections file will contain 2 entries: one for the port on which it is listening, and one for the port of its parent.
• -on_port_exception Action
  This specifies an action for the Facilitator to take when it is unable to listen on a specified port.
  Action can be any of the following:
  • exit
  • try_again
    Try to open the port repeatedly, every five seconds.
    Note: In a setup file, this may also be specified with a numeric argument for number of seconds. For example:

    try_again(10.0).
    

  • next_highest
    Try to open the port with the next highest number.
    Note: In a setup file, this may be specified with an integer argument, for number of different ports to try. For example, if the initial port specification is 3500, and the following appears in the setup file:

    next_highest(100).
    

    the facilitator will try listening on each port numbered 3500 - 3600, until one is available, or it has tried them all without success (in which case it exits). In the absence of the integer argument, the default value of 100 will be used.
  • change_port
    Prompt the user for a different port number.
  • any_available
    Get the number of an available port from the operating system.

4.6.3 Client Agent Invocation Arguments

• setup_file FilePath
  Library code checks for this whenever oaa_ResolveVariables is called.
• -oaa_connect Address
  This argument tells the agent the network address to use to connect to a facilitator. Library code checks for this whenever com_Connect is called.
• -oaa_listen Address
  This argument tells the agent to open a listener socket, and the network address to use for that socket. Library code checks for this when oaa_SetupCommunication is called.

• -on_connect_exception Action
  This specifies an action for the agent to take when it is unable to connect to a specified port.
  Action can be any of the following:
  • exit
  • try_again
    Try to open the port repeatedly, every five seconds.
    Note: In a setup file, this can be specified with a numeric argument for number of seconds. For example:

    try_again(10.0).
    

  • next_highest
    Try to connect to the port with the next highest number.
    Note: In a setup file, this may also be specified with an integer argument, for number of different ports to try. For example, if the initial port specification is 3500, and the following appears in the setup file:

    next_highest(100).
    

    the agent will try connecting to each port numbered 3500 - 3600, until it successfully connects, or has tried them all (in which case it exits).
  • change_port
    Prompt the user for a different port number.

4.6.4 The default_facilitator Argument

For this reason, when it is desired to specify a connection address in a setup file, it is usually best to use

    default_facilitator(tcp(HostName, PortNumber)).

   default_facilitator(tcp('acapulco.ai.sri.com', 3333)).

Note that when Facilitator agents are arranged hierarchically in a multi-facilitator topology, the use of default_facilitator in a setup file is not appropriate, unless it is known that each facilitator will read a different setup file, or will get its address information from the command line or environment.

Although connection addresses are usually fully specified for a Facilitator agent, it is possible to specify a variable for either the host or port. In this case, acceptable values will be automatically chosen by the system.

5. Providing Services

5.1 Declaring Solvables

5.1.1 Specification of a Solvable

      solvable(GoalTemplate, Parameters, Permissions)

For example, the solvable list for a simple mail agent might look like this:

      [solvable(send(mail, ToPerson, Msg), [callback(send_mail)], []),
       solvable(last_message(MessageNum),
                [type(data), single_value(true)],
                [write(true)]),
       solvable(get_message(MessageNum, Msg), [callback(get_mail)], [])
      ]).

For those readers with limited knowledge of Prolog, we note that ToPerson, MessageNum, and Msg are variables, whereas the other argument values (mail, data, true and false) are constants.

In the case of the goal template send/3, the variable ToPerson is expected to be bound when the solvable is called, whereas in the goal template last_message/1, MessageNum provides a return value; that is, free when the solvable is called, and bound when the solvable returns. This distinction is not apparent from the solvable specifications, however; it is only known by considering the meaning and context, or by reading the comments for the solvables.

5.1.2 Goal Templates of Solvables

The goal template of a solvable provides, at a conceptual level, a description of the service (or data) provided; at a functional level, a specification that the agent's facilitator can use in making delegation decisions; and at the level of communications, a template for the event which the agent will receive when the service is requested.

When writing a solvable goal template, it is important to understand that each goal template specification will be used according to the semantics of unification, just as it is used in logic programming. When the facilitator receives a request to solve some goal, it uses unification to test that request against the goal templates contained in the solvables specifications of its connected agents. (Solvables permissions and parameters do not figure in the unification, only goal templates.) By default, each connected agent for which the unification succeeds receives the request. The event that expresses this request, as sent to the agent by the facilitator, and passed to the agent's callback procedure, is the result of this unification.

5.1.3 Permissions of Solvables

A solvable's permission list may contain the following boolean permissions. In each case, the meaning of the permission applies to all agents ( including the one declaring the solvable). Although this may be considered counterintuitive in some respects, improvements have been deferred until a more comprehensive permissions scheme is developed.

• call(TrueOrFalse). If true, the solvable is available to be called. If false, the declaring agent receives no requests for the solvable from the facilitator; nor can the declaring agent call it locally. (Note, however, that a solvable can be made available for local use only, using the private parameter -- see below.)

• write(TrueOrFalse). This permission applies only to data solvables. If true, the solvable can be updated (that is, facts can be added, removed, and replaced). If false, the declaring agent receives no requests for updates from the facilitator; nor can the declaring agent update the solvable locally.

• read(TrueOrFalse). If true, the definition of the solvable's callback can be obtained by other agents. This permission is currently not in use.

In the example solvable list above, the first and third solvables need not specify any permissions, because they use only the default values, which are call(true), write(false), read(false). The second solvable, last_message, specifies the non-default permission write(true), to allow updates to the data associated with this solvable. It is very common to use write(true) with data solvables. A solvable's permissions can be modified at anytime.

5.1.4 Parameters of Solvables

There are a number of parameters that may be used to characterize a solvable. Of these, the most important are type/1, utility/1, and callback/1.

The value of type/1 can be either data, procedure, or trigger; the default is procedure. These three types are informally characterized in Section 4.3.1, Declarations of Capabilities (Solvables).

As explained there, procedure and data solvables can both be accessed by calling oaa_Solve. Technically, there are three specific differences between these two types of solvables. First, a data solvable can be updated using library procedures oaa_AddData, oaa_RemoveData, and oaa_ReplaceData. Second, it is not necessary (or possible) to define a callback procedure for a data solvable. Finally, for a data solvable, the agent library maintains a record of which facts are created by which agents, and uses this information to remove an agent's facts when the agent goes offline. (This behavior can be modified using solvable parameters bookkeeping/1 and persistent/1.)

The value of utility/1 can be any integer between 0 and 10; the default is 5. This parameter provides a means of giving a qualitative indication of how well the agent performs the service implemented by the solvable, with larger numbers expressing higher quality of service. This number is used by the agent's facilitator, when multiple agents offer the same solvable. When a facilitator receives a request for such a solvable, it orders the available solvers by decreasing utility, which means the agents claiming higher utility will receive the request first. Or, if the request is accompanied by certain combinations of parameters (see the strategy(action) parameter to oaa_Solve), the agent claiming the highest utility may be the only one to handle the request.

The value of callback/1 is an ICL expression that names a user-defined procedure. The use of this procedure is described below, in Defining Request Handlers.

An exhaustive list of solvables parameters, with their possible values and default values, is given in the Reference Manual. General characteristics of parameter lists are explained in Section 4.3.6, Parameter Lists.

5.1.5 Shorthand Forms for Solvables

Specifications of solvables have a standard form and several alternative shorthand forms. The shorthand forms are provided primarily for backwards compatibility with earlier versions of the agent library. Each library procedure that takes a solvable list as an argument will accept any of these forms, so that developers' calls to these procedures may be made more readable, in some situations. In addition, it is always acceptable to pass in a single solvable, instead of a list. When the solvable or solvable list is passed in using one of the shorthand forms, it is converted to standard form. Thus, when debugging their code, developers may see the results of this conversion.

The differences between standard and shorthand forms are straightforward. In standard form, each solvable term contains all three arguments:

      solvable(GoalTemplate, Parameters, Permissions)

      [solvable(get_message(MessageNum, Msg), [], [])]

      [solvable(get_message(MessageNum, Msg), [], [])]

      [solvable(get_message(MessageNum, Msg), [])]

      [solvable(get_message(MessageNum, Msg))]

      solvable(get_message(MessageNum, Msg), [], [])

      solvable(get_message(MessageNum, Msg), [])

      solvable(get_message(MessageNum, Msg))

      get_message(MessageNum, Msg)

5.1.6 Library Procedures for Declaring Solvables

• oaa_Register(+ConnectionId, +AgentName, +Solvables,+Params).

  A call to oaa_Register is the means by which a client (that is, non-facilitator) agent normally registers with a facilitator, and informs the facilitator of its solvables. oaa_Register should be called after opening a communications channel to the facilitator, using com_Connect. Every client agent is required to connect and register with a facilitator to participate in a community of agents. However, it is not required that the agent specify its solvables when it registers. If an agent wishes to specify its solvables later, it may do so using oaa_Declare.

  If an agent has no solvables to declare when it connects, it may pass the empty list ([]) as the third argument to oaa_Register.

  The AgentName argument is the symbolic name by which the client agent will be known to its facilitator and other agents (see Agent Names and Addresses).

• oaa_Declare(+Solvables, +CommonPermissions, +CommonParams, +Params, -DeclaredSolvables).

  A call to oaa_Declare may be used at anytime after connecting to a facilitator. Each solvable in Solvables is added to the agent's list of current solvables, both locally and in the agent's facilitator (unless private(true) appears as a parameter, in which case the facilitator does not learn of it).

• oaa_Undeclare(+Solvables, +Params, -UndeclaredSolvables).

  A call to oaa_Undeclare results in the removal of each previously declared solvable that is listed in Solvables.

• oaa_Redeclare(+Solvable, +NewSolvable, +Params).

  This library procedure may be used to simultaneously remove one solvable, and install another. Conceptually this is the same as a call to oaa_Undeclare followed by a call to oaa_Declare, with the appropriate arguments, except that oaa_Redeclare ensures the two operations take place at the same time. This is especially useful when changing the permissions or parameters associated with an existing solvable.

In addition to declaring solvables for itself, an agent can ask its facilitator to declare solvables of type data; this is done by including address(parent) in the Params argument. When this is done, the result is a shared data predicate that can be read and written by all clients of the facilitator. This is one way of implementing a "blackboard" approach to communication and coordination between agents.

5.3 Defining Request Handlers

When an agent receives a request for one of its services declared as a procedure solvable, the callback procedure for that service is called. To handle these calls, each agent must define code that implements the callback procedure of each solvable it has declared of type procedure. (Callbacks for data solvables are provided transparently by the agent library, and trigger solvables have no need of callbacks.)

As explained in the preceding section, a callback procedure for a solvable can be specified in the parameter list of the solvable's declaration. It is also possible to declare a default app_do_event callback for procedure solvables, using oaa_RegisterCallback. When this is done, any request for a procedure solvable, which has no specified callback, will go to the default callback.

In Prolog, callback procedures, are assumed to be defined in module user, unless some other module is explicitly indicated. This may be done using the standard syntax Module:CallBack; for example, callback(my_module:my_procedure).

The callback procedure is always called with two arguments: the incoming goal to solve, and a parameter list. The return value(s) of the callback procedure are the instantiated solutions to the goal. In Prolog, these are returned by the usual means, using backtracking to provide various bindings of the goal's variables.

For example, for the solvables declared above, in a Prolog implementation, the callbacks would be defined as follows:

   send_mail(send(mail, ToPerson, Msg), Params) :-
       <code implementing the send solvable ...>

   get_mail(get_message(MessageNum, Msg), Params) :-
       <code implementing the get_message solvable ...>

Either or both of these solvables could have had their goals handled by the default app_do_event callback, if one has been declared. Regardless of whether you choose to use a default callback for any (or all) of your solvables, it is sometimes necessary to define a default callback for handling some events other than those associated with solvables. For instance, Section 6.8 describes how it may be used to intercept ev_solved/6 events returned asynchronously from other agents.

Notice that there is no callback defined for the last_message solvable, because it is a data solvable.

In general, when defining a callback procedure, the parameter list argument may be ignored; that is, the goal argument contains the essential information for satisfying the incoming request. However, occasionally it may be useful to know what agent has made this particular request. This may be determined by retrieving the value of the from parameter; for example, in Prolog:

    send_mail(send(mail, ToPerson, Msg), Params) :-
        icl_GetParamValue(from(Requestor), Params),
        ....

In the agent libraries for languages such as C, Delphi or Visual Basic, because those languages do not provide backtracking, the conventions for returning multiple solutions from a callback procedure are slightly different than for Prolog.

In the C, Visual Basic and Delphi libraries, the callback procedure returns success, failure or multiple solutions to the incoming request in the variable answers. For an event request send(mail,'Adam', Msg), a successful action would return "[send(mail,'Adam', Msg)]" in answers, and failure would be indicated by returning the empty solution list "[]". Multiple solutions can be returned as well: the query manager(adam,X) could return two solutions by storing "[manager(adam,jerry),manager(adam,doug)]" in answers.

5.2 Optional Typing of Solvables

Beginning with release 2.3.0, OAA allows for optional type declarations to be given with solvables. A type declaration characterizes each of a solvable's arguments, in terms of ICL data types and binding constraints. (In a future release, it may also be possible to work with "user-defined" data types). When this information is present, the facilitator uses it in its matchmaking operations.

Declaring Argument Specs

To declare types associated with a solvable, include an argspecs term in the solvable's parameter list:

    argspecs(ArgSpec1, ArgSpec2, ..., ArgSpecN)

1. An input argument specification indicates that in a goal, the argument will be either fully instantiated or a var (and it can only be a var if Required? is false).

       in(TypeSpec, Required?)
   

   • TypeSpec: One of the types listed in ICL Data Types
   • Required?: true or false, as to whether the argument must be instantiated.
2. An output argument specification indicates that in a goal, the argument will be a var; in a solution; it will be fully instantiated.

       out(TypeSpec, Deterministic?)
   

   • TypeSpec: One of the types listed in ICL Data Types
   • Deterministic?: true or false; true means at most 1 return value; false means Prolog-style backtracking over multiple solutions is possible.
3. An inout argument specification indicates that in a goal, the argument may be partially instantiated in a goal, in which case it may be more fully instantiated in a solution.

       inout(TypeSpec, Deterministic?)
   

   • TypeSpec: One of the types listed in ICL Data Types
   • Deterministic?: true or false, as above.

A variable may also be given as a type spec, meaning that arguments in that position can be of any type.

When argspecs isn't present, every argument is assumed to be declared as inout(_, false); that is, any type allowed and not required (input arguments) or deterministic (output or inout arguments). This conforms with current practice of the facilitator.

Note that with respect to compound types, there are now two places in which they may be declared. One is the traditional means of specifying the compound type skeleton within the goal template of the solvable. For instance, the goal template

  send(Recipient, mime('text/plain', _))

Names

    argnames(Name1, Name2, ..., NameN)

Matchmaking with Types

Note that there is a supertype/subtype hierarchy implicit in the built-in types above. For instance, float and integer are subtypes of number, and string and number are subtypes of atomic. These relationships will be respected by the facilitator, in matchmaking. For instance, if an argspec indicates type 'number' for a given argument, the faciliator checks that the value of that argument in the goal is either an integer or a float.

Type recognition

For primitive argument values, such as atoms, numbers, the type of an argument is determined by standard means (provided by the Prolog programming language).

For argument values having the functor icldataq, the type is simply icldataq(_) or icldataq(_,_,_), depending on the structure of the argument value.

For argument values having the form xml(XSDSpec, _XMLDocument), the type is identified as xml(XSDSpec, _Variable). Similarly for mime(MimeType, _MimeDocument).

5.4 Delaying Solutions

Normally, a callback procedure responding to a request from the agent community does all of its work and assembles all its solutions before returning.

There is also the possibility of delaying the return of a callback procedure's solutions until some future time. This is often useful for events which may take a long time to complete, or will depend on information or events that arrive asynchronously. For example, if a robot has been asked to attain a certain position, this is not a goal that can be achieved quickly. In such cases, it may be desirable to return immediately from the callback procedure, so that other processing steps can proceed.

The process of delaying solutions in an app_do_event callback is handled in three steps:

1. At the end of the callback, call oaa_DelaySolution(ID), where ID is any identifier you choose to represent this specific request. Calling oaa_DelaySolution(ID) inside the callback informs the library NOT to return solutions for the event.
2. If any processing you do as part of calculating results for the delayed request requires you to issue requests to the agent community using primitives such as oaa_Solve(Goal,Params), oaa_AddData(Data,Param), or oaa_AddTrigger(Type,Cond,Action, Params), you should call oaa_AddDelayedContextParams(ID,YourParams,NewParams) to mix in the appropriate context parameters into your outgoing requests.
3. When you have finished calculating results for the original request, the results should be gathered into a list of solutions and returned using oaa_ReturnDelayedSolutions(ID, SolutionList).

   Here is an example in Prolog, where an agent managing the control of robot movements publishes a solvable move_robot(RobotId,PosX,PosY). Since robotic movement can take a long time, and since event updates as to the robot's position and status arrive asynchronously over time, delayed solutions are used to implement the solvable.

   % If someone asks me to make a robot move to (X,Y),
   %   I will tell the robot to start moving, but won't
   %   have completed the task until I know if the robot
   %   has reached the goal or has given up.
   oaa_AppDoEvent(move_robot(RobotId, X,Y),_Params) :- 
        start_moving(RobotId, X,Y).
        oaa_DelaySolution(RobotId).
    
   % As the robot moves, we receive updates on its position,
   %   which we broadcast to all interested agents.
   oaa_AppDoEvent(current_position(RobotId, X,Y),_Params) :- 
      % instead of calling oaa_Solve(robot_pos(RobotId,X,Y),[broadcast]), 
      % we break it into 2 steps to allow oaa_AddDelayedContextParams()
      % to mix in any context parameters.
      oaa_AddDelayedContextParams(RobotId, [broadcast], ParamsWithContext),
      oaa_Solve(robot_pos(RobotId,X,Y), ParamsWithContext).
   
   % We receive the event that say the robot has completed its task
   % so we return solutions to the original request.
   oaa_AppDoEvent(finished_moving_to(RobotId, X,Y),_Params) :- 
      oaa_ReturnDelayedSolutions(RobotId, [move_robot(RobotId, X, Y)]).
   
   % Here we are notified the robot can't do the task and has
   % given up, so we return failure (the empty solution list)
   oaa_AppDoEvent(cant_move_to(RobotId, X,Y),_Params) :- 
      oaa_ReturnDelayedSolutions(RobotId, []).
   
   

   Even though internally the treatment of the solvable move_robot() is handled in a delayed, asynchronous way, this is transparent to a requesting agent, who can issue a oaa_Solve(move_robot(robot1, 100,100),[]) request which will block until the robot has succeeded or failed in its goal.

   5.5 Event Priorities and Queues

   The priority(P) parameter is used to control priorities among events. P's value may range from 1 (lowest priority) to 10 (highest priority). The default priority is 5. As events arrive on the communication stream, events are ordered such that highest priority events are executed first.

   The priority(P) parameter may be specified in two places:

   1. a priority may be given in the parameter list of a solvable declaration.
   2. priorities may also be specified as parameters to the oaa_Solve procedure or the oaa_PostEvent procedure.

   Imagine declaring a solvable for your agent a(X), which relies on some information provided by the agent community, a1(X). When an incoming request arrives at your agent, the callback associated with a(X) is called as described above. This callback calls oaa_Solve(a1(X),[]), which blocks, waiting for solutions to be returned from the agent community. While the agent is waiting for solutions to be returned, new events may arrive on the communication channel. What happens to these new events? The following behavior is produced:

   • If the incoming event is of the SAME or LOWER priority as the event we are currently solving, the event is queued for later execution. These events will be executed after goals a1(X) and a(X) have completed.
   • If the incoming event is of a HIGHER priority, it will be executed immediately, interrupting the current goal a(X).

   5.6 Meta-Agent Services

   Meta-agents use their domain-relevant knowledge to help a Facilitator agent make decisions. Meta-agents might incorporate learning algorithms or neural networks, expert systems or rulebases, user-preferences or any strategy for making intelligent decisions.

   Meta-agents are simply OAA agents that define a special solvable or capability called "meta", in the form:

   meta(Type, +Goal, +Params, +FacInfo, -Result).
   Currently, Type may be one of the following:
   • lookup: This type of meta-agent implements a strategy for finding and starting new agents that can solve a query. If some agents makes a request for Goal and there are currently no agents installed locally that can be considered to handle Goal, a "lookup" meta hook will fire. Given an incoming Goal and Params from the oaa_Solve request, the meta agent is responsible for finding and starting an agent who can handle the Goal. If such an agent can be found and started, the meta capability should return "true" once the agent is properly conntected. Otherwise, the meta agent returns false, indicating that it could not complete its task.

   • prioritize: The Facilitator uses an agent's published utility declaration to order multiple agents who could potentially accomplish the same task. Agents of equal utility will be ordered on a first-come, first-serve basis. If a meta-agent declares a "prioritize" meta capability, it will be called with the Goal and Params from the oaa_Solve request, and FacInfo will contain the sorted list of agents as determined by the Facilitator. The meta-agent thus has the opportunity to reorder the list, returning the new list in the Result parameter. Uses may include user preferences (a user prefers a particular agent over another), or load-balancing.

   • plan_query: When the Facilitator is compiled to handle compound goals, the Facilitator uses its strategies and metadata to produce a routing plan for a given delegated request. This meta hook allows smarter or more specialized Facilitator agents to improve on the plan generated by the Facilitator. FacInfo will contain the plan as calculated by the standard Facilitator, and Result should contain the modified plan.

   • execute_plan: When the Facilitator is compiled to handle compound goals, once it has calculated a routing plan for a given query, it then interprets the plan, invoking and coordinating the appropriate agents. The "execute_plan" meta hook enables extended plans (probably generated by a plan_query meta-agent) to be interpreted by a client meta-agent. This may also be useful for scalability scenarios where having a single Facilitator could be a single-point-of-failure and bottleneck, executing all plans and storing all executiong state for all agents. The hook would allow distributed execution of the route plans.

   Note: other meta hooks may be added in the future.

   Several meta-agent hooks may fire for the same query. For instance, if an agent performs oaa_Solve(a(X),[strategy(action)]) and no agent is currently loaded that can handle a(X), a "lookup" meta-agent may fire, loading several agents that can perform a(X). These agents will be prioritized in order of expected utility, and this sequencing may be then improved upon by "prioritize" meta-agent.

   What happens if several meta-agents have differing opinions about how a goal should be handled? In this case, the Facilitator uses the "action" strategy to handle them: all meta-agents that can contributed are collected and themselves ordered according to expected utility. The first meta-agent is consulted, and if it returns useful information, the Facilitator uses it. If not, the next meta-agent in the list is consulted until at most one agent succeeds in providing information the Facilitator can use. If no information is found, the Facilitator proceeds with its default handling of the delegated task.

   
   
   
   
   

   6. Requesting Services: the oaa_Solve Procedure

   While performing a task, an agent can often make use of information and services provided by other agents. The mechanism for making requests of other agents is encapsulated in a single procedure, oaa_Solve/2. The oaa_Solve/2 procedure provides considerable flexibility in making requests, by selecting different combinations of parameter values. Here, we describe some of the more commonly used parameters. For a complete list, see the Reference Manual.

   6.1 Prolog-Style Queries

   The standard way (in Prolog) to request a solution to some query is to call the procedure

       oaa_Solve(Goal, ParameterList).
   

   Note: Other programming languages such as C or Delphi have their own syntactic variants for all of the library routines described in this developer's guide. For instance, in C, the solve procedure is declared as

       oaa_Solve(char *Goal, char *ParameterList, char **answers)
   

   By default (that is, with an empty ParameterList ([]), or by calling the oaa_Solve/1 procedure which assumes an empty Parameter list), a call to this procedure directs the agent's facilitator to assemble all available solutions to Goal; that is, solutions from all of the agent's peers that offer Goal as a solvable. (Note that this description applies when Goal is non-compound; things are slightly more involved with compound goals.) From the programmer's point of view, however, it is used just as if Goal were being executed locally by a Prolog interpreter: it can fail or succeed, and multiple solutions can be obtained through backtracking. This is a very convenient and natural method of writing code when creating an agent's functionality.

   When a goal is sent to a facilitator through a solve request, the facilitator looks for agents that can provide a response to the goal by matching the goal against the procedure and data solvables of all connected agents. If multiple agents have indicated that they can return solutions to the goal in question, the default behavior used by the facilitator is to send the request to all pertinent agents and to wait until all agents have responded, collecting the solutions from each agent and routing the set of all solutions back to the requesting agent. If you wish to override this default behavior, perhaps having individual agents send their specific solutions back to the requesting agent separately, use the reply parameter.

   However, this default use of the solve procedure, while providing all of the power and expressiveness of Prolog, also has its shortcomings; for example, execution of the agent calling oaa_Solve is suspended until the goal has been solved, either succeeding or failing. This goal may take a certain time to resolve, as it will be posted to the facilitator, and then routed to another agent on another machine for processing. And during this time, the agent posting the query is dormant, waiting for the solution to return. There are, however, a number of alternative methods of posting queries, using the ParameterList, as explained below.

   6.2 Prolog-style Queries with Caching

   In some particular cases, an agent may decide to use oaa_Solve/2 with the cache parameter; that is,

       oaa_Solve(Goal, [cache]).
   

   This behaves just like oaa_Solve(Goal, []), except that once the goal is computed, the solution is stored locally in the agent's database. The next time that the same goal is recomputed, the answer is found immediately, without accessing a remote agent. This optimization must be used with care, as the agent is responsible for maintaining the coherency of his own cache: if a solution is subject to changes over time, it is safer to omit the cache parameter.

   The cache option should correctly handle subsumption. Imagine that a user first issues the request

       oaa_Solve(hotel('fairmont', Info), [cache])
   

   which returns one solution, storing this in the cache. If at a later time, the user asks the query

       oaa_Solve(hotel(Any,Info),[cache])
   

   it would be an error to return only the solution stored in the cache; rather, the system must recognize that the cache does not have information stored which subsumes this query, so a new query must be posted over the network. Subsumption is currently correctly handled by the Prolog agent library, but is not correctly handled by the agent libraries in other programming languages.

   An agent can choose to clear its own cache by using the primitive oaa_ClearCache.

   6.3 Limiting the Number of Solutions or Solvers

   As mentioned above, the default use of oaa_Solve/2, oaa_Solve(Goal, []), causes the responding agent(s) to generate all possible solutions to Goal. In some cases, depending on how the called procedure is written, finding multiple solutions may have undesirable side-effects. Thus, if the calling program knows that it needs only a single solution, or a limited number of solutions, it can prevent the responding program from finding all possible solutions, by using the solution_limit(N) parameter:

      oaa_Solve(Goal, [solution_limit(N)])
   

   where N can be any positive integer.

   This parameters tells each responding agent to find at most N solutions. This means that, when there are multiple responding agents, the total number of solutions returned to the requester may exceed N. However, in the presence of parameter parallel_ok(false), a solution limit can also influence the facilitator's behavior. For example, suppose that both solution_limit(10) and parallel_ok(false) have been specified for some request, and that the facilitator identifies 4 candidate solvers. If, say, the first two solvers return a total of 12 solutions, the facilitator will not send this request to either of the remaining two candidates.

   Similarly, a requester can also limit the number of providers selected to handle a request, using the the provider_limit(N) parameter. That is,

      oaa_Solve(Goal, [provider_limit(N)])
   

   tells the facilitator to select at most N agents to satisfy the given Goal.

   provider_limit(N) and solution_limit(N) can be used in conjunction. For example,

      oaa_Solve(Goal, [provider_limit(2), solution_limit(3)])
   

   tells the facilitator to select at most two providers to handle the given Goal, and tells each of those providers to generate at most three solutions.

   6.4 Using the Requesting Agent as a Solver

   When a request is received by a facilitator from some agent, the facilitator's normal behavior is to solicit solutions from all agents that claim to handle that sort of request, including for the requesting agent itself. If it is not desired that the requesting agent be included as a solver of a request, that may be indicated using the reflexive parameter:

       oaa_Solve(Goal, [reflexive(false)])
   

   Even with the reflexive parameter true, the requesting agent will only be asked to solve a goal when the goal matches one of its procedure or data solvables.

   6.5 Requesting Solutions from Specific Agents

   In general, when requesting the solution to a goal, an agent posts the request to the facilitator without knowing which remote agent (or agents) will solve the goal -- the facilitator is responsible for transparently locating an appropriate agent (or agents). However, if the address(es) of a specific agent (or agents) are known, the address(es) can be indicated in the parameter list as

       oaa_Solve(Goal, [address(AgentAddress)])
   

   Addresses are described in Agent Names and Addresses.

   6.6 Requesting Data Solutions Owned by Specific Agents

   The owner/1 parameter may be used, when querying a data solvable, to specify that only solutions (facts) owned by a particular agent are desired. The argument must be the local ID of a single agent. For example,

       oaa_Solve(airline_rating(A, R), [owner(6)])
   

   will retrieve all facts of the data solvable airline_rating/2, which are owned by the agent with local ID 7.

   Data ownership is explained in Section 7.5, Ownership of Data Elements.

   6.7 Solution Routing

   OAA provides several options for controlling whether, and when, solutions are returned for a goal submitted to oaa_Solve; these are indicated using the blocking/1 and reply/1 parameters. blocking/1 controls the behavior of the requesting agent (the agent calling oaa_Solve), whereas reply/1 controls the behavior of the facilitator and the agents responding to the request.

   The blocking/1 parameter is boolean:

   • A value of true (the default) means that the call to oaa_Solve blocks until the solutions are returned from the facilitator -- at which time they are returned from oaa_Solve.

   • A value of false indicates that the call to oaa_Solve is to return immediately. In this case, solutions can still be handled when they arrive, as explained in the following subsection.

   The reply/1 parameter at present also has two possible values, but it is expected that there may be additional possibilities introduced in the future.

   • A value of true (the default) means that the facilitator is to collect all solutions, and return them in a single ev_solved event. When the value of the blocking parameter is also true, these solutions are transparently captured and returned from oaa_Solve. Otherwise, as discussed in the following subsection, the solutions can be handled by other means.

   • A value of none means that no solutions need be returned. This implies that oaa_Solve returns immediately, regardless of the value of blocking/1. The use of none also implies that no confirmation is provided that Goal was actually received or handled successfully by any other agent. This usage, which was called broadcast in an earlier version of OAA, is appropriate when an agent wants to send out a routine notification of some event or piece of information to interested agents; that is, the agents providing Goal as a solvable.
   The unique_values/1 parameter is boolean:

   • A value of true means that multiple copies of the same solution returning from a solve, potentially from different agents, will be removed. For instance, if an agent makes the request oaa_Solve(email('Adam Cheyer', E), [unique_values(true)]), if multiple database agents all contain the same information, only one solution for E will be returned.

   • A value of false (the default) returns all solutions from all agents without removing duplicate copies.

   6.8 Handling Asynchronous Solutions

   As explained in the previous subsection, the parameter blocking(false) may be used to request information from remote agents in a non-blocking fashion:

       oaa_Solve(Goal, [blocking(false)])
   

   In this way, an agent's computation can continue while the request is being resolved. This is more efficient for the local agent; however it is slightly more difficult to program, because additional code is needed to handle the results of the request when they arrive.

   Assuming the parameter reply(none) is not present, the results of a non-blocking query will generate an event of the form

       ev_solved(GoalId, Requestees, Solvers, Goal, Params, SolutionList).
   

   The Requestees argument will be a list of the local ID(s) all agents asked to handle the request, and Solvers will be a list off the local ID(s) of the agent(s) that succeeded in handling it. Goal is a copy of the original goal submitted to oaa_Solve. Params is a copy of the original parameters submitted to oaa_Solve, except that any variables appearing in partially instantiated parameters will have been bound. SolutionList is a list of the goal's solutions, each of which is unifiable with Goal.

   One way of handling the results of a non-blocking query is to provide a handler for the ev_solved/5 event, by declaring and defining an app_do_event callback. Another way is to trap the event by a local communication trigger, which supplies an action to be executed when the solutions are received.

   The following example posts the query to be solved, and then sets up a trigger to display the results of the goal asynchronously when they are returned. While the goal is being executed remotely, the agent can perform other actions.

       interface :-
         get_query_from_user(PostableQuery),
         oaa_Solve(PostableQuery, [blocking(false)]),
         oaa_AddTrigger(comm,
   	             ev_solved(_GoalId, _Requestees, _Solvers, PostableQuery, _Params, Solutions),
                        display(Solutions),
   	             [address(self), recurrence(when), on(receive)] ).
   

   Triggers are explained in Section 8, Using Triggers.

   6.9 Test-locatable Queries

   Using the test parameter, you can specify a test to be executed on a local facilitator, and if the test succeeds locally, only then will the goal be solved on that facilitator. This is useful, for example, when specifying a goal such as "send a message to the interface agent, but only on a facilitator where the user's name is 'phil'" :

       oaa_Solve(ui_inform('message'), [test(name('phil'))])
   

   Note: the test parameter is useful primarily when multiple facilitators are used, as described in Section 10.1, Using Multiple Facilitators.

   6.10 Controlling Hierarchical Search

   When agents are arranged in a hierarchy of multiple facilitators (see Using Multiple Facilitators), it is often important to indicate whether and to what extent a request should be propagated to remote facilitators. For this purpose, the propagate parameter may be used.

   The propagate parameter takes a single argument, which itself is a parameter list; the elements that may appear within this list are: up/1, down/1, up_limit/1, and down_limit/1.

   The up and down parameters each may take one of three values: true, false, and if_no_solvers. The value true indicates that the request should be propagated upward (or downward); false indicates that it should not be propagated; and if_no_solvers indicates that it should be propagated if there are no local agents that can handle this request (i.e., none that are clients of the same facilitator as the requester).

   Given that a goal is to be propagated upward or downward, the up_limit/1 and down_limit/1 parameters can be used to limit the number of levels, of facilitator agents, to which it is propagated. For example, specifying an up_limit of 0 would preclude all upward propagation (the request would go only to the facilitator of the requester, and thus would be no different than specifying up(false)), whereas an up_limit of 1 would allow the requester's facilitator to pass the request upward to its parent facilitator (but no further upward).

   The default for the up/1 and down/1 parameters is false. For up_limit/1 and down_limit/1, there is no default value, which means that the number of propagation levels is unlimited.

   The following example shows the propagate parameter that would be used if the requester wants its request to be handled by all agents that declare the appropriate solvable, and are clients of its facilitator, or of the parent of its facilitator, or of any other facilitator below that parent in the hierarchy.

       oaa_Solve(Goal, [propagate([up(true), up_limit(1), down(true)])])
   

   Note that the propagate parameter does not have any effect when an explicit address has been given, using the address parameter. When an explicit address has been given, the facilitator attempts only to route the request to the agent or agents specified, and does not consider propagation opportunities at all.

   These same parameters may also be used with oaa_AddData, oaa_RemoveData, oaa_ReplaceData, oaa_AddTrigger,, and oaa_RemoveTrigger.

   6.11 Controlling Search Time

   Except when a non-default value of the reply parameter is specified, the oaa_Solve/2 procedure blocks until a solution to a query has been found (either in a positive way - success - or a negative way - no solution can be obtained). For this reason, it is sometimes desirable to set a limit on the amount of time a remote agent can use to satisfy a query. The time_limit parameter is used to limit the amount of solve-time to a given number of seconds, with oaa_Solve/2 failing if no solution can be found in this amount of time.

   The time_limit parameter encloses a positive real number, as in the following example:

       oaa_Solve(Goal, [time_limit(10.5)])
   

   which indicates that the responding agent is not to be given any more than 10.5 seconds to respond. If it happens that the responding agent does not respond in the allowed time, the facilitator causes the call to oaa_Solve/2 to fail.

   However, it is still possible that the responding agent will return solutions after the time limit has expired. If this happens, the solutions are still returned to the requesting agent; that is, a ev_solved/6 event is sent to the requesting agent. This makes it possible for the requesting agent to make use of the belated response, if it takes the required steps to make use of that event. The way to do this is described in Section 6.8.

   6.12 Establishing a Context for a Request

   In many cases, a call to oaa_Solve will lead to a series of interactions between a number of agents. For example, some existing systems make use of a notification agent, which may be asked to get a message to a specified individual, using the most appropriate means. In a simple usage, this agent might be called like this:

       oaa_Solve(notify('Adam Cheyer', 'OAA meeting at 3:00'), [])
   

   In providing this service, this agent may call upon a calendar agent ( to determine the whereabouts of the specified recipient), a database agent ( to retrieve the recipient's phone number or email address), and one or more communications agents (e.g., a phone agent, an email agent, or a fax agent). If the phone agent is employed, the notification agent will also call upon a text-to-speech agent, to prepare digitized audio waveforms to be played over the phone line.

   In a scenario such as this, where a series of service requests (calls to oaa_Solve) is initiated by a single call to oaa_Solve, it is sometimes helpful to have a means of establishing a context that ties together all of the service requests. The context/1 parameter provides a simple means of doing this.

   The value of the context/1 parameter is unconstrained; that is, it may be any ICL atom or expression that is convenient. Whenever a call to oaa_Solve includes context(SomeValue) in its parameter list, that parameter is automatically propagated to all subsequent calls to oaa_Solve resulting from the initial call (regardless of which agent is making the call). In the scenario above, a context/1 parameter passed to the initial call:

       oaa_Solve(notify('Adam Cheyer', 'OAA meeting at 3:00'), 
                 [context(message_request_114)])
   

   would be present in each callback that transmits one of the subsequent service requests. For example, assume that the email agent is selected for use by the notification agent, and that it provides a solvable send/3 and defines a callback function send_mail/2, as described in the example from Section 5.3. Then its callback function will be called like this:

       send_mail(send(mail, 'Adam Cheyer', 'OAA meeting at 3:00'), 
   	      [..., context(message_request_114), ...])
   

   (The parameters list will also include such things as the from/1 parameter, indicating which agent generated this particular request.)

   It is possible for multiple context/1 parameters to appear in a parameter list. If the initial call to oaa_Solve contains multiple contexts, each of them is propagated to subsequent calls. Furthermore, subsequent calls may introduce additional context/1 parameters, in which case these are passed along together with those introduced by earlier calls in the chain.

   6.13 Getting Information from Return Parameters

   As described earlier, the address/1 parameter is optional for calls to oaa_Solve: when it is missing, it's the job of the facilitator to select an agent or agent(s) to which to send the request. In such cases, it may occasionally be useful to the requesting agent to learn precisely which agents the facilitator selected.

   This may easily be done, using the get_address/1 parameter. Unlike the other oaa_Solve parameters discussed above, get_address takes a variable for its argument. When oaa_Solve returns, this variable will be bound to a list of all agents to which the goal was sent (or, in the case of a compound goal, all agents to which any subgoal was sent). The elements of this list will be local IDs (as described in Section 4.3.7, Agent Names and Addresses).

   Because this parameter returns a value, it is called a "return parameter". Another return parameter, closely related to get_address/1, is get_satisfiers/1. Whereas get_address returns all agents to which the goal was sent, get_satisfiers returns only those agents which returned one or more solutions to the goal (or to some subgoal, in the case of a compound goal).

   6.14 Task Type Macros (Strategy Parameter)

   The strategy parameter can be used to specify a higher-level statement that implies some combination of lower-level parameters. Several task types "macros" have been defined for use with the strategy parameter:
   • strategy(inform): implies [reply(none),parallel(true)]. oaa_Solve(msg, [strategy(inform)]) can be used to broadcast "msg" to all interested observers. For example, when the speech recognition agent detects that the user has finished speaking, this time sensitive information could be transmitted using oaa_Solve(inform(speech, end_of_speech), [strategy(inform)]) and all user interface or modality fusion agents can use the information accordingly.

   • strategy(query): implies [parallel(true)]. For instance, if an agent wants to find the fax number for a person (a query), it might invoke oaa_Solve(fax_number(Person,FN),[strategy(query)]). In this context, all database agents responding to fax_number will be queried in parallel and their responses collected into a single response to the request.

   • strategy(action): implies [parallel(false),solution_limit(1)]. For example, if an agent wants to send a fax to a person (an action), it would be the wrong thing to send it to several fax agents at the same time because the target would receive several copies of the same fax. For an action task, the Facilitator agent will collect all relevant agents, prioritize them, and then send the goal to the first on the list. If the agent succeeds in the task, the action is complete. If the agent fails, the next in the list is tried until one succeeds. Note: meta agents of type "prioritize" are given the opportunity to apply domain-specific knowledge in helping the Facilitator order the agents.

   A future enhancement will enable a user to create their own strategies defining frequently-used combinations of parameters.

   6.15 Summary of Parameters for oaa_Solve

   The default behavior (paramlist = []) is to act like the Prolog primitive call(Goal), blocking until Goal is finished, and unifying and backtracking over solutions for Goal.

   This behavior may be modified by a parameter list, which may contain some combination of the following parameters:

   cache(T_F)	cache all solutions locally, and if good solutions already exist in the cache, use the local values instead of making a distributed request. Default: false.
   level_limit(N)	highest number of hierarchical levels to climb for solutions. default: N = 0 (don't climb)
   address(AgentId)	send request to specific agent, given its name or Addr. If AgentID is 'self', solves the goal locally.
   reply(Mode)	true: Reply desired. none: No reply desired. Default: true, except when the call to oaa_Solve is a trigger action, in which case it is none. 'none' is used here instead of false, because we anticipate some additional values.
   blocking(Mode)	true: Block until the reply arrives. : false: Don't block. In this case, the reply events (ev_solved) can be handled by the user's app_do_event callback function. Default: true, except when the call to oaa_Solve is a trigger action, in which case it is false. Note that reply(none) overrides blocking(true).
   callback(Pred)	When blocking(false) and reply(true) are in effect, hence asking for an asynchronous query, this parameter may be used to specify the predicate to be called with the reply event (ev_solved). In the absence of this parameter, the app_do_event callback is used.
   solution_limit(N)	Limits the maximum number of solutions found to N.
   time_limit(N)	Waits a maximum of N seconds before returning (failure if no solution found in time).
   context(C)	Passes a context value through any subsequent solves.
   parallel_ok(T_F)	if T_F is 'true' (default), multiple agents that can solve the Goal will attempt to work on it in parallel. If 'false', one agent will be selected at a time to solve the goal, until the maximum number of requested solutions (see solution_limit) is found.
   reflexive(T_F)	If T_F is `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
   priority(P)	P ranges from 1 (low priority) to 10 (high priority) with a default of 5.
   flush_events(T_F)	Will flush (dispose of) all events of lower priority currently queued at the destination agent. These events are lost, and will not be executed. This parameter should be used with caution!!! Default: false.
   get_address(X)	Returns a list of addresses (ids) of agents that were asked to solve the goal, or one of its subgoals
   get_satisfiers(X)	Returns a list of addresses (ids) of agents that succeeded in solving the goal, or one of its subgoals.
   get_goal_id(X)	Returns the GoalId generated for this solve request.
   strategy(S)	Shorthand for certain combinations of the above parameters. S is one of query = [parallel_ok(true)] action = [parallel_ok(false), solution_limit(1)] inform = [parallel_ok(true), reply(none)]

   Remarks: Note that certain combinations of parameters are inconsistent, and are handled as follows: reply(none) overrides blocking(true), reply(none) overrides parallel_ok(false)

   All of the above parameters may be used in the "global" parameter list (the second argument to oaa_Solve), when Goal is non-compound. Most can be used in the global list with compound goals also. Some of these parameters can also be used in the NESTED parameter lists of compound goals.
   
   
   
   

   7. Maintaining Data

   The agent library supports the creation, maintenance, and use of databases, in the form of data solvables. A data solvable is essentially the same as a relation in a relational database. Creation of a data solvable is explained in Section 5, Providing Services. Querying a data solvable, as with access to any solvable, is done using oaa_Solve, as explained in Section 6, Requesting Services. Here, we discuss the maintenance of data solvables. By "maintenance", we mean adding, removing, and replacing facts of the solvable.

   A data solvable can be used privately by an agent, or can be made publicly readable and/or publicly writable, so that other agents have access to it. The level of access is determined by the permissions and the private parameter associated with the solvable.

   The library procedures oaa_AddData, oaa_RemoveData, and oaa_ReplaceData are used to read and write data solvables.

   A call to any of these causes the agent that provides the data solvable to check its active data triggers, and may result in the firing of one or more of them, as explained in Section 8.3, Trigger Firing Conditions

   Note on terminology: In describing these procedures, we use the name clause for the argument that specifies the fact to be added, removed, or replaced. The connotation of clause is actually more general than that of fact, and clause is used deliberately. This is because in future versions of the OAA library, in certain situations, we expect that it may become possible to add, remove, or replace rules in addition to facts. For present purposes, however, clause may be considered synonymous with fact.

   7.1 Adding Data

   Any agent may add data to one of its writable data solvables (whether private or public), or to a publicly writable data solvable of another agent, by calling

       oaa_AddData(+Clause, +Params)
   

   This causes the the data element Clause to be recorded, in precisely the form given.

   Normally, there may be multiple facts recorded for a data solvable, and any number of facts that are exact duplicates of one another. However, note that the creation of multiple facts can be disallowed by the provider of the solvable, by declaring the solvable with the parameter single_value(true). Similarly, the creation of duplicate facts can be disallowed with the parameter unique_values(true).

   By default, the data element is recorded following al