A step by step walk in programming multi-agent organisation

What you’ll build

This tutorial illustrates the programming of agents' organisations in a multi-agent system.

You will use and program a normative organisation coordinating and regulating the cooperation among autonomous agents interacting in the shared environment.

In this tutorial, you will program a multi-agent system where agents are operating under an agents' organisation and within a shared environment that may be deployed on multiple machines. The code is organized into two JaCaMo project files (.jcm): one for the server workspace, one for the client one.

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

Code

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.

1. Creating a MAS with a simple Agent organisation

Download the code used in step 1 (initial and solution) Download ZIP

Learned features in this step

How to use the organisation specification
What is the life cycle of an organisation
How to change and define organisation specification

1.1. Explanations

We are considering the multi-agent system developed in the 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.

A simple organisation easss_org:

An agent organisation defines an explicit and changeable coordination pattern among the agents. Programmed in the org-spec.xml file, it is composed by:

a structural specification that defines a group easssGr with three roles: greeter, observer and computer. These roles can be played by the agents when participating to a group of this type,
a functional specification that defines and plans the performance goals compute, greeting and observe to be achieved by the agents.

It structures them into the mCompute, mGreeting and mObserve missions.
a normative specification that assigns in a straightforward way obligations to each role and mission

The org_agent.asl agent program:

The program has plans to enter the organisation, to adopt one of the roles of the organisation
For now this agent is obedient w.r.t. the duties it receives from the organisation given its role.
The agent has all the necessary skills to achieve any goal coming from the missions of the organisation (cf. file skills.asl in subfolder inc of folder src/agt)

The user_agent.asl agent program:

The program has plans to focus on Scheme Console and Group Console GUI artifacts.

As the org_agent, it has the necessary skills to realize any goal defined in the organisation.
The two GUI artifacts are used by the agent to interact with the user. You will use them to act as an agent: entering some group in the organisation, adopt/leave some role, commit/leave some mission, etc.

The server.jcm file

These two jacamo project files are used to distribute agents, artifacts and the organisation in the deployed multi-agent system

The server.jcm creates a server workspace and deploys artifacts and agents in it
The server.jcm creates also the easss_org organisation from the org-spec.xml (the organisation artifacts in charge of its management are deployed in the easss_org workspace)


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

  mas server {
    agent majordomo {
          join: server
    }

    workspace server {
       artifact msg_console: tools.GUIConsole()
       artifact calculator: tools.Calculator()
       artifact lock: tools.Lock()
       artifact barrier: tools.Barrier(3)
    }

    organisation easss_org : org-spec.xml {
       group easss_team : easssGr {
             responsible-for : easss_sch
             debug  // used to create group inspector
       }
       scheme easss_sch : easssSch {
             debug // used to create scheme inspector
       }
    }

    // agent source path
    asl-path: src/agt
              src/agt/inc
    // main node
    platform: cartago("infrastructure")
}

The client.jcm file

The client.jcm creates a client workspace and deploys artifacts and agents both in this workspace and in the server 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 organisation.


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

  mas client {

    agent user_agent {
            instances:   1
    }

    agent user2 : org_agent.asl {
        join: server @ servernode
        roles: greeter in easss_org.easss_team @ servernode
    }

    agent user3 : org_agent.asl {
        join: server @ servernode
        roles: computer in easss_org.easss_team @ servernode
    }

    // java class path
    class-path:  lib

    // agent source path
    asl-path: src/agt
              src/agt/inc

    platform: cartago()
    node servernode running @ localhost
}

1.2. Practice

To ease the test, you can define a group of three to four students.

One student launch the server workspace (server.jcm). All students launch a client workspace and act on the GUI Artifact to participate to the organisation.

Enter the organisation and fulfill your obligations.
Take care to follow the life cycle of the organisation 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 the organisation inspector to inspect the evolution of the organisation 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, …) by editing the file easss_org.xml and see how the functioning of the agents changes
Modify the organisation specification so that at least two agents play the role greeter in the group
Modify the organisation specification so that the role greeter is obliged to commit to mission mCompute (after testing, undo your change)

2. Making agents create their own organisation from a specified organisation 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

How to program agents able to deploy organisation defined in an organisation specification file

2.1. Explanations

We reuse the previous example and refactor it, so that, agents create their own organisation.

Instead of creating the agent organisation in the .jcm files, agents have the necessary plans to decide on the way their organisation is deployed.

Don’t forget to change the .jcm file in accordance to your changes

Create the organisation

In order to deploy the organisation, create the workspace in which will be placed the organisational artifacts in charge of the management of the organisation.
```
  1
2

  createWorkspace(...);
joinWorkspace(...);
```
The name of this workspace can be the name chosen for the organisation.
Then, create in this workspace the organisational artifact OrgBoard (type is ora4mas.nopl.OrgBoard). The OrgBoard stores all the groups and schemes that are composing the organisation. In order to create it, use wid() with the id of the created workspace, to annotate the makeArtifact action.

