CLF::EIS Manager Module

From Agent Factory

This library provides support for management of environments implemented using the Environment Interface Standard. To use this library, you must first install the EIS Platform Service. It can be used with any agent that is implemented using a language that is based on the Common Language Framework. All of the examples provided on this page are based on AF-AgentSpeak. Details of other libraries provided with the Common Language Framework can be found here.

Installing the Library

To use the EIS Manager Module, you must modify your run configuration to install the EIS Platform Service as is shown below:

import com.agentfactory.agentspeak.interpreter.AgentSpeakArchitectureFactory;
import com.agentfactory.agentspeak.debugger.AgentSpeakStateManagerFactory;
import com.agentfactory.agentspeak.debugger.inspector.AgentSpeakInspectorFactory;
import com.agentfactory.visualiser.DebuggerRunConfiguration;

public class Main {
    public static class MyConfig extends DebuggerRunConfiguration {
        public String getName() {
            return "helloworld";
        }

        public String getDomain() {
            return "ucd.ie";
        }

        public void configure() {
            addLanguageSupport(new AgentSpeakInspectorFactory(), new AgentSpeakStateManagerFactory());
            super.configure();
            addArchitectureFactory(new AgentSpeakArchitectureFactory());

            addPlatformService(EISService.class, "eis");
 
            addAgent("eissy", "myeisagent.aspeak");
        }
    }

    public static void main(String[] args) {
        new MyConfig().configure();
    }
}

Once the platform service has been installed, you can use the library by adding the following line to your AgentSpeak program:

module eis -> com.agentfactory.eis.EISManagerModule;

All actions may then be accessed by using the prefix "eis". This is because you associated the library with this identifier. If you change the module identifier, then any action call must be prefixed by the new identifier.

Actions

This module provides actions to allow the agent to access the environment management functionality of the Environment Interface Standard.

#agent example

module eis -> com.agentfactory.eis.EISManagerModule;

+initialized : true <-
    eis.setup(eis, vacworld.jar, []);

#agent example

module eis -> com.agentfactory.eis.EISManagerModule;

+initialized : true <-
    eis.setup(eis, vacworld.jar, []);

+eisState(paused) : ~eis(paused) & eisSupports(start) <-
    eis.start;

#agent example

module eis -> com.agentfactory.eis.EISManagerModule;

+initialized : true <-
    eis.setup(eis, vacworld.jar, []),
    ?list = eis.getFreeEntities,
    forall(?name:?list) {
        .println("There is an entity called: " + ?name)
    };

+freeEntity(?name) : true <-
    .println("I believe there is a free entity called: " + ?name);

#agent example

module eis -> com.agentfactory.eis.EISManagerModule;

+initialized : true <-
    eis.setup(eis, vacworld.jar, []),
    ?list = eis.getFreeEntities,
    forall(?name : ?list) {
        ?type = eis.getEntityType(?name),
        .println("There is a free entity called: " + ?name + " with type: " + ?type)
    };

Sensors

Sensors provide beliefs that the agent can use to make decisions about how best to act. The Core API comes with a number of default sensors that are listed below.

Examples

The default use of the EIS Management API is as part of the EIS Management Agent. This agent is responsible for configuring and monitoring the attached EIS environment. Typically, it is expected that any EIS user will not need to modify this agent, but instead, they will simply use it as part of their deployment. In this section, we give the code for this agent. We do so for two reasons: so that the operation of this agent is well understood, and so as to illustrate how the EIS Manager API is used in practice.

#agent EnvironmentManager

module ams -> com.agentfactory.clf.library.AMSLibrary;
module eis -> com.agentfactory.eis.EISManagerModule;

+initialized : environment(?pid, ?jarfile) <-
    ams.setup,
    ?params = [],
    if (parameter(?x)) ?params = list[ ?x | parameter(?x) ]
    eis.setup(?pid, ?jarfile, ?params),
    eis.getFreeEntities;
	
+eisState(paused) : ~eis(paused) & eisSupports(start) <-
    eis.start;

+newEntity(?entity) : ~design(?entity, ?design) <-
    eis.getEntityType(?entity),
    foreach(entityType(?entity, ?entityType) & design(?entityType, ?design)) {
        ams.create(?entity, ?design),
        ams.resume(?entity)
    };
	
+newEntity(?entity) : design(?entity, ?design) <-
    ams.create(?entity, ?design),
    ams.resume(?entity);

+freeEntity(?entity) : ~design(?entity, ?design) <-
    eis.getEntityType(?entity),
    foreach(entityType(?entity, ?entityType) & design(?entityType, ?design)) {
        ams.create(?entity, ?design),
        ams.resume(?entity)
    };

+freeEntity(?entity) : design(?entity, ?design) <-
    ams.create(?entity, ?design),
    ams.resume(?entity);

The main responsibilities of this agent are:

• To configure the EIS Service for the relevant environment.
• To create the agents that will control the entities present in the environment.

The former of these responsibilities is handled via the initial rule, which simply sets up the EIS Manager API and the AMS API, and then queries the environment for any free entities.

The second responsibility involves creating agents to control any of the free entities identified by the free entities query, and also creating agents for any entities that are created as the environment evolves. In reality, these options represent two possible design strategies for developers of EIS environments, and so, must both be supported to ensure compliance.

The creation of agents to control free entities is further complicated by the typing system employed by EIS. This feature of EIS associates a string type with every entity. The manager agent is able to use the EIS Manager API to query the environment as to the entities type. Again, some environments specify types for entities, while others do not (EIS best practice seems to be that you should, but this is not enforced). As a result, the EIS Management Agent must be able to create entities either by name or by type.

The result of this is that there are 4 rules devoted to creating agents to control entities: 2 rules for dealing with free entities, and 2 rules for dealing with new entities. For both cases, one rule deals with creating agents based on the entity name, and one rule deals with creating agents based on the entity design. The rules dealing with the entity by name are written before those dealing with entity type as this gives precedence to name based mappings over type based mappings.

To use the above agent, you must modify your run configuration to add the agent and give the agent initial beliefs relating to the entities you want to create:

import com.agentfactory.agentspeak.interpreter.AgentSpeakArchitectureFactory;
import com.agentfactory.agentspeak.debugger.AgentSpeakStateManagerFactory;
import com.agentfactory.agentspeak.debugger.inspector.AgentSpeakInspectorFactory;
import com.agentfactory.visualiser.DebuggerRunConfiguration;

public class Main {
    public static class MyConfig extends DebuggerRunConfiguration {
        public String getName() {
            return "helloworld";
        }

        public String getDomain() {
            return "ucd.ie";
        }

        public void configure() {
            addLanguageSupport(new AgentSpeakInspectorFactory(), new AgentSpeakStateManagerFactory());
            super.configure();
            addArchitectureFactory(new AgentSpeakArchitectureFactory());

            addPlatformService(EISService.class, "eis");
 
            addAgent("manager", "com/agentfactory/eis/EnvironmentManager.aspeak");
            initAgent("manager", "environment(eis, \"vacworld.jar\")");
            initAgent("manager", "design(vacbot, \"VacBot.aspeak\")");
        }
    }

    public static void main(String[] args) {
        new MyConfig().configure();
    }
}

In the above example, we create a manager that will be linked to the VacWorld environment and associate any entity of type "vacbot" with the "VacBot.aspeak" agent program. It is also possible to define entity names here, in which case a specific entity will be associated with a specific agent program.