What you’ll build
This programming tutorial illustrates the programming of agents' organizations in a multi-agent system.
You will use and program a normative organization coordinating and regulating the cooperation among autonomous agents interacting in the shared environment.
What you’ll need
-
A favorite text editor or IDE
-
JDK 1.8 or later
-
A JaCaMo platform installed and configured
-
To have done the JaCaMo Hello World Tutorial Step by step walk in programming multi-agent environment
In this tutorial, you will program a multi-agent system where agents are operating under an agents' organization and within a shared environment deployed on multiple machines.
The code is organized into two JaCaMo project files ( |
-
The whole code of this tutorial (it contains all the necessary code for each of the following steps) is available Download ZIP. If you prefer, you can also download each particular piece of code in each of the corresponding step.
STEP 1. Creating a MAS with a simple Agents' organization
-
Get the code used in step 1: Download ZIP
Learned features
In this step, you will learn:
|
Understand
We are considering the multi-agent system developed in Step by step walk in programming multi-agent environment tutorial.
The aim is to install some coordination among the agents for using the artifacts in a proper sequence.
easss_org
:An agents' organization to define an explicit and changeable coordination pattern among the agents.
The organization is programmed in the org-spec.xml
file.
It is composed by:
-
a
structural specification
that defines a groupeasssGr
withgreeter
,observer
andcomputer
roles that can be played by the agents participating to groups of this type, -
a
functional specification
that defines and plans the performance goalscompute
,greeting
andobserve
to be achieved by the agents.It structures them into a set of missions
mCompute
,mGreeting
andmObserve
-
a
normative specification
that assigns in a straightforward way obligations to each role and mission
org_agent.asl
-
This type of agent enters the organization and adopts one of the roles of organization
-
For now this agent is obedient w.r.t. the duties it receives from the organization given its role.
As we can see, in this application, agents have all the necessary skills to realize any goal coming from the missions of the organization.
user_agent.asl
-
This agent is focused on two GUI artifacts
Scheme Console
andGroup Console
.As the
org_agent
, it has the necessary skills to realize any goal defined in the organization. -
Thanks to these two GUI artifacts, you, as user, will be able to interact with the MAS system as if you were an agent of the organization, in order to enter some group, adopt/leave some role, commit/leave some mission, etc.
server.jcm
and client.jcm
project filesThese two jacamo project files are used to distribute agents, artifacts and the organization in the deployed multi-agent system
-
The
server.jcm
creates aserver
workspace and deploys artifacts and agents in it -
The
server.jcm
creates also theeasss_org
organization from theorg-spec.xml
(the organization artifacts in charge of its management are deployed in theeasss_org
workspace) -
The
client.jcm
creates aclient
workspace and deploys artifacts and agents both in this workspace and in theserver
workspace.The agents will also join the
server
workspace to use artifacts that are deployed in it.They will also adopt some roles in the organization.
Practice
-
To ease the test, you can define a group of three to four students, each in interaction with an agent of type
user_agent
.Enter the organization and fulfill your obligations.
-
Take care to follow the life cycle of the organization as defined by the MOISE framework.
Thanks to the GUI artifact, you can decide to adopt a role, to commit to a mission, to declare the achievement of some goal, etc.
-
Use the
agent inspector
to monitor the evolution of the mental state of the agent, or theorganization inspector
to inspect the evolution of the organization state in the Group boards and Scheme boards, to detect the violations
It is also interesting to inspect the mind of the agents to see the beliefs produced by the organisation (The complete description of the observable properties of organisational artifacts are found in MOISE API)
-
Change the specification of the organisation (e.g. cardinality of roles, order of the goals, …) and see how it changes the functionning of the agents
-
Modify the organisation specification in order to force to have at least two agents playing the role
greeter
in the group -
Modify the organisation specification so that the role
greeter
is obliged to commit to missionmCompute
(after testing, undo your change)
STEP 2. Making agents create their own organization from a specified organization program
-
If you didn’t realize previous step, you can get the code used in this step: here (zip) otherwise just use the result of previous step
Learned features
In this step, you will learn:
|
Understand
-
We reuse the previous example and refactor it, so that, agents create their own organization.
Instead of creating the agents' organization in the
.jcm
files, agents get back some power to decide on the way their organization is deployed.
-
In order to deploy the organization, one has first to create the workspace in which will be placed the artifacts in charge of the management of the organization.
createWorkspace(...); joinWorkspace(...);
-
Then, one has to create in this workspace (use of annotation
wid()
), the main artifact of typeora4mas.nopl.OrgBoard
that stores all the groups and schemes that are taking place in the organization.The program of the organization is stored in
./src/org/org-spec.xml
(this path has to be given at the initialization of the artifact)
makeArtifact(...,"ora4mas.nopl.OrgBoard", ["src/org/org-spec.xml"], OrgArtId)[wid(WOrg)]; focus(OrgArtId)[wid(WOrg)];
-
Then arrives the creation of group (with eventually the way to monitor and debug this structure)
createGroup(Gname, easssGr, GrArtId); debug(inspector_gui(on))[artifact_id(GrArtId)]; focus(GrArtId)[wid(WOrg)];
For each creation of group, one has to use this operation createGroup
* And finally, the creation of schemes:
// create the scheme createScheme(Schname, easssSch, SchArtId); debug(inspector_gui(on))[artifact_id(SchArtId)]; focus(SchArtId)[wid(WOrg)];
-
In order to enables agents participating to a group, to commit to missions of a social scheme, the group must become responsible of the deployed social scheme.
This can be done only and only when the group is well formed (i.e. when all the constraints on minimal number of agents playing a role are satisfied).
-
As soon as the group is well formed, a new belief
formationStatus
is generated into the agent’s belief base
-
?formationStatus(ok)[artifact_id(GrArtId)];
-
The internal action
.wait
enables to wait till some condition is fulfilled (e.g. production of a belief about the formation status from a group)-
From the moment the group becomes responsible of the scheme, agents that are playing roles in this group, have the possibility to commit to missions of the scheme under the responsibility of the group.
-
addScheme(Schname)[artifact_id(GrArtId)];
-
Entering of agents in the organization is realized by adopting a role in a group of an organization (remind that you can get the Id of a group with
lookupArtifact
with a specific name in the organization workspace)
lookupArtifact(Group,GroupId)[wsp("easss_org")]; adoptRole(Role)[artifact_id(GroupId)];
You may have a look at the code of org_agent
which is realizing some very simple automated reasoning and actions on the organization
Practice
-
Create an
org_majordomo
agent that will realize the deployment of the organization following the different steps described above -
Refactor the code in accordance
STEP 3. Reasoning on the Organization
-
If you didn’t realize previous step, you can get the code used in this step here (zip) otherwise just use the result of previous step
Learned features
In this step, you will learn:
|
Undestand
obligation(ag,reason,goal,deadline)
-
oblCreated(o): the obligation o is created.
-
oblFulfilled(o): the obligation o is fulfilled
-
oblUnfulfilled(o): the obligation o is unfulfilled (e.g. by timeout).
-
oblInactive(o): the obligation o is inactive (e.g. its maintenance condition does not hold anymore).
e.g. o = obligation(Ag,,done(Sch,bid,Ag), TTF) if the bid is a performance goal and o = obligation(Ag,,satisfied(Sch,bid), TTF) if the bid is an achievement goal.
-
normFailure(f): the failure f has happened (e.g. due some regimentation).
e.g. f = fail(mission_permission(Ag,M,Sch)).
The f comes from the normative program.
-
Fulfilling an obligation for a mission means committing to that mission in the given time constraint
-
Fulfilling an obligation for a goal means achieving that goal in the given time constraint
-
as soon as an obligation is fulfilled, the signal
oblFulfilled
is generated by the artifacts -
as soon as an obligation is unfulfilled, the signal
oblUnfulfilled
is generated by the artifacts (e.g. deadline of a goal has not been satisfied)
oblUnfulfilled(obligation)[artifact_id(AId)]
Practice
-
Write a plan so that the agent adopts the chosen role as soon as the group has been created (i.e. the corresponding groupBoard artifact has been deployed)
-
Write a plan so that the agent leaves its current role as soon as another agent adopts the same role in his/her group and the group is not yet well formed. After leaving the agent adopts another role.
-
Add a plan in the agent’s code so that this agent is an obedient one: as soon as one obligation, that concerns it, is created, it fullfills the obligation
-
Add a plan in the agent’s code so that each time an agent of its group fulfills an obligation, it broadcasts a message in order to increase the reputation of that agent