Getting Started

After installing AgentScape (see Downloads) you can start using AgentScape. The basic steps for this are:

  • Configuring and starting the middleware
  • Configuring and starting an agent

All of these functionalities can be performed using the configuration GUI. This utility is available as a JAR file in the installation directory.

  • lib/config.jar

Basic middleware configuration

As explained in the concepts section, each AgentScape world consists of a Lookup Service, at lease one Location Manager and one Host Manager. We will demonstrate how to start this using the configuration GUI. Create a new configuration file (a “WORLD” type) and you will see the configuration GUI which displays an empty world configuration without locations and hosts.

Right click on the “world” node and select Add Location. Right-click on the new location node and select Add Host (or use Edit > Add > … from the menu bar). The window will look like the next picture.

This is a minimal configuration file which you can save and use to start an instance of the middleware. For now, save it to location.xml. No services will be started on this host and it will use the public location service to add itself to the public agentscape world.

If you don't have internet access, or you want to setup a new (private) world, select the “WORLD” node and check the button Start lookup service. This prompts to select a host that starts the world lookup service. Attaching your hosts to an existing world allows remote agents to be migrated to (and away from) your machine - if there are no firewalls restricting access to the machines.

The middleware can be started using the Run menu, or by pressing CTRL-R. Because there is only one host defined, this host will be started automatically. Otherwise you will be prompted to select the host you want to start. You will see a window with the console output of the middleware platform. You can close this window if you want to (it can be shown again via the Run menu) or you can kill the platform. For now, just leave it be.

If all is well you should observe no warnings from the console output. In this case, a middleware process is running on your machine. It runs the host configured as Host_1. Moreover, it also runs a Location Manager service for the location Location_1. Now, a location has been setup and you can start running agents.

Running agents

AgentScape can be installed with a number of example agents. These can be started by creating an application configuration. You can do so by selecting File > New and then selecting the “APPLICATION” type configuration. You can add a number of agents to the configuration by right-clicking on the application node and selecting Add Agent.

In its simplest form, an agent is packaged as a self-contained JAR file. A standard installation contains several such agents in the agents directory. Select the new agent node and click on the Browse button. Navigate to the agents directory and select the agent-demo-migration-2.0-xx.jar file (depending on the version you have installed).

You can perform more configuration, but for now save the configuration to a file application.xml and then open the Run menu item. If your AgentScape host is still up and running, this will prompt you for a location to start the application. Select Location_1 and press OK.

If all goes well, a window will popup on your screen that looks like the following picture. This is a window that is being displayed by the migration agent and allows for user interaction. An agent does not need to have a GUI window, but all the demonstration agents that come with the distribution have one.

The migrating agent demo has the option to migrate to a remote location. This requires multiple locations to be connected to the same world. If you started your own world lookup service, there will likely not be any other locations to migrate to. Setting up another host and location is easy enough, and will be demonstrated in the next section(s).

Advanced middleware configuration

This section provides some more advanced topic on middleware configuration. This deals with setting up services, distributed location(s), using the commandline tools and more.

Host & service configuration

Services are modules that provide functionality for agents. Just as agents, these are not part of the middleware, but can be added dynamically to the middleware installation. At the moment, services can be activated and configured at startup time. A minimal AgentScape installation has some built-in services which are always available for agents and do not need to be configured:

  • Directory service (org.iids.aos.directoryservice.DirectoryService) More info
  • Thread service (org.iids.aos.service.local.ThreadService) More info
  • Timer service (org.iids.aos.service.local.TimerService) More info

