JADE PROGRAMMING FOR BEGINNERS

JADE TUTORIAL

USAGE RESTRICTED ACCORDING TO LICENSE AGREEMENT.

last update: 9 September 2007. JADE 3.6

Authors: Giovanni Caire (TILAB, formerly CSELT)

Copyright (C) 2000 CSELT S.p.A.

Copyright (C) 2001 TILab S.p.A.

Copyright (C) 2002 TILab S.p.A.

Copyright (C) 2003 TILab S.p.A.

Copyright (C) 2004 Telecom Italia S.p.A.

Copyright (C) 2005 Telecom Italia S.p.A.

Copyright (C) 2006 Telecom Italia S.p.A.

Copyright (C) 2007 Telecom Italia S.p.A.

Copyright (C) 2008 Telecom Italia S.p.A.

JADE -Java Agent DEvelopment Framework is a framework to develop multi-agent systems in compliance with the FIPA specifications. JADE successfully passed the 1st FIPA interoperability test in Seoul (Jan. 99) and the 2nd FIPA interoperability test in London (Apr. 01).

Copyright (C) 2000 CSELT S.p.A. (C) 2001 TILab S.p.A. (C) 2002 TILab S.p.A.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, version 2.1 of the License.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

This tutorial is structured as follows. Chapter 1 gives a brief overview of JADE and introduces the concepts of Platform, Container, AMS and DF. Chapter 2 presents a simple example that will be used throughout this tutorial to illustrate the steps required to develop simple agent-based applications with JADE. Chapter 3 focuses on creating agents and explains the basic features of the Agent and AID classes. Chapter 4 explains how to make JADE agents execute tasks and introduces the Behaviour class. Chapter 5 describes how to make agents communicate and introduces the ACLMessage and MessageTemplateclasses. Chapter 6 illustrates how to exploit the Yellow Pages service provided by the DF agent through the DFService class.

Besides the basic features illustrated in this tutorial JADE provides a number of advanced features such as the support for complex interaction protocols and the usage of user defined ontologies. For these features readers are reminded to the JADE Programmer’s guide and Administrator’s guide available on the JADE web site.

1 JADE OVERVIEW

JADE is a middleware that facilitates the development of multi-agent systems. It includes

• A runtime environment where JADE agents can “live” and that must be active on a given host before one or more agents can be executed on that host.

• A library of classes that programmers have to/can use (directly or by specializing them) to develop their agents.

• A suite of graphical tools that allows administrating and monitoring the activity of running agents.

1.1 Containers and Platforms

Each running instance of the JADE runtime environment is called a Container as it can contain several agents. The set of active containers is called a Platform. A single special Main container must always be active in a platform and all other containers register with it as soon as they start. It follows that the first container to start in a platform must be a main container while all other containers must be “normal” (i.e. non-main) containers and must “be told” where to find (host and port) their main container (i.e. the main container to register with).

If another main container is started somewhere in the network it constitutes a different platform to which new normal containers can possibly register. Figure 1 illustrates the above concepts through a sample scenario showing two JADE platforms composed of 3 and 1 container respectively. JADE agents are identified by a unique name and, provided they know each other’s name, they can communicate transparently regardless of their actual location: same container (e.g. agents A2 and A3 in Figure 1), different containers in the same platform (e.g. A1 and A2) or different platforms (e.g. A4 and A5).

You don’t have to know how the JADE runtime environment works, but just need to start it before executing your agents. Starting JADE as a main or normal container and executing agents on it, is described in the JADE Administrative Tutorial available on the JADE website.

1.2 AMS and DF

Besides the ability of accepting registrations from other containers, a main container differs from normal containers as it holds two special agents (automatically started when the main container is launched).

The AMS (Agent Management System) that provides the naming service (i.e. ensures that each agent in the platform has a unique name) and represents the authority in the platform (for instance it is possible to create/kill agents on remote containers by requesting that to the AMS). This tutorial does not illustrate how to interact with the AMS as this is part of the advanced JADE programming.

The DF (Directory Facilitator) that provides a Yellow Pages service by means of which an agent can find other agents providing the services he requires in order to achieve his goals. Using the Yellow Pages service provided by the DF agent is illustrated in chapter 6.

2 THE “BOOK TRADING” EXAMPLE

This chapter introduces a simple example that will be used throughout this tutorial to illustrate the steps required to develop agent-based applications with JADE. The scenario considered in this example includes some agents selling books and other agents buying books on behalf of their users.

Each buyer agent receives the title of the book to buy (the “target book”) as a command line argument and periodically requests all known seller agents to provide an offer. As soon as an offer is received the buyer agent accepts it and issues a purchase order. If more than one seller agent provides an offer the buyer agent accepts the best one (lowest price). Having bought the target book the buyer agent terminates.

Each seller agent has a minimal GUI by means of which the user can insert new titles (and the associated price) in the local catalogue of books for sale. Seller agents continuously wait for requests from buyer agents. When asked to provide an offer for a book they check if the requested book is in their catalogue and in this case reply with the price. Otherwise they refuse. When they receive a purchase order they serve it and remove the requested book from their catalogue.

All issues related to electronic payment are outside the scope of this tutorial and are not taken into account.

