Introduction
This document briefly describes how to use the MOISE platform based on CARTAGO. It follows the new approach to implement OMI (Organisation Management Infrastructure): based on a normative language and artifacts. The conceptual view of this approach is presented in [cite:hubner09e], which is strongly based on ORA4MAS [cite:hubner09c].
A brief history of MOISE OMIs
-
S-MOISE: a tier based centralised proposal. It adds an organisational layer on top of the communication layer. Agents use this new layer to interact/coordinate/…. It is centralised due a component called OrgManager that manages all the organisational layer [cite:hubner05a].
-
SYNAI: an extension of S-MOISE with context specification and more suitable normative specification [cite:gateau07].
-
J-MOISE (for S-MOISE): is the integration of S-MOISE for Jason agents [cite:hubner07].
-
J-MOISE (for ORA4MAS): an integration of ORA4MAS with Jason similar to J-MOISE (for S-MOISE). This project was discontinued, Jason agents access organisational artifacts as any other artifact.
-
ORA4MAS: the OMI based on artifacts. In the initial version the organisational artifacts are implemented in Java [cite:hubner09c]. In a more recent version, the artifacts are programmed in NPL (Normative Programming Language) [cite:hubner10b].
Organisational Artifacts Specification
Two main kinds of artifacts are implemented: GroupBoard
and
SchemeBoard
. The usage interface (operations, observable
properties, and signals) of them are available in the following links
-
Group API and
-
Scheme API respectively.
Java integration
There is a generic GUI to create organisational artifact and agents enabling the user to test the specification. To run it:
gradle intsim
We can then set the organisational specification for the system and create groups, schemes, and generic GUI based agents.
You can also read the code of a simulator to learn how to program Java agents to use these artifacts. The source is available here and can be run with
gradle sim
Jason Integration
Organisational actions
The actions are the action provided by the OrgArts like adoptRole
and commitMission
, etc.
Organisational perception
Observable properties of the artifacts (which are Java objects) are
mapped to the beliefs inside agents by Cartago-Jason bridge. All of
them are annotated with artifact(artifact id)
as shown
in the mind inspector:
The beliefs are the following (see API documentation of artifacts for more details):
-
specification(….)
for groups -
specification(….)
for schemes -
play(agent, role, group)
-
commitment(agent, mission, scheme)
-
goalState(scheme, goal, list of committed agents, list of agent that performed the goal, state of the goal)
-
obligation(agent,norm,goal,deadline)
: the current active obligations. -
others (see observable properties of the artifacts)
The following signals are also translated to Jason events (see the organisational artifacts specification for more details):
-
oblCreated(obligation)
: the state of the obligation is changed to created -
oblFulfilled(obligation)
-
oblUnfulfilled(obligation)
-
oblInactive(obligation)
-
normFailure(details)
: some norm failure is thrown. -
destroyed(artifact id)
: the artifact was destroyed.
Example
We use the traditional writing paper example to illustrate the use of Jason - ORA4MAS integration [cite:hubner09c]. In this example we have three agents:
-
Bob: will create one group, and two schemes to write two papers. He adopts the role editor in the group and the mission mManager in the schemes.
-
Alice: this agent waits for the group creation and then adopts the role writer and commits to the missions mColaborator and mBib.
-
Carol: this agent also waits for the group creation and then adopts the role writer and commits to the mission mColaborator.
The Jason project is:
/*
(Traditional) Writing paper example
to be run as a JaCaMo application
by Jomi (2010)
*/
mas wp {
agent bob
agent alice
agent carol
}
The code of the agents follows.
// This agent creates the group/scheme to write a paper
// and adopts the role "editor" in the group
my_role(editor).
{ include("common.asl") }
/* Initial goals */
!create.
/* Plans */
+!create
<- .my_name(Me);
createWorkspace(ora4mas);
joinWorkspace(ora4mas,O4MWsp);
makeArtifact(myorg, "ora4mas.nopl.OrgBoard", ["../wp-os.xml"], OrgArtId)[wid(O4MWsp)];
focus(OrgArtId);
createGroup("mypaper", wpgroup, GrArtId);
debug(inspector_gui(on))[artifact_id(GrArtId)];
setOwner(Me);
.print("group created");
// wait for alice
?play(alice,writer,mypaper);
// wait for carol
?play(carol,writer,mypaper);
!run_scheme(sch1).
//+group(_,_,AID) <- focus(AID).
//+scheme(_,_,AID) <- focus(AID).
// general error handler for goal start
-!start[error(I),error_msg(M)] <- .print("failure in starting! ",I,": ",M).
+!run_scheme(S)
<- createScheme(S, writePaperSch, SchArtId);
debug(inspector_gui(on))[artifact_id(SchArtId)];
.print("scheme ",S," created");
addScheme(S)[artifact_name("mypaper")];
.print("scheme is linked to responsible group");
commitMission(mManager)[artifact_id(SchArtId)].
-!run_scheme(S)[error(I),error_msg(M)] <- .print("failure creating scheme ",S," -- ",I,": ",M).
// application domain goals
+!wtitle <- .wait(500); .print("writing title...").
+!wabs <- .print("writing abstract...").
+!wsectitles <- .print("writing section title...").
+!wconc <- .print("writing conclusion...").
+!wp <- .print("paper finished!").
+goalState(sch1, wp, _, _, satisfied)
<- .wait(1000);
destroyScheme(sch1);
.print("starting a new scheme...");
!!run_scheme(sch2).
+?play(A,R,G) <- .wait({+play(_,_,_)},100,_); ?play(A,R,G).
// signals
+normFailure(N) <- .print("norm failure event: ", N).
+destroyed(Art) <- .print("Artifact ",Art," destroyed").
// for debug (prints out the new states of goals)
//+goalState(Sch,Goal,CommittedAgs,AchievedBy,State)
// <- .print(" goal changed: ", goalState(Sch,Goal,CommittedAgs,AchievedBy,State)).
{ include("$jacamoJar/templates/common-moise.asl") }
{ include("$jacamoJar/templates/org-obedient.asl") }
The first included file is listed below. The last two are part of the JaCaMo distribution and are available here and here.
/* Initial goals */
!play.
!join.
/* Plans */
+!play
<- lookupArtifact("mypaper",GrId);
?my_role(R);
adoptRole(R)[artifact_id(GrId)];
focus(GrId).
-!play
<- //.print("waiting to play a role");
.wait(100);
!play.
+!join : joined("ora4mas",_).
+!join
<- joinWorkspace("/main/ora4mas",_).
-!join
<- .print("waiting to join ora4mas");
.wait(200);
!join.
+!quit_mission(M,S)
<- .print("leaving my mission ",M," on ",S,"....");
leaveMission(M)[artifact_name(S)].
// this agent waits for the group creation and then
// adopts the role writer and
// commits to the missions mColaborator and mBib
my_role(writer).
{ include("common.asl") }
/* Plans */
// application domain goals
+!wsecs <- .print("writing sections...").
+!wrefs <- .print("organising bibliography...").
// conditions to leave missions
@lgss1[atomic]
+goalState(Scheme,wsecs,_,_,satisfied)
: .my_name(Me) & commitment(Me,mColaborator,Scheme)
<- !quit_mission(mColaborator,Scheme).
@lgss2[atomic]
+goalState(Scheme,wrefs,_,_,satisfied)
: .my_name(Me) & commitment(Me,mBib,Scheme)
<- !quit_mission(mBib,Scheme).
{ include("$jacamoJar/templates/common-moise.asl") }
{ include("$jacamoJar/templates/org-obedient.asl") }
// this agent waits for the group creation and then
// adopts the role writer and
// commits to the mission mColaborator
my_role(writer).
{ include("common.asl") }
/* Plans */
// application domain goals
+!wsecs[scheme(S)]
<- .print("writing sections for scheme ",S,"...").
// when my goal in the scheme is satisfied, leave my mission
@lqm[atomic]
+goalState(Scheme,wsecs,_,_,satisfied)
: .my_name(Me) & commitment(Me,mColaborator,Scheme)
<- !quit_mission(mColaborator, Scheme).
// plans to handle obligations
// only commits to mColaborator!
+obligation(Ag,Norm,committed(Ag,mColaborator,Scheme),Deadline)[artifact_id(ArtId),workspace(_,_,W)]
: .my_name(Ag)
<- .print("I am obliged to commit to mColaborator on ",Scheme,"... doing so");
commitMission(mColaborator)[artifact_name(Scheme), wid(W)].
+obligation(Ag,Norm,committed(Ag,Mission,Scheme),Deadline)
: .my_name(Ag)
<- .print("Ignoring obligation to commit to ",Mission," on ",Scheme).
{ include("$jacamoJar/templates/common-moise.asl") }
{ include("$jacamoJar/templates/org-obedient.asl") }