Multi-Agent Oriented Programming Master Web Intelligence, 2010-2011

Table of Contents

The definition and design of some of the parts of this course are the result of cooperation between the authors of this course and R. H. Bordini, Instituto de Informatica, Pontificia Universidade Catolica do Rio Grande do Sul, Brazil, J. F. Hubner, Federal University of Santa Catarina - DAS, Florianopolis, Brazil, J.S. Sichman, Universidade de Sao Paulo - LTI-PCS, Sao Paulo, Brazil, M. Piunti, A. Santi, A. Ricci, Universita degli studi di Bologna - DEIS, Bologna, Italy.

We acknowledge the support of the Region Rhone Alpes with the CMIRA 2010 project.

1 Course

2 Configuring your Working Environment

  • Create a directory maop (stands for "multi-agent oriented programming"). In the sequel, we will use MAOP as environment variable to point on this directory (e.g. MAOP=/Users/dupont/MAS/maop).
  • In $MAOP, you will install all the different distributions that will be used during the course: agent (Jason Language) -done later in AOP section-, environment (CArtAgO platform) -done later in EOP section-, organisation (Moise Language) -done later in OOP section- and finally the JaCaMo maop platform (that packages the three previous distributions).
  • The JaCaMo Java-based platform can be dowloaded from: http://sourceforge.net/projects/jacamo/ or here locally jacamo.
  • Install it in the $MAOP directory.
  • Create an examples directory in the $MAOP directory. All your practical exercises will go in it.
  • For each exercise, you'll create a dedicated directory.
  • You environment will look like that at the end of the practical work:
maop
   jacamo
   Jason-1.3.3
   cartago-2.0.1
   ...
   examples
       greeting
       cleaning_robots
       auction_house
       ...

3 Practical work on JADE

4 Practical work on Agent Oriented Programming: The Jason Language

4.1 Installation and Configuration
4.2 Tutorial on Jason
  • To start learning and using Jason, DO the tutorial where you'll learn how to install Jason and write some Jason Program.
  • DO the following changes to the "sending hello" exercise: (i) create an other agent called "alice" who sends "bonjour" to bob ; (ii) change bob's code so that as soon as he receives a message he replies to the sender with the same content ; (iii) change the code of the agents "bob" and "alice" so that they fall into an infinite loop of message exchanges.
  • Using Jade and Jason is quite easy. DO the Tutorial Jade-Jason.
  • Note: the list of all available standard actions are described in the jason.stdlib package described in the standard documentation (available in doc/api/index.html)

5 Practical work on Environment Oriented Programming: The CArtAgO Platform

5.1 Installation and Configuration
  • CArtAgO distribution is available from http://sourceforge.net/projects/cartago/ or here locally catago-2.0.1.
  • Download and install CArtAgO distribution in the $MAOP directory to have the complete distribution, documentation and examples;
  • In order to create a Jason application exploiting CArTAgO, just include in the MAS configuration file (the one ending with .mas2j):
    • cartago.jar and c4jason.jar libraries in the declared class path;
    • the declaration of c4jason.CartagoEnvironment as environment;
    • the declaration of c4jason.CAgentArch as agent architecture, for each agent that needs to work within CArtAgO environment.
5.2 "Hello CArtAgO" simple example

In the following, we will program a simple hello world example, with a hello_world MAS where two instances of hello_agent agent.

  • Configuration File of the MAS
    MAS hello_world {  
    environment: c4jason.CartagoEnvironment  
    agents: 
        hello_agent agentArchClass c4jason.CAgentArch #2; 
    classpath: "$MAOP/jacamo/lib/cartago.jar";"$MAOP/jacamo/lib/c4jason.jar";
    } 
    
  • Hello Agent
    • As you can notice, we have to add in the classpath the cartago and cartago bridge for jason libraries.
    • The hello_agent agent first discovers the console artifact, then interacts with it printing an hello message, by acting on the println operation control.
    • Here is the code:
    !hello. 
    +!hello : true  
    <- .my_name(Name); 
       println("Hello, world! by ",Name).
    
