MadKit Development Guide

The model places no constraints on the internal architecture of agents. An agent is only specified as an active communicating entity which plays roles within groups. This agent definition is intentionally generic to allow agent designers to adopt the most accurate definition of agent-hood relative to their application. The agent designer is responsible for choosing the most appropriate agent model as internal architecture.

Groups are defined as atomic sets of agent aggregation. Each agent is part of one or more groups. In its most basic form, the group is only a way to tag a set of agents. In a more developed form, in conjunction with the role definition, it may represent any usual multi-agent system.

Groups have the following characteristics:

The role is an abstract representation of an agent function, service or identification within a group. Each agent can handle multiple roles, and each role handled by an agent is local to a group. Handling a role in a group must be requested by the candidate agent, and is not necessarily awarded. Thus, modeling of abstract communication schemes can defined from roles, guiding the design process.

The MadKit platform is built around this agent/group/role model. In addition to the three core concepts, the platform adds three design principles:

MadKit itself is a set of packages of Java classes that implements the agent kernel, the various libraries of messages, probes and agents. It also includes a graphical development environment and many system and demonstration agents.

The basic philosophy of the MadKit architecture is to use wherever possible the platform for its own management: any service beside those assured by the micro-kernel are handled by agents. Thus the platform is not an agent platform according to the classical sense. The reduced size of the agent kernel, combined with the principle of modular services managed by agents enable a range of multiple, scalable platforms with simultaneous specialized agent models libraries.

The MadKit micro-kernel is a small (less than 50 Kb) and optimized agent kernel. The term "micro-kernel" is intentionally used as a reference to the role of micro-kernels in the domain of OS engineering. We could directly translate their motto into:

...incorporating a number of key facilities that allow the efficient deployment of services.

The MadKit kernel handles only the following tasks:

MadKit uses the AGR model for its own usage. All services, apart from those provided by the kernel are performed by agents using groupes and roles to perform their own tasks. For instance, remote communication, i.e. communications that are performed between agents situated in different kernels, are handled by a specific Communicator agent.

An important aspect of MadKit is the possibility to define distributed applications without being concerned by low level constructs such as sockets, threads, URL, etc. No modification of code is needed to distribute a MadKit application. Once the basic principles of MadKit, i.e. using AGR, sending messages, referencing agents through their agent address, are applied, it is straightforward to make it work on several kernels. See section {{section}} to learn how to setup a distributed network of MadKit kernels, and see section {{section}} to learn the fundamental tips and tricks of distributed programming, and the main errors a programmer should avoid to make his or her application transparently work in a distributed environment.

The MadKit graphical interface is based on the Java Bean specification. Each agent is solely responsible for its own graphical interface in every aspect (rendering, event processing, actions...). An agent interface can be a simple label, a complex construction based on multiple widgets, or a legacy bean software module.

A "graphic shell", called the MadKit desktop or desktop for short, launches the kernel and setup the interfaces for the various agents and manages them in a global GUI (for instance: each agent has its own window, or is mapped in a global worksheet, or is combined with another agent interface, etc.).

As the agent graphic interfaces are decoupled from the agent kernel, the platform can run in various modes (desktop, applet, console only, etc.) and the agent code does not need any modification.

Plugin based structure

MadKit comes as a set of plugins. This structure allows various agents and features to be added as simple module one may add, remove and update at its own needs. Each plugin is controlled by an ant file from which it is possible to recompile, install and desinstall a module.

Plugin development architecture of MadKit

In this section we describe the plugin architecture of MadKit 4. MadKit is based on a plugin structure which allows new features and agents to be added as kind of modules called plugins. A plugin is made of files and resources which may be compiled, installed, updated, etc. using ant, a fantastic development tool written in Java.

  madkit
   +--- bin  // contains launcher scripts
   |
   +--- lib  // contains Ant jars plus necessary dependencies
   |
   +--- docs // contains documentation
   |
   +--- plugins // contains all the plugins description
          +---- plugin1 // the different plugins
          +---- plugin2 //
          +---- plugin3 //