The complete sources of this example are available among the examples provided with JADE in the examples.bookTrading package.

3 CREATING JADE AGENTS – THE AGENT CLASS

Creating a JADE agent is as simple as defining a class extending the jade.core.Agent class and implementing the setup() method as shown in the code below.

import jade.core.Agent;

public class BookBuyerAgent extends Agent {

protected void setup() {

// Printout a welcome message

System.out.println(“Hello! Buyer-agent “+getAID().getName()+” is ready.”);

}

}

The setup() method is intended to include agent initializations. The actual job an agent has to do is typically carried out within “behaviours” as will be described in chapter 4.

3.1 Agent identifiers

Each agent is identified by an “agent identifier” represented as an instance of the jade.core.AID class. The getAID() method of the Agent class allows retrieving the agent identifier. An AID object includes a globally unique name plus a number of addresses. The name in JADE has the form <nickname>@<platform-name> so that an agent called Peter living on a platform called P1 will have Peter@P1 as globally unique name. The addresses included in the AID are the addresses of the platform the agent lives in. These addresses are only used when an agent needs to communicate with another agent living on a different platform. Developers need to care about them only in particular cases that are outside the scope of this tutorial.

Knowing the nickname of an agent, its AID can be obtained as follows:

String nickname = “Peter”;

AID id = new AID(nickname, AID.ISLOCALNAME);

The ISLOCALNAME constant indicates that the first parameter represents the nickname (local to the platform) and not the globally unique name of the agent.

3.2 Running agents

The created agent can be compiled as follows.

javac –classpath <JADE-classes> BookBuyerAgent.java

In order to execute the compiled agent the JADE runtime must be started and a nickname for the agent to run must be chosen:

java –classpath <JADE-classes>;. jade.Boot buyer:BookBuyerAgent

More details on compiling and running agents can be found in the JADE Administrative Tutorial or in the JADE Administrator’s Guide available on the JADE website. The result of the typed command is as follows.

C:\jade>java –classpath <JADE-classes> jade.Boot buyer:BookBuyerAgent

5-mag-2008 11.06.45 jade.core.Runtime beginContainer

INFO: ----------------------------------

This is JADE snapshot - revision 5995 of 2007/09/03 09:45:22

downloaded in Open Source, under LGPL restrictions,

at http://jade.tilab.com/

----------------------------------------

5-mag-2008 11.06.51 jade.core.BaseService init

INFO: Service jade.core.management.AgentManagement initialized5-mag-2008 11.06.51 jade.core.BaseService initINFO: Service jade.core.messaging.Messaging initialized

5-mag-2008 11.06.52 jade.core.BaseService init

INFO: Service jade.core.mobility.AgentMobility initialized

5-mag-2008 11.06.52 jade.core.BaseService init

INFO: Service jade.core.event.Notification initialized

5-mag-2008 11.06.52 jade.core.messaging.MessagingService clearCachedSlice

INFO: Clearing cache

5-mag-2008 11.06.53 jade.mtp.http.HTTPServer <init>

INFO: HTTP-MTP Using XML parser com.sun.org.apache.xerces.internal.parsers.SAXParser

5-mag-2008 11.06.54 jade.core.messaging.MessagingService boot

INFO: MTP addresses:

http://NBNT2004130496.telecomitalia.local:7778/acc

5-mag-2008 11.06.54 jade.core.AgentContainerImpl joinPlatform

INFO: --------------------------------------

Agent container Main-Container@NBNT2004130496 is ready.

--------------------------------------------

Hello! Buyer-agent buyer@NBNT2004130496:1099/JADE is ready.

The first part of the above output is the JADE disclaimer that is printed out each time the JADE runtime is started. The initialization of the kernel services (kernel services are JADE internal stuff and are not described in this document) activated in the started platform follows. Finally the indication that a container called “Main-Container” is ready completes the JADE runtime startup. When the JADE runtime is up our agent is started and prints its welcome message. The nickname of the agent is “buyer” as we specified on the command line. The platform name “NBNT2004130496:1099/JADE” is automatically assigned on the basis of the host and port you are running JADE on (see the JADE Administrator’s guide for assigning a name to the platform).

3.3 Agent termination

Even if it does not have anything else to do after printing the welcome message, our agent is still running. In order to make it terminate its doDelete() method must be called. Similarly to the setup() method that is invoked by the JADE runtime as soon as an agent starts and is intended to include agent initializations, the takeDown() method is invoked just before an agent terminates and is intended to include agent clean-up operations.

3.4 Passing arguments to an agent

Agents may get start-up arguments specified on the command line. These arguments can be retrieved, as an array of Object, by means of the getArguments() method of the Agent class. As mentioned in chapter 2, we want our BookBuyerAgent to get the title of the book to buy as a command line argument. To achieve that we modify it as follows (1).

import jade.core.Agent;

import jade.core.AID;

public class BookBuyerAgent extends Agent {

// The title of the book to buy

private String targetBookTitle;

// The list of known seller agents

private AID[] sellerAgents = {new AID(“seller1”, AID.ISLOCALNAME),

new AID(“seller2”, AID.ISLOCALNAME)};

// Put agent initializations here

protected void setup() {