# 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.](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 (**I**ntegrated **D**evelopment **E**nvironment) 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](https://enflexit.gitbook.io/agent-workbench/development/basic-steps/installations) 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 [defined a target platform](https://enflexit.gitbook.io/agent-workbench/development/basic-steps/define-a-target-platform)
* ... 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](https://github.com/EnFlexIT/AgentWorkbench/tree/master/eclipseProjects/org.agentgui/examples/de.enflexit.awb.samples.Examples).

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*.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-743838b38ec95d86d18b854557e2f0a163dffe74%2Fhewoagpluginproject.jpg?alt=media\&token=fc3ca1d8-2995-4e5f-90fd-81dca2d8f387)

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

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-07b4d755cb9a41838280a8c16bbcc2932ce0f2d3%2Fhewoagcreateplugin.jpg?alt=media\&token=6f8bc490-48c1-4f70-b7fa-e6bd0adb4c9b)

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.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-4649747e40bebfd93ecccb26a2eeb391bdbd57dd%2Fhewoagplugincontent.png?alt=media)

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*

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-2003ca4b0a88fe948c498aeccbeff3e6557e2132%2Fhewoagdependencies.png?alt=media)

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.ap\_i 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.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-3b52c5a9e501952b1c8f83590429cb5c1cd704a2%2Fhewoagpackage.png?alt=media)

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*.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-aca3c6803e807b5713652a9be64b30efaeed6a06%2Fhewoagclass.png?alt=media)

You can find the code for the HelloWorldAgent class [here ](https://github.com/EnFlexIT/AgentWorkbench/blob/master/eclipseProjects/org.agentgui/examples/de.enflexit.awb.samples.Examples/src/de/enflexit/awb/samples/example01/HelloWorldAgent.java)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.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-442dd78943fee619d0ae3353fd037303299436de%2Fspecifypackage.png?alt=media)

{% hint style="info" %}
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.
{% endhint %}

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](https://github.com/EnFlexIT/AgentWorkbench/blob/master/eclipseProjects/org.agentgui/examples/de.enflexit.awb.samples.Examples/src/de/enflexit/awb/samples/classLoadService/ClassLoadServiceImpl.java).

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.*

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-3e8fe4b86f8ccd86b0f3e9ade3c71426314babdd%2Fruntimetab.png?alt=media)

Select the two packages and *Add* them.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-c597656db1443123c7455b9c2f87a2253062e78c%2Fhewoagpackexport.png?alt=media)

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".

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-ff4ebeec5af661ce4845b0faf7ba67a230472b4a%2Fcreatexmlfile.png?alt=media)

Get the [code for this file](https://github.com/EnFlexIT/AgentWorkbench/blob/master/eclipseProjects/org.agentgui/examples/de.enflexit.awb.samples.Examples/OSGI-INF/classLoadService.xml) from our GitHub and paste it to the *Source* tab, then save the file.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-1f640506401337f649cd68d106db07951575edf0%2Fsourcetab.png?alt=media)

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

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-fc040838727791fbe428d47a062b701d299b4d0b%2Foverviewtab.png?alt=media)

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".

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-1b13d751727da664bbc0b5b395cd62d13b7c8bfa%2Fchangeproperties.png?alt=media)

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 S\_ervice-Component\_ and the *Bundle-ActivationPolicy*.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-850e427a4367db79291cd87c33fdd8ee8de4a473%2Fmanifestmf2.png?alt=media)

```css
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.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-4495f2866d85e6e995080941967bde9097573098%2Fhewoagbuildfolder.png?alt=media)

### 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](https://enflexit.gitbook.io/agent-workbench/development/starting-awb-from-eclipse#setup-the-run-configuration).

Open your *Debug Configurations*.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-84191acf62b96bcc54326005d2be140455b78aad%2Fopenrunconfig.jpg?alt=media)

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.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-70521c6b170a4088cd9c7a76511b1f51d1f4a2a2%2Faddplugintotunconfig%20\(1\).jpg?alt=media)

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](https://enflexit.gitbook.io/agent-workbench/development/basic-steps/installations) page).

In this project, navigate to *Setup* > *Agent-Start.* Click ![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-c288541e408557e0df4191682ac0dfcd2f7bddf5%2Faddagenticon.png?alt=media) , select our agent and click *Add*.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-c9d63e206a7cdaacf5ffe238c2bfb89a14d167a5%2Fhewoagselection.png?alt=media)

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

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-8973c268ec74ea71eb22d46c26f4c284dd7342a6%2Fhewoagstartlist.png?alt=media)

We successfully added our own agent to our project. Now we want JADE to execute our agent, by clicking ![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-19789bf1dded6ad6ed29a310ec667f936d481b43%2Fjaderunicon.png?alt=media) . 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 ![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-6f9c29b88743e1a8f71c26242e80252b74edca7b%2Fconsoleicon.png?alt=media) , a console window pops up at the bottom.

![](https://874617837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LL95HBh1KIqu90YyWBK%2Fuploads%2Fgit-blob-b7bf03a2d58984a2aa565c7f983ba8d8714ac172%2Fhewoagconsoleoutput.png?alt=media)

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://enflexit.gitbook.io/agent-workbench/development/basic-steps/create-a-project-plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.