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

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 (.jcm): one for the server workspace, one for the client one.

  • 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

Learned features

In this step, you will learn:

  • How to use the organization specification

  • What is the life cycle of an organization

  • How to change and define organization specification

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.

A simple organization 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 group easssGr with greeter, observer and computer roles that can be played by the agents participating to groups 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 a set of missions mCompute, mGreeting and mObserve

  • a normative specification that assigns in a straightforward way obligations to each role and mission

The org_agent agent program: 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.

The user_agent program: user_agent.asl

  • This agent is focused on two GUI artifacts Scheme Console and Group 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.

The server.jcm and client.jcm project files

These two jacamo project files are used to distribute agents, artifacts and the organization 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 organization from the org-spec.xml (the organization artifacts in charge of its management are deployed in the easss_org workspace)

  • 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 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 the organization inspector to inspect the evolution of the organization state in the Group boards and Scheme boards, to detect the violations

Hints:

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 mission mCompute (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:

  • How to program agents that can deploy organization following the organization specification

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.

Initiate the organization

  • 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 type ora4mas.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)];
Initiate Groups and Schemes

  • 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)];
Make the group responsible of a social scheme

  • 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)];
Make agents adopt roles

  • 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)];
Hints

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:

  • How to do some basic reasoning on the organization

Undestand

Obligation
obligation(ag,reason,goal,deadline)
Signals coming from the organization

  • 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

  • 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 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

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