Create an Agent Project

What is an Agent Plug-in, what an Agent Project?

This section shortly describes how you can define, develop and start your first agent-based "application". Even this is a very simple example, it will demonstrate the principle on how you can extend Agent.Workbench (AWB) with your own agents and further user functions. Since AWB is based on OSGI / Eclipse bundles, you have to develope OSGI plug-ins for your agent projects too. In the course of the text we are mixing-up these terms from time to time, but their meaning is the same (plug-in = bundle). For further reading and a practical introduction into the modularity concept of OSGI, we recommend to read this tutorial: http://www.vogella.com/tutorials/OSGi/article.html.

Eclipse Projects & Agent.Workbench Projects: We would like to mention here that, in the context of Agent.Workbench and Eclipse, the word "project" is used with two meanings. Since Agent.Workbench handles agents or Multi-Agent Systems (MAS) as self-containing projects on one hand site, also Eclipse uses the term "project" for Java or plug-in developments. This, in turn, makes it sometimes misleading, if we speak about an "agent project" in general. More precisely, we have to distinguish these project types to avoid a lingusitic misunderstanding.

As a prerequisite, we assume that you have an installed Agent.Workbench and an Eclipse IDE (Integrated Development Environment) that enables you to develop plug-ins (an IDE that enables Java developments only, wil not be sufficient). For further details see the Getting Started tutorial.

In short words: Our goal here is to create an Eclipse-Plug-in and a first agent, start and debug this agent from the Eclipse IDE and finally, to export the developed agent into a Agent.Workbench project so that the agent application can work on its own (without the IDE). For this the following steps are to be done:

  • Create a new Plug-in-Project in the Eclipse IDE.

  • Create an Agent: Define your desired package structure and create your first agent class.

  • Define a Debug-Configuration

  • Debug an Agent:

  • Export your agent bundle / plugin into the workbench's project directory and Agent.Workbench standalone. Open the above defined workbench project and have a look at the tabs [Resources] and [Agents], where you will find your exported bundle and your first agent.

  • Define a setup and start your agent application.

How can I create own Agents?

With the goal in mind, to develop your own agent-based application, the first step to do so is developing your own agents. Because Agent.Workbench is OSGI based, your extensions to it (your own agents) also need to follow this approach. So in the following, we are going to create a plug-in/OSGI bundle for a dummy agent to demonstrate the process. We want to create the agent, start it with Agent.Workbench and let it print "Hello world!" to the console.

The following steps require you to...

  • ... have an Eclipse IDE installed that enables you to develop Plug-ins ( Eclipse IDE for Enterprise Java Developers)

  • ... have Java version 8 (the 64 Bit version) installed and the Eclipse preferences for jre and compiler set to java 1.8

The source code for this example , as well as for other examples, is stored in a corresponding examples- project in our GitHub that you can find here.

In the course of this tutorial, we need to create several files in our plug-in. Each file has a reference to its code in our GithHub. In case you cloned Agent.Workbench from GitHub to your Eclipse IDE workspace, you can just copy and paste these files to the location you need it to be, and do some minor changes to it.

Creating a "Hello world!" agent

Create a new Plug-in Project in Eclipse under File > New > Plug-in Project.

Name the project "de.agent.test". The other text fields and check-boxes can maintain their default configuration. Click Next and then Finish.

Your plug-in now appears in your Project Explorer tab on the left. If you go into the plug-in hierarchy, you can see the JRE Systems Library which contains multiple .jar files, an empty src folder and a folder called META-INF. This stores the MANIFEST.MF file which is part of every plug-in. The file is important because it defines which dependencies your plug-in has, and which packages it exports.

The behavior of an agent is defined in a java class, that represents the agent. Thus, any agent class needs to extend the super class jade.core.Agent. This class is part of the JADE bundle org.agentgui.lib.jade that is part of Agent.Workbench. To use it, we have to define this library as a dependency for our plug-in. Therefore, we have to edit the MANIFEST.MF in the Eclipse Plug-in Manifest Editor and choose the Dependencies tab at the bottom of the view. Because we depend on multiple plug-ins throughout this tutorial, for convenience we are going to add them all in this step. Click Add and select the following bundles as Dependencies:

  • de.enflexit.api

  • de.enflexit.common

  • org.agentgui.core

  • org.agentgui.lib.jade

The bunlde org.agentgui.lib.jade contains the above mentioned agents super class, org.agentgui.core and de.enflexit.common are necessary for the class- load service that we are going to address later. The de.enflexit.api plug-in contains some helper classes.

