Practical work on Organisation Oriented Programming

In this part of the tutorial, you will learn how to program organizations using the MOISE organization language and platform. You will also learn how to program agents able to take into account the organization in their internal reasoning process.

Configuration

In order to realize the following exercises on organization oriented programming in the context of multi-agent oriented programming, you have to download the set of exercises that are available here

Preamble

  • Every agent of a JaCaMo MAS has the possibility to participate to the management of the organizations that are deployed in the MAS by the way of a set of dedicated organizational artifacts: GroupBoard and SchemeBoard.

GroupBoard description (cf. GroupBoard API)

  • A GroupBoard artifact provides the agents with a set of operations, observable properties and signals that any agent can use for managing the life cycle of a group in the organization: creation/deletion of the group, adoption/leave of roles, becoming responsible of a social scheme, etc. Let's note that for each instance of group to be executed, should be created a GroupBoard in the MAS.

Organizational operations (made available to agents through organizational actions)

  • adoptRole(String role): the agent tries to adopt role in the group
  • leaveRole(String role): the agent tries to give up role in the group
  • addScheme(String schId): the group starts being responsible for the scheme schId
  • removeScheme(String schId): the group finishes being responsible for the scheme schId
  • setParentGroup(String parentGroupId): the group becomes a subgroup of parentGroupId
  • setOwner(String agentId): the agent agentId that owns the group (inherited by OrgArt)
  • destroy(): the agent destroys the group