Each plugin is related to a specific jar in the lib directory and its description is associated to a specific directory of the same name, which is located in the plugins directory of MadKit. For instance, the demos plugin is related to the demos.jar file situated in the lib directory, and its description can be found in the directory demos located in the plugins directory.

  plugin's name
   +--- src  // containts the sources of the java files and the ressources to be included in the jar.
   |     +--- package name of java files
   |     +--- images  // the images to be included as resources in the jar.
   |
   +--- scripts  // contains the text files used by agents, and the sources of the scripted files.
   |
   +--- docs // contains the documentation of the plugin
   |
   +--- build.xml // the ant file used to compile, install, etc.. the plugin
   +--- optional: <plugin>.cfg // a configuration file (in XML format) which may be used to initiate a set of agents
   +--- optional: <plugin>.bat // a .bat file which starts MadKit with no desktop 
   |                           // with only the agents defined in the <plugin>.cfg file
   +--- optional: <plugin>.sh  // a .sh file which starts MadKit with no desktop 
   |                           // with only the agents defined in the <plugin>.cfg file
   +--- optional: <plugin>_desktop.bat // a .bat file which starts MadKit with the desktop 
   |                                   // and load the agents defined in the <plugin>.cfg file
   +--- optional: <plugin>_desktop.sh  // a .sh file which starts MadKit with the desktop 
                                       // and load the agents defined in the <plugin>.cfg file

The build.xml file is very important because it contains all the information needed to compile the plugin and make the jar, create the API documentation, and clean the plugin. Here are all the targets offered by this build.xml file:

The targets you will use most often are the 'jar' target (default one), the 'docs', and the 'real-clean' one. To execute such a target, go to the directory of the plugin, and type:

	> ant <target>

where <target> is the name of one the targets (or only ant alone if you want to use the default target).

It is also possible to execute such a target directly from the explorer {{link}} of MadKit

To define a new plugin, copy the template plugin which has been defined for this purpose and give it the name of the plugin. Then modify the .xml file as follows.

In MadKit, an agent is an object class that inherits from AbstractAgent class or one of its subclasses, and has the following capacities:

To compile your own agent, you'll probably have to import classes from the madkit.kernel package, so you must have the madkit.jar class archive somewhere in your CLASSPATH environment variable.

In the agent life-cycle, some functions are defined at AbstractAgent level, and other in the various subclasses that define more precisely its execution. This point is important as an agent can be executed within its own thread (by using the Agent class), or through the synchronous engine (see the Synchronous Engine guide). Thus, what is found in the AbstractAgent class is only a part of the description of the whole agent life-cycle

All abstract agents contain two specific sections, the activate and end section:

Activate section

When an agent is created, the kernel calls its activate() method. This method can be seen as a kind of "constructor" in the agent world. When an agent is instantiated and the constructor called, the kernel has not already setup the internal structures and registered it, thus you cannot use any of the methods of the AbstractAgent class (for example, to set up initial groups and roles)! All initialization of an agent must be done in the activate() method.

End section

When an agent terminates, due either to a normal termination of its behavior or a request to be killed (from the graphical host, from a system agent, ...), the kernel calls its end() method. However, this functionality is not as important as the activate(), and is rarely used.

An important point of agent life-cycle management is being able to launch new agents from an agent. To instantiate a subclass of AbstractAgent is not enough. It is necessary to register the agent instance to the social context (i.e. tables of groups and roles) managed by the kernel using the launchAgent(...) method.

An agent may also be killed using the killAgent(...)method.

Important: only the original launcher of an agent (i.e. the agent that has launched it), or the agent itself, may kill this agent

The standard class for information exchange in MadKit is Message. This class only defines things like sender, receiver or date of emission, so it's mostly used through specialized subclasses. Messages receivers and senders are identified thanks to their AgentAddress. MadKit does not enforce a standard interaction mechanism. Such a mechanism can be defined on an ad-hoc basis, or built in a specific agent model library.