The program of the organisation is stored in ./src/org/org-spec.xml (this path has to be given when initializing the artifact)
```
  1
2

  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)


  1
2
3

  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:


  1
2
3
4

  // create the scheme
createScheme(Schname, easssSch, SchArtId);
debug(inspector_gui(on))[artifact_id(SchArtId)];
focus(SchArtId)[wid(WOrg)];

In order to enable 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
- Use a the test goal ?formationStatus to test the presence of this belief in the belief base of the agent
  1 ?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)

The operation addScheme is used to make a group GrArtId responsible of a scheme Schname


  1

   addScheme(Schname)[artifact_id(GrArtId)];

From the time 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.

Make agents adopt roles

Entering of agents in the organisation is realized by adopting a role in a group of an organisation (remind that you can get the Id of a group with lookupArtifact with a specific name in the organisation workspace)
```
  1
2

  lookupArtifact(Group,GroupId)[wsp("easss_org")];
adoptRole(Role)[artifact_id(GroupId)];
```
You may have a look at the code of org_agent.asl which is realizing some very simple automated reasoning and actions on the organisation

2.2. Practice

Create an org_majordomo agent that will realize the deployment of the organisation following the different steps described above
Refactor the code of the jcm file in accordance

properties observed from an organisation

the group groupId of type groupType exists in the organisational entity and is accessible with ArtId

group(groupId, groupType, Artid)

the social scheme schemeId of type schemeType exists in the organisational entity and is accessible with ArtId

scheme(schemeId, schemeType, ArtId)

The organisation specification in a prolog like representation.

specification(...)

properties observed from a group:

Agent ag is playing the role in the group.


  1

  play(ag,role,group)

list of social scheme entities the group is responsible for
```
  1

  schemes(...)
```
group definition from the structural specification (a prolog like representation)
```
  1

  specification(...)
```
list of subgroups ids
```
  1

  subgroups(...)
```

id of the parent group (used in subgroups)


  1

  parentgroup(id)

whether the group is well-formed (values are ok and nok)


  1

  formationStatus(V)

properties observed from a social scheme:

agent ag is committed to the mission in the social scheme sch (we have as many obs prop as commitments). e.g. commitment(bob,mission1,s1)
```
  1

  commitment(ag,mission,sch)
```
list of group entities responsible for the scheme. e.g. groups([g1])
```
  1

  groups(...)
```

current state of goal in the scheme schId where possible states are: waiting, enabled, satisfied). e.g. goalState(s1,g5,[alice,bob],[alice],satisfied)


  1

  goalState(schId, goal, list of committed agents, list of agents that performed the goal, state)

specification of the scheme in the organisation specification (a prolog like representation).
```
  1

  specification(...)
```

current active obligations. e.g. obligation(bob,ngoal(s1,mission1,g5),done(s1,bid,bob),1475417322254)


  1

  obligation(ag,reason,goal,deadline)

current active permission.


  1

  permission(ag,reason,goal,deadline)

value of goals' arguments, defined by the operation setArgumentValue e.g. goalArgument(sch1, winner, "W", "Bob")


  1

  goalArgument(schemeId, goalId, argId, value)

operations to act on an organisation:

Create (resp. destroy) a group entity in the organisation entity


  1
2

  createGroup
destroyGroup

Create (resp. destroy) a social scheme entity in the organisation entity


  1
2

  createScheme
destroyScheme

operations to act on a group:

to try to adopt (resp. leave) a role in the group entity. If the action is successful the agent will adopt (resp. leave) the role otherwise an event is generated.
```
  1
2

  leaveRole
adoptRole
```
to try to add (resp. remove) a scheme to (resp. from) the responsibilities of the group entity
```
  1
2

  addScheme
removeScheme
```
to try to add a group entity as parent group of the group entity
```
  1

  setParentGroup
```
to try to add an agent id as owner of the group entity.
```
  1

  setOwner
```
to try to delete the group entity.
```
  1

  destroy
```

operations to act on a social scheme:

to try to commit (resp. leave) a mission.


  1
2

  commitMission
leaveMission

to try to change the status of a goal to satisfied.
```
  1

  goalAchieved
```

to try set the values of the arguments of a goal.


  1

  setArgumentValue

to try to reinitialize the status of a goal to enabled.
```
  1

  resetGoal
```
to try to delete the social scheme entity.
```
  1

  destroy
```
to try to add an agent id as owner of the social scheme entity.
```
  1

  setOwner
```

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

How to do some basic reasoning on the organisation

3.1. Explanations

When executing in an agent organisation, the agents who play some roles in it receive obligations and permissions to commit to missions.

Once committed to a mission (either an obliged or permitted mission), they receive signals corresponding to obligations to achieve goals when those goals become active.

Fulfilling an obligation

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

Knowing that an obligation has been fulfilled

as soon as an obligation is fulfilled, the signal oblFulfilled is generated
as soon as an obligation is unfulfilled, the signal oblUnfulfilled is generated (e.g. deadline of a goal has not been satisfied)

These signals are:


  1

  obligation(to whom, maintenance condition, what, deadline)

the obligation o is created.
```
  1

  oblCreated(o)
```

the obligation o is fulfilled


  1

  oblFulfilled(o)

the obligation o is unfulfilled (e.g. by timeout).


  1

  oblUnfulfilled(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.
```
  1

  oblInactive(o)
```
the failure f has happened (e.g. due to some regimentation).

e.g. f = fail(mission_permission(Ag,M,Sch)).

The f comes from the normative program.
```
  1

  normFailure(f)
```

3.2. Practice

Adopting/Leaving roles

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.

Make an obedient agent

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

Manage the reputation of an agent

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