Organization Observable Properties (Java objects mapped to agent's beliefs)

These beliefs are annotated with artifact(artifact id).

  • specification(….): the specification of the group in the OS (a prolog like representation) as follows: group_specification(group type id, list of role, list of sub-groups, properties).
    • Each role in the list is: role(id,min cardinality, max cardinality, list of compatible roles, list of links), each link is: link(type, target, scopo) (see explanations)
  • play(agent, role, group): agent agent is playing the role in the group.
  • schemes: a list of schemes ids the group is responsible for.
  • subgroups: a list of subgroups ids
  • parentGroup: the id of the parent group (used in subgroups)
  • formationStatus: whether the group is well-formed (values are ok and nok)

Organizational signals (mapped to agent's organizational events)

  • 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 condition does not hold anymore)
  • normFailure(f): the failure f has happened (e.g. due to some regimentation violation)
  • destroyed(artifact id): artifact has been destroyed.
  • obligation(agt, norm, what, deadline)

SchemeBoard description (cf. SchemeBoard API)

  • A SchemeBoard artifact provides the agents with a set of operations, observable properties and signals that any agent can use for managing the life cycle of a social scheme in the organization: creation/deletion of the social scheme, commitment/leave of missions, etc. Let's note that for each instance of social scheme to be executed, should be created a SchemeBoard in the MAS. Let's note that for each instance of social scheme to be executed, should be created a SchemeBoard in the MAS.

Organizational operations (made available to agents through organizational actions)

  • commitMission(String mission): the agent tries to commit to a mission in the scheme (verifications of the mission max cardinality and mission permissions, throwing normFailure in the case of breaking some regimentation)
  • leaveMission(String mission): the agent tries to leave/remove its mission in the scheme (verifications that the agent is committed to the mission and that the mission's goals have been satisfied throwing a normFailure in the case of breaking some regimentation)
  • goalAchieved(String goal): the agent sets the goal as achieved (verifications that the agent is committed to the goal and that the goal has been enabled throwing a normFailure in the case of breaking some regimentation)
  • setArgumentValue(String goal, String var, Object value): the agent sets a value for the goal argument var
  • resetGoal(String goal): the agent resets the goal
  • destroy(): the agent destroys the instance of the scheme board

Organization Observable Properties (Java objects mapped to agent's beliefs)

They are beliefs annotated with artifact(artifact id).

  • specification(….) for schemes are (see explanations): scheme_specification(id,goals tree starting by root goal,missions).
  • commitment(agent, mission, scheme) agent ag is committed to the mission in the scheme (we have as many obs prop as commitments)
  • groups: a list of groups responsible for the scheme.
  • goalState(schId, goalId, list of committed agents, list of agents that achieved the goal, state); where state refers to the goal status: waiting, enabled, satisfied).
  • obligation(agent,norm,goal,deadline): the current active obligations.

Organizational signals (mapped to agent's organizational events)

  • 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 condition does not hold anymore)
  • normFailure(f): the failure f has happened (e.g. due to some regimentation violation)
  • destroyed(artifact id): artifact has been destroyed.
  • obligation(agt, norm, what, deadline)

Refreshing the context: MAS without Organization

  • Let's go back to the refactoring issued from the last practical work on EOP

Exercise: Using a world of interacting Agents and Artifacts without Organization

  • Consider the code step11.
  • Look at the code of the "user_agent" that uses these artifacts and run the example launching the MAS server and the client one.

A first Agents Organization

  • In order to install some coordination, let's use an organization which provides us with the right mean to install an explicit and adaptable coordination pattern.
  • The org-spec.xml file contains the definition of an organization specification based on the MOISE organization language.
  • This is a very first organization structural and functional specifications assigning goals to agents (one role, mission/goal and norm) so that a set of agents is in charge of observing, another set in charge of computing, another set in charge of printing messages). This specification is a follows:
    • Structural specification:
      • one group type: easssGr
      • possible roles are: greeter, observer, computer
    • Functional specification:
      • possible goals are compute, greeting, observe,
      • missions are mCompute, mGreeting, mObserve
    • Normative specification is straightforward: permissions for each role, each mission

Exercise: Organized world of interacting Agents and Artifacts

  • Consider the code step12.
  • Define a group of three to four students. Each group launches only one MAS server. Each user launches a MAS client.
  • Use the GUI Artifact in your MAS client and try to enter the organization following the dynamic of the organization as defined in MOISE metamodel (cf. course). Thanks to the GUI Artifact, you can decide to adopt a role, to commit to a mission, to declare the achievement of some goal
  • Look at the execution using either the agent's mind inspector, the organization inspector checking the state of each of the organizational artifacts (groupboard and schemeboard), detect the violations
  • Describe the global life cycle of the organization? What are the different steps to follow before executing a social scheme?

Mastering the building of an organization

Exercise: Changing the Organization Specification

  • 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 mission mCompute (after testing, undo your change)

Organization-Aware Agents: reasoning on the organization

  • We will reuse the previous example and will automate some of the actions for creating/instantiating the organisation.
  • You could have a look at the way the deployement of the organisation management infrastructure is done in the MAS server by looking at the code of the (org_majordomo) agent

Exercise: Adopting a role

  • Choose a role to be adopted by your agent
  • Add in your code the plan so that your agent adopts the chosen role as soon as the group has been created (i.e. the corresponding groupBoard artifact has been deployed)
  • Add in your code the plan so that your 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.

Exercise: Making a group responsible of a social scheme

  • Make your group responsible of the social scheme deployed in the schemeBoard artifact, as soon as the group is well formed.
  • From that time, agents that are playing roles in the group, have the possibility to execute the missions of the scheme under the responsibility of the group.

How to test the status of a group

  • As soon as the group is well formed, a new belief formationStatus is generated into the agent's belief base

Organization-Aware Agents : reasoning on the obligations

Exercise: Making an obedient agent

  • Add a plan in the agent's code so that this agent becomes an obedient one: as soon as one obligation, that concerns it, is created, the agent fulfills the obligation

What does it mean to fulfill an obligation

  • fulfilling an obligation for a mission means committing to that mission
  • fulfilling an obligation for a goal means achieving that goal

Managing violations

Exercise: Managing 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

How to know that an obligation has been fulfilled

  • as soon as an obligation is fulfilled, the signal oblFulfilled is generated by the artifacts

Olivier Boissier, Rafael Bordini, Jomi Hubner, Alessandro Ricci, June 2014