Note: MadKit provides several kinds of predefined messages such as StringMessage, XMLMesssage and ActMessage. The latter is the starting point for defining ACLMessages and KQMLMessages. You may define your own class of message, by letting your class inherit from the class Message.

				
	    AgentAddress otherAgent = getAgentWithRole("travel", "contract-net", "bidder");
	    sendMessage(otherAgent, new ContractMessage("your-offer?"));
	  

	    while (true)
        {  
             Message m = waitNextMessage();
             println("The sender was: "+ m.getSender());
        }
	  

The group and role system is always available to an agent and provides both action and information calls.

The group API just takes the group name as parameter (a simple string) and the role-related calls always take the group name and the role name (also a string).

Here are their definition:

The MadKit graphic model is based on independent graphic components, using the Java Beans specification for building graphical components..

Each agent is solely responsible for its own graphical interface, in every aspect (rendering, event processing, actions...) An agent interface can be a simple label, a complex construction based on multiple widgets, or a legacy bean software module. A "graphic shell"(which is usually the MadKit desktop) launches the kernel and setup the interfaces for the various agents and manages them in a global GUI (for instance: each agent has its own window, or is mapped in a global worksheet, or is combined with another agent interface, ...).

As the graphic shell is a classic software module, it can be wrapped in an agent for maximum flexibility, allowing control of other agent interfaces by a regular agent that can be part of any interaction scenario.

There is also some miscellaneous calls that do not fall in the above categories. The getAddress() makes the agent return its own AgentAddress.

The couple setName(...) and getName() manipulate the agent name. The agent name can be altered during the agent life. The only thing that is unique and is used for messaging and group/role management is the AgentAddress. The getAgentInformation() returns an agent "identity card" (creator, age, ...).

Agents also have a minimal text output mechanism. The println(...) method outputs a line of text. The actual output can be redirected on a file, on the console or in an automatically launched GUI, depending on the platform configuration. Hackers can redirect this output stream with the setOutputWriter(...) method. A related utility is the debug(...) method, which outputs the parameter string only if a debug flag is set. This flag can be manipulated at run-time with the setDebug(...) call. The debug stream can also be redirected with the setDebugWriter(...) method.

A very important subclass of the AbstractAgent is the Agent class. This class defines an agent running in a concurrent thread. It is the most direct and easy way to define an agent.

With this class, the behavior of an agent must be coded in the live() method, which will be called automatically upon agent creation. Agents being defined with the Agent or one of its subclasses are recognized by the kernel, which handles the job of creating and starting the thread which will execute the live().

The class also provides a blocking version of the message reception call: waitNextMessage(). If this method is invoked and there is something in the message box, it returns immediately. Otherwise, the thread is suspended until something arrive.

An utility method, pause(...) is also provided, and can suspend the thread for the number of milliseconds given in parameter.

A classic agent implementation is an endless loop waiting for messages and dispatching them according to the message type:

protected void live() { while(true) { Message e = waitNextMessage(); if (e instanceof StringMessage) handleMessage((StringMessage)e); else if (e instanceof KQMLMessage) handleMessage((KQMLMessage)e); else if (e instanceof Message) handleMessage(e); } }

The Hello program

Example: here is the Hello agent which is defined in the template plugin. This agent first prints the message "Hello I'm an agent", then creates a group and attempt to play a role into it. If this work, it goes into an infinite loop, waiting for a message to handle it. This is obviously a very basic behavior. You should be able to do better :-)

public class Hello extends Agent { String myCommunity="myCommunity"; String myGroup="myGroup"; String myRole="myRole"; boolean alive = true; public void activate(){ println("Hello I'm an agent !"); // create a distributed group int r = createGroup(true, myCommunity, myGroup, null, null); if (r != 1) alive =false; else requestRole(myCommunity, myGroup, myRole); } public void live() { println("Hello world..."); while(alive){ Message m = waitNextMessage(); handleMessage(m); } } void handleMessage(Message m){ // You should describe here the agent's behavior // upon reception of a message } public void end() { println("\t That's it !!! Bye "); pause(2000); // just to be abloe to see the last message.. } }