Next we want to create a package, to store our agent class. Right-click the scr folder and choose New > Package. Maintain the generated package-name and click Finish.

To create the agent class, right-click the de.agent.test package and choose New > Class. In the appearing window name the class "HelloWorldAgent" and click Finish.

You can find the code for the HelloWorldAgent class here in our GitHub. In your code, you just need to change the specified package, in which the class is stored. You can quick fix this problem by moving your mouse over the specified line and choosing Change package declaration to "de.agent.test". This also applies to all following occasion, where we copy source code from GitHub.

What the HelloWorldAgent class does, is it overrides the setup() method from the Jade agent class to perform certain actions during startup of the agent. In our simple case we just want our agent to print "Hello world!" to the console.

At this point we implemented the core of our hello-world agent plug-in. In the next steps we are going to define the exported packages and adapt OSGI specifications.

Every plug-in that extends Agent.Workbench needs to offer a specific service, the class-load service. The class-load service is connected to a class called ClassLoadServiceImpl. To store the corresponding ClassLoadServiceImpl class we create another package in the scr folder, named "de.agent.test.classLoadService". In that package, create a new class called "ClassLoadServiceImpl". You can find the class code here.

To export the packages and thus make them accessible for other components, we need to adjust the MANIFEST.MF file in the Runtime tab. Under Exported Packages, click Add.

Select the two packages and Add them.

Since our plug-in has to be an OSGI bundle, it needs to comply some OSGI specifications. So to offer the class load-service OSGI conform, we must create a folder in our plug-in called "OSGI-INF" and then store a file called classLoadService.xml in it. To create the folder, right click de.agent.test, choose New > Folder. To create the XML file, right-click the OSGI-INF folder and choose New > File. Name the file "classLoadService.xml".

Get the code for this file from our GitHub and paste it to the Source tab, then save the file.

To see changes to the file, close and reopen the file or refresh (F5) the project. As a result an Overview tab appears.

The Name and the Class property specify the location for the ClassLoadServiceImpl class. Since our package structure differs from its original location, we have to set both, Class and Name property to "de.agent.test.classLoadService.ClassLoadServiceImpl".

Another OSGI specification requires us to add some OSGI specific headers to the MANIFEST.MF tab, in the MANIFEST.MF file. More precisely, we have to define our Service-Component and the Bundle-ActivationPolicy.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Test
Bundle-SymbolicName: de.agent.test
Bundle-Version: 1.0.0.qualifier
Automatic-Module-Name: de.agent.test
Bundle-RequiredExecutionEnvironment: JavaSE-1.8
Service-Component: OSGI-INF/classLoadService.xml
Require-Bundle: org.agentgui.lib.jade,
de.enflexit.api,
de.enflexit.common,
org.agentgui.core
Export-Package: de.agent.test,
de.agent.test.classLoadService
Bundle-ActivationPolicy: lazy

As a last step, we need to define the folders that must be included in the build. Check the boxes, as shown in the screenshot below, in the Build tab.

Starting the agent in Agent.Workbench

Now we created a fully operational agent, that we can use in Agent.Workbench. To demonstrate this, we have to add our de.agent.test plug-in to the run-configuration and start Agent.Workbench with it. As a prerequisite, you should have setup a run- configuration.

Open your Debug Configurations.

In your Debug Configurations, select your run-configuration and go to the Plug-ins tab. Our plug-in now appears under Workspace > de.agent.test. Select the plug-in and click Debug to start Agent.Workbench directly in debug-mode from your IDE.

In Agent.Workbench we want to create a new project, called "Hello world" (Instructions on how to create a project in Agent.Workbench can be found on this page).

In this project, navigate to Setup > Agent-Start. Click , select our agent and click Add.

Now our agent (HeWoAg) should appear in the start list.

We successfully added our own agent to our project. Now we want JADE to execute our agent, by clicking . Thereupon two windows will pop up, the Load Monitor and the Thread Monitor. Those windows are not important for us at this point, so we can just close them. If we now open the console by clicking , a console window pops up at the bottom.

If your console has the line "Hello world!" in it, congratulations! You just created your own, fully functional agent. Now this agent clearly does not deliver any practical benefit. But with completing this tutorial, you learned the basic skill of creating individual agents, and did the first steps any project developer does.

Assuming that our hello- world agent and Agent.Workbench represent a finished project, the next step is to export the project to make it a standalone end-user application.