5.3 "Counting" example
  • In the following, we will program a simple counting world example, with a counter_mas MAS.
  • Create a Jason project counter_mas.
  • In this MAS, the counter agents and observer agents play in the default workspace using counting artifacts.
  • "Counter" Artifact
    • The Counter0 artifact is a simple artifact composed of a count observable property initialized to 0 when the artifact is created.
    • The artifact has a single operation inc with no parameters that increments count and sends a signal tick every time it is executed by an agent.
    • DO : write the code of this artifact in the counter_mas directory.
  • Observer agent
    • DO : write the code of the observer agent. This agent creates the Counter0 artifact and observes it by focusing on. The observer agent stops focusing on the artifact as soon as its observable property is equal to 6.
    // Agent observer in project counter_mas.mas2j
    
    /* Initial beliefs and rules */
    
    /* Initial goals */
    
    !observe.
    
    /* Plans */ 
    
    +!observe : true 
    <-      println("Oberver starting to work");
            makeArtifact("counter0","Counter0", [], Count); 
            +myTool(Count); 
            focus(Count).
    
    ...
    
  • Counter agent
    • DO: Write a first version of the counter agent using this silly code, just to test your artifact
    // Agent counter in project mas_counter_bis.mas2j
    
    /* Initial beliefs and rules */ 
    
    /* Initial goals */ 
    
    !start. 
    
    /* Plans */   
    
    +!start : true
      <- ?discover_count(Count);  
         !use_count(Count).  
         
    +?discover_count(Count) : true  
      <- lookupArtifact("counter0",Count). 
    
    -?discover_count(Count)  
      <- .print("count still not available..waiting"); 
         .wait(10);  
         ?discover_count(Count).  
         
    +!use_count(Count): true  
      <- for (.range(I,1,50)) {
                    inc[artifact_id(Count)];
                    .print("incrementing step ",I);
            }.
    