Additional services can be developed independent of agentscape. These can perform anything from application specific tasks to more generic functionality. The following services can be installed via the AgentScape installer and are supported by the AgentScape development team.

  • Servlet Service (org.iids.aos.servlet.api.ServletService) More info
  • Blackboard Service (org.iids.aos.blackboardservice.BlackboardService) More info
  • ActiveMQ JMS message bus ( More info
  • WebService Gateway ( More info

These plugin services are installed in the AgentScape installation directory in lib/services. The API and other shared libraries are located in lib/shared. However, plugin services need to be explicitly activated and configured otherwise they will not be used. This can be done using the configuration utility.

Services are always running on an AgentScape host and are configured as such. If you have some services installed, they can be added to a host from the configuration utility by right-clicking on the host node and selecting Add Service. If you have some services installed, a dialog will popup which will automatically detect the properties of the installed services. In the next example picture, a Servlet Service has been added to the host Host_1. Selecting the service in the tree node allows to configure the service.

Most properties (interface, implementation, etc) do not need to be changed. However, the access control can be configured from this dialog (HOST is the default setting). If the service is configured to LOCATION access it can be accessed from agents on other hosts in the same location as well, whereas WORLD access allows the service to be accessed from any location in the same world.

Some services required some parameters. These can be modified using the Add/Delete buttons. Currently, there is no list of predefined arguments for a service so these will have to be known in advance.

Plugin services are automatically published in the DirectoryService! This makes them automatically discoverable by agents on other locations. That is, if the directory service has been correctly setup. See the next section on how to configure this directory service in a distributed environment.

Distributed system setup & deployment

One of the main advantages of AgentScape is that it is not very complicated to setup a distributed environment consisting of different hosts and locations. The configuration editor allows to specify multiple locations (possibly with multiple hosts) in a single configuration file. For example, our sample configuration file can be extended with an extra host in Location_1 and another location as well. This will lead to a configuration similar to the one shown in the following picture.

Here we see a tree structure of our new world. It is important to note that some hosts have more important roles, and are required for the startup of other hosts.

  • Host_1 is the location manager of Location_1. It also runs the world lookup service and the servlet service.
  • Host_2 runs no special services
  • Host_3 runs the location manager for Location_2.

The following dependencies exist here:

  • Host_3 requires the lookup service to be running (therefore it depends on Host_1).
  • Host_2 requires the lookup service and Location_1 to be running (therefore it also depends on Host_1).

Using the GUI, all of these hosts can be started (as long as Host_1 is started first). You can copy over the configuration file to different machines and start each host from another machine. However, the commandline tools can also be used for this (in this case boot.jar - see next section).

Distributed Directory Service

One service that is not automatically distributed is the Directory Service Backend. A directory service is always available on a host, but it is important to know that each host has its own directory service, with its own local storage. This makes it impossible to discover information published in the directory on a remote host. To this end, the DSBackend system service is available. It is disabled by default, but can be enabled to act as a central repository for directory information. If such a backend is available anywhere in the world, each host in the world will store its records there instead of locally. Usually, the host that starts the lookup service will also start the DS backend.

This is not really a distributed solution, but systems of relatively modest scale and usage it may perform just fine. Enabling this requires only a few steps with the GUI: select the host to start the backend (in this case Host_1) and tick the box Custom system services. Select the DSBackend service and click on Enabled. Now, as soon as Host_1 is started, all directory records in the world will be collected on this host.

Commandline tools

There are a number of commandline utilities available which may be convenient to use on systems that cannot use the configuration GUI (like on a server or in a startup script). These commandline tools do not allow modification of the definition files, but can take an existing configuration and start it.

boot.jar starts a host from a configuration file. If the location.xml file only contains a single host, the second argument is not needed. Otherwise it is required to specifiy the HostID (name) here. For example:

java -jar lib/boot.jar location.xml [Host_1]

app.jar starts an application from a configuration file on a location. In the following example, the application from app.xml is started on Location_1.

 java -jar lib/app.jar app.xml Location_1

aslookup.jar starts a standalone lookup service. This may be useful if you want to setup a central world lookup service without starting a host and a location. For example, the public (default) lookup service at is a standalone lookup service. Anyone can connect to it, but there are no hosts using it by default. You can (optionally) specify a port where the service listens on.

java -jar lib/aslookup.jar [port]
usage.txt · Last modified: 2012/11/06 12:07 by clark