Example 2

From Agent Factory

Necessary Packages

To follow this example, you must download the following packages:

• Agent Factory Runtime Environment (AF-RTE)
• AFAPL2 Development Kit

NOTE: As of version 1.1.0 of the AF Run Time Environment, the Actuator, Perceptor, and Module base classes have been moved to a new package: com.agentfactory.logic.agent and have been moved to the Logic API. Details of this API can be found in The Logical Agent API Guide

The example code below is based on a prior version of Agent Factory, and has not yet been updated to reflect the new package structure. Backwards compatibility with this prior version is discussed in the Compatibility API Guide.

Implementing an Action

To implement an action, we must do two things: first, we need to create an actuator that contains the implementation of the action. After this, we need to specify our action in an AFAPL2 file, using the ACTION construct.

So, lets start with the actuator. Actuators are - Java classes that subclass the com.agentfactory.platform.interfaces.Actuator class and implement the act(..) method. Upon creation, the agent creates on instance of each specified actuator. Thus, the same instance is used even when the action is being performed concurrently. Consequently, actuators must be implemented as thread-safe classes.

To illustrate how to create an actuator, we will develop a "helloWorld" action that prints the String "Hello World" to the console. After this, we will explore a slightly more complex version of "helloWorld" that includes some more advanced features of actuator implementations.

import com.agentfactory.platform.interfaces.Actuator;
import com.agentfactory.platform.logic.FOS;

public class HelloWorldActuator extends Actuator { 
   public boolean act( FOS action ) {
        System.out.println( "Hello World" );
        return true; 
    }
}

What the above actuator implementation does is fairly obvious. The only "issue" is the return value of an actuator. This is used to define whether the commitment to the corresponding action failed or succeeded. It is useful where it is possible for the actuator to complete unsuccessfully, for example, updating a table in a database. In such cases, the actuator can indicate its failure by returning false instead of true.

Before we create an example AFAPL2 program to illustrate how to use this actuator, we must compile it (as before, you may need to include the af_platform.jar file in the calss path). To do this, open a command prompt, change the directory to be the one containing the Java class (e.g. d:\quickstart) and type in the following line:

javac -cp .;d:\agentfactory\lib\af_rte.jar HelloWorldActuator.java

If you're using Linux, the command will look like this:

javac -cp .:/usr/lib/agentfactory/lib/af_rte.jar HelloWorldActuator.java

In each case, you should ensure that the path to af_rte.jar is correct for your installation.

Now you have compiled your first actuator.

Next, we need to create an AFAPL2 agent program, which will be stored in a file named "helloworld.afapl2" (again use a text editor to do this). This program contains two parts: an action definition and a commitment that will cause the agent to perform that action. The action definition specifies an action called "helloWorld" and links the action to the HelloWorldActuator. In addition, this definition requires that you specify any pre and post conditions that apply to the action.

Pre-conditions are used to ensure that the action is only performed when it is possible, for example a robot soccer agent program may include a "kick" action. The pre-condition for this action would be that the agent has the ball (i.e. BELIEF(hasBall) ). Conversely, post-conditions are used to identify which actions can be used to achieve the goals of the agent. How to do this will be described later in this guide. For this example, we will declare both the pre- and post- condition of our action to be true (this is a default that means "no precondition or postcondition").

The second part of the program is a commitment declaration that will be added to the initial commitments of the agent. This commitment specifies that the agent has made a commitment to itself, at the current time point, to perform the action "helloWorld". The third parameter of the COMMIT statement (shown in the code fragment below) is the maintenance condition. This condition defines what beliefs must remain true for the agent to maintain its commitment to the action. If the condition becomes false at any time, then the agent will fail the commitment (i.e. it is equivalent to an actuator returning false).

ACTION helloWorld {
    PRECONDITION BELIEF(true);
    POSTCONDITION BELIEF(true);

    CLASS HelloWorldActuator;
}

COMMIT(?self, ?now, BELIEF(true), helloWorld);

Once you have created the "helloworld.afapl2" file you must complete the process by compiling it into a ".agent" file. This second type of file is used to deploy the agent.

To compile a ".afapl" file into a ".agent" file use the AFAPL2 compiler in the same command prompt that you used to compile the Java file:

afapl2c helloworld.afapl2

To deploy an instance of our newly created agent program, we need to create (use) two addtional files: the platform configuration file (a file with a ".cfg" extension) and the agent platform script file (a file with a ".aps" extension). For the purposes of this example, we have provided an example platform configuration file [1] here. Download this file, and save it in the "quickstart" folder (i.e. the same folder as HelloWorldActuator.java and alive.afapl2).

The second file you need to create is the agent platform script file. This file is used to specify the initial set of agents that will be created when the agent platform is started. For the purposes of our example, this script should contain the following:

CREATE_AGENT hello helloworld.agent

To create this file, again use your text editor, and save the file as "helloworld.aps".

You are now ready to deploy your first agent!

To do this, you simply need to start up an agent platform, passing the platform.cfg and alive.aps files as parameters, using the following command:

agentfactory -s alive.aps -c platform.cfg -f

This should also cause the Agent Factory Debugger to be started, giving you the following graphical interface:

Double-click on myfirstagent to get the controller view for that agent, and select the Commitments tab - it should look like this:

Finally, to run your first agent, simply click the "Start" button (either the one at the top, or the one in the agent controller view). This should result in the commitment being removed from the agents commitment set. If you check the console, you should see that the "Hello World" message has been printed out.