5.4 Extended version with messages
  • Having checked that everything is ok, let's write now a more "interesting" version of this agent.
  • When the observer agent has created the artifact, he/she broadcasts the name of this artifact in the MAS (the counter agent has no more hardcoded the name of the artifact to use)
  • As soon as the counter agents gets the message, he/she starts to use this artifact to increment the value of the counter.
  • Being a lazy agent, it rests for a while (let's say 100 ticks), after each increment. It does this job for 10 cycles. Every time, the agent increments the artifact and prints a message.
  • DO: write the jason code of both agents and test it.
5.5 Extended version with failure plan
  • Keeping the same set of agents, change the Counter0 artifact into a "bounded" counter artifact: its observable property cannot be higher than a maximum value fixed at the initialisation. This artifact generates a failure failed signal when action inc is no more possible.
failed(String failureMsg, String descr, Object... args)
an action feedback is generated, reporting a failureMsg and a tuple
descr(Object...) describing the failure
  • Transform the counter agent so that it executes some plan in case of failure of its plan of incrementing the counter.
5.6 To go deeper in the use of Cartago
  • We strongly invite you to have a look at the following set of exercises that introduce step by step the different features of the Cartago Platform
5.7 Artifact-Based Auction House
  • In this last exercise, you have to develop a MAS where a set of agents will use an artifact to execute an auction protocol to allocate a set of tasks between them.
  • One agent, the contractor, giacomo creates an instance of this artifact for each of the tasks he/she needs to allocate to different company agents: e.g. one auction artifact for Walls, another one for Floors, …
  • company agents can perceive those artifacts and bid according to their competence and following their own strategies.
  • Auction Actifact
    • The auction artifact has the following observable properties: task description, maximum payment value maxValue, current best bid currentBid (lower service price), current winning agent ID currentWinner.
    • The auction artifact AuctionArt has the following operation: bid(p) that consists in placing a new bid for doing the service for price p. The init operation of this artifact receives the task description that will be auctionned and the maximum value for the bid.
    • Note: to get the agent that has executed an action, it is possible to use the getOpUserName method
  • Giacomo Agent:
    • Belief base: composed of the different content of the parts that will be produced by the agent. For instance, the form of such a belief can be: paper("Section","Section1") where the first argument defines the "part" and the second defines the "content" of the part.
    • The giacomo agent is in charge of creating the auction house, i.e. to create an auction artifact for each of the tasks to allocate. It is also in charge to drive and manage the different auctions.
    • The creation of an auction artifact consists in declaring the task that is managed by the artifact and the maximum possible price for it.
    • Note: the implementation of the iteration on the different auction artifacts can be done using the for
    Implementation of for.
    
    Syntax:
    
      for ( logical formula ) {
         plan_body
      }
    
    for all unifications of logical formula, the plan_body is executed.
    
    Example:
    
    +event : context
      <- ....
         for ( vl(X) ) {
            .print(X);     // print all values of X
         }
         for ( .member(X,[a,b,c]) ) {
            .print(X);    // print all members of the list
         }
         for ( .range(I,1,10) ) {
            .print(I);    // print all values from 1 to 10
         }
         ....
    
    The unification resulted from the evaluation of the logical formula is
    used only inside the loop, i.e., the unification after the for is the
    same as before. 
    
  • Company Agents
    • The company agents discover the different auction artifacts corresponding to the tasks they are interested in and build the different bids according to their own strategies.
    • In the following you will have to develop three agents interested in the same set of tasks (e.g. sitePreparation, Floors, Walls), having different strategies for bidding.
      • one agent will have the same blind strategy for every taks: decrease the current bid by a constant value until his/her lowest limit is reached.
      • one agent will have a different strategy for each task
      • one agent will have a maximum value for all the tasks he/she wants to bid for (i.e. coordination of the different bids that he/she realizes on each task)
    • Note / Winner you can use the following code for making an agent aware of that he is winning or not in an auction:
    i_am_winning(Art)   // check if I placed the current best bid on auction artifact Art
       :- currentWinner(W)[artifact_id(Art)] & .my_name(Me) & .term2string(Me,MeS) & W == MeS.
    
    • Note / Sum of all the current bids placed by the agent
    sum_of_my_offers(S) :- 
       .my_name(Me) & .term2string(Me,MeS) &
       .findall( V,      // artifacts/auctions I am currently winning
                 currentWinner(MeS)[artifact_id(ArtId)] &
                          currentBid(V)[artifact_id(ArtId)], 
                 L) & 
       S = math.sum(L).
    

6 Practical work on Organisation Oriented Programming: The Moise Framework

6.1 Installation and Configuration
  • The Moise Framework for Multi-Agent Organisation programming can be downloaded from: https://sourceforge.net/projects/moise/ or Here locally moise-0.7a.
  • Download and install it in the $MAOP directory to have the complete distribution with examples, documentation, tutorial.
  • In order to create a Jason application exploiting CArTAgO and MOISE Artefact-based organisational management infrastructure, just include in the MAS configuration file (the one ending with .mas2j):
    • cartago.jar, c4jason.jar, moise.jar libraries in the declared class path;
    • the declaration of c4jason.CartagoEnvironment as environment;
    • the declaration of c4jason.CAgentArch as agent architecture, for each agent that needs to work within CArtAgO environment and with the organisation management infrastructure.
MAS my_project {
   infrastructure: Centralised
   environment:
       c4jason.CartagoEnvironment
   agents:
       agent1     agentArchClass c4jason.CAgentArch;
       ...

   classpath: "$MAOP/jacamo/lib/cartago.jar";"$MAOP/jacamo/lib/c4jason.jar";"$MAOP/jacamo/lib/moise.jar";
}
6.2 "Hello Moise" simple organisation and Jason Agents
  • Copy the $MAOP/moise-0.7a/examples/sim directory to your local directory examples
  • Configure the classpath of the org-simulator.mas2j project according to your local configuration (Let the agents as defined in the project definition).
  • The organisation specification is related to the traditional Writing Paper example.
  • Launch the project and run it using the different GUIs that appear.
    • This first application uses one generic GUI to create the artifact-based organisation management infrastructure for Moise and agents. This GUI enables the user to test the specification of any organisation.
    • Run it so that we have three agents: (1) Bob who creates one group, and one scheme to write a paper, adopts r2 in the group and mManager and mBib in the scheme ; (2) Alice who waits for the group creation and then adopts the role r3 and commits to the mission mColaborator ; (3) Carol who also waits for the group creation and then adopts the role r3 and commits to the mission mColaborator.

Some explanations:

  • Each agent has at his/her disposal the different organisational actions provided by the organisational artifacts:
    • see the GroupBoard API $MAOP/moise-0.7a/doc/api/ora4mas/nopl/GroupBoard.html
    • see the SchemeBoard API $MAOP/moise-0.7a/doc/api/ora4mas/nopl/SchemeBoard.html
  • The 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)
  • The beliefs are the following (see API documentation of artifacts for more details):
    • specification(….) for groups (see ../../doc/api/moise/os/ss/Group.html#getAsProlog())
    • specification(….) for schemes (see ../../doc/api/moise/os/fs/Scheme.html#getAsProlog())
    • play(agent, role, group)
    • commitment(agent, mission, scheme)
    • goalState(scheme, goal, list of committed agents, list of agent that achieved 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.
  • Note: you can read the code of the simulator to learn how to program Java agents to use these artifacts. The source is available in $MAOP/moise-07.a/src/ora4mas/nopl/simulator/ConsoleSimulator.java
6.3 A more complex organisation with Jason Agents and Artifacts
  • We will reuse the previous example and will automate some of the actions for creating/instantiating the organisation.
  • Deployement of the organisation management infrastructure
    • From the orgagent.asl template, we will create a director agent that will execute and automate some of the actions of the organisation.
    • the agent will deploy both the GroupBoard (ora4mas.nopl.GroupBoard) and the SchemeBoard (ora4mas.nopl.SchemeBoard), using the operation makeArtifact, respectively for the gspec group and sspec scheme.
    • he/she will adopt the role r2 as soon as the groupBoard artifact is deployed.
    • As soon as the group is well formed, he/she will add the group as responsible of the scheme (i.e. agents playing roles in the group will have the possibility to execute the missions of the scheme under the responsibility of the group).
      • Note: as soon as the group is well formed, a new belief is generated into the belief base of the agent formationStatus
  • Automatic instantiation of the organisation
    • Modify the organisation specification in order to force to have at least two agents playing the role r3 in the group. Modify the organisation specification so that the role r1 is obliged to commit to mission mManager.
    • Write a behaviour in director code so that as soon as an agent different of him/her who adopts a role in his/her group, he/she leaves that role and adopt the role r3.
    • Write a behaviour in director code so that this agent is an obedient one: as soon as one obligation concerning him/her is created, he/she fullfill the obligation: fulfilling an obligation for a mission means committing to this mission, fulfilling an obligation for a goal means achieving that goal.
    • Write a behaviour in director code so that each time an agent of his/her group fulfill an obligation he/she sends a message to the other agents in order to increase the reputation of that agent (use the signal oblFulfilled which is generated by the artifacts).

7 Practical work on Multi-Agent Oriented Programming: Builing Giacomo's House

  • In this final exercise, you will develop the multi-agent system for managing and executing the general workflow describing the tasks to build an house.
  • THE COMPLETE SYSTEM HAS TO BE RETURNED NO LATER THAN THE 1st OF FEBRUARY. You 'll have to return:
    • the source code (java, asl, organisation specification)
    • a description and explanation of the way you have programmed your application.
  • A possible partial implementation of this application is available as a tutorial of the jacamo platform available at http://jacamo.sourceforge.net. You can use it as starting point (you already have started to develop this application while building the auction house).
  • The description of the different steps and design choices are available here
  • Based on this first solution, you will have to do the following improvements:
    • Develop an agent that tries to adopt roles related to tasks he/she is not supposed to (malevolent agent)
    • Develop an agent that does not fulfill the tasks
    • Change the Giacomo agent so that it is able to monitor the building of the house and check whether the tasks are being done appropriately: reacting to the norm violation, to the norm fulfillement.
    • When a task has not been properly executed, Giacomo should create a new auction for that task and forbid the violating company from taking part in the new auction.
    • Change the system to build two houses in parallel
    • Add any improvement you wish.

Author: O. Boissier, G. Picard, R. Yaich (LSTI-ENSM-SE)

Date: October 2010

HTML generated by org-mode 7.01h in emacs 23