Table of Contents
This chapter provides a technical overview of the ADK. It describes the Agent Runtime Environment (ARE) and introduces the Agent Foundation Classes (AFC). It also describes components distributed with the ADK, including the template project. Finally, it gives an overview of development management tools that help developers create and visualize their agents.
The following minimum system requirements are recommended prior to installing the ADK:
| Requirement | Description |
|---|---|
| Hard disk | 70Mb available |
| Memory | 128Mb minimum, 256Mb recommended |
| Processor | Pentium 500MHz or higher |
| Software | Sun Java Runtime Environment version 1.3.1 or 1.4. If you need to run the ADK on JDK 5.0, please contact Tryllian. The ADK will not work out of the box with version 5.0 of the JDK. The ADK has also been tested with Bea's JRockit JVM and with IBM's JVM; both appear to support running the ADK. |
| Network | For mobility, a network connection supporting TCP/IP is required |
| Database software | The out-of-the-box persistence requires database software. This product includes Hypersonic SQL. Persistence is also supported with the following databases : Oracle version 8.1 or higher (has been tested for Oracle 8i release 2 (8.1.7)), MS-SQL version 2.27, Mckoi version 0.92, Cloudscape 5.0, MySQL 4.1, PostgreSQL 7.2 or DB2 8.1. If you have additional database requirements, please contact Tryllian. |
| OS Requirements | The ADK runs on any OS for which Sun has made available a JVM. Windows 2000 and XP, Solaris and GNU/Linux are supported by Tryllian. Additionally, the ADK has been tested on OS/400, OS/370. Tryllian can offer paid suport for running the ADK on IBM mainframes or AS/400 machines. Apple's OS X is not supported, but part of the development of the ADK is done on OS X. |
The Agent Development Kit consists of two parts, the Agent Foundation Classes (AFC) and the Agent Runtime Environment (ARE). Most developers will interact with the AFC to construct their agents. The AFC encapsulates most of the functionality of the ARE and therefore you will mostly not need to use the ARE directly. In cases where the AFC does not encapsulate ARE functionality, you can still directly interact with the ARE.
In short, the Tryllian ADK allows application programmers to define all of the components that are required to build an agent-based application. The AFC is the main programming API and thus contains most of the interfaces and classes needed to interact with the agent-based elements. A few important interface classes, such as agent addresses are provided by the ARE, but used in the AFC as well.
An important aspect of creating an agent application is implementing your agent's behavior using tasks.
Another important aspect is the use of communication protocols between agents. The ADK provides some classes and tasks that simplify using agent communication.
Using the AFC, you can:
Create your own agents.
Create tasks for your agents to perform.
Create messages for your agent to send to other agents and create your own agent languages.
Log your agent's activities.
The kernel of the ADK is the ARE. As an ADK user, interaction with the ARE takes place indirectly. So although the ARE is the most fundamental part of the ADK, it's also the least visible one for you as an agent developer. The ARE presents itself to you through its System Agents, with which your agent can communicate. These agents never leave the habitat and provide a number of basic services such as moving agents to another habitat, keeping track of the agents in the habitat, etc. All communication between individual agents and the system is implemented by the ARE in the form of messages sent to a number of system agents. The ARE also implements the ADK's security features.
The agent template is a skeleton to create your own agent. It is found in the agent-template directory and uses ANT to create, compile, package and run agents. This template will perform all the activities previously described, as long as the build.properties and build.xml are correctly configured. In addition to the Agent Template, the ADK includes a sample project based on the Agent Template, that developers can use as a learning tool when building agent applications. Information about this sample project can be found in the ADK Scenarios documentation.
Agent deployment using the ADK requires several important steps that will be introduced in this section. Some steps differ from versions prior to release 2.0.
Agents are deployed using the DNA format. A DNA file is essentially a jar file containing jar files. Thus, agents can consist of more than one jar. Also, the DNA format requires all classes to be signed with a digital signature. DNA files are discussed in more detail in Section 4.7, “DNA Files”.
This project contains build scripts that use ANT (see ant.apache.org). Compile the example agents in the template. To build all agents, type build all. To only build one agent, specify the agent-name. For example, for an agent called example, type build example.
Now, you can run the first example, type habitat habitat\exampleHabitat.xml .
It will print:
[Example] Hello World
To stop the habitat, press "CTRL-C" or ask the habitat service manager (when running on Windows) to stop the habitat.
As stated, the Agent Template is found in the directory agent-template. The basic setup of this template is as follows:
| File | Description |
|---|---|
| build.bat | Windows build file |
| build.properties | Property settings for the build tool |
| build.xml | Build description (similar to Makefile) |
| habitat.bat | Windows habitat startup script |
| project.dtd | Document Type Definition (DTD) for build.xml |
| README.txt | Readme file for the template project |
Directories within the template (found in the directory agent-template):
| Directory | Contents |
|---|---|
| agents | DNA files of created agents |
| classes | Class files |
| config | Contains the security related files and other settings (including keystore) |
| descriptors | DNA deployment information (descriptor files) |
| documents | directory where user documentation such as manuals can be stored |
| habitat | directory where habitat startup scripts can be put |
| jars | Files generated from class files |
| lib | directory where project-specific third party libraries can be put |
| log | directory where the log files will be placed |
| projectsettings | directory where project-specific configuration files can be put |
| src | Java files (contains all code for agents and common code) |
Directories in the ADK directory:
| Directory | Contents |
|---|---|
| lib | The ADK libraries |
This section describes the basic steps involved with adding your own agent to the template. More information about creating agents can be found in the Agent Creation chapter (Chapter 5, Agent Creation). After having taken all these steps, you will be able to build and deploy your agent from the command line.
Note that this is not the only way agents can be created and deployed. An alternative solution would be to use the DeployTool, which lets you perform all steps after compiling your source code to class files using a GUI instead.
Write java code.
Put the new java source code for your agent in the src directory. It is advised to put every agent in its own package.
Write a descriptor file
Create a file named <agentname>.descriptor.xml and put it in the descriptors directory. A descriptor is an XML file that specifies the contents of a DNA file and the class of the agent described by the DNA. It can look like the following:
<agentdescriptor>
<target target-id="standard">
<environment>
<java areversions="1.3"
agentclass="AGENTCLASS"
/>
</environment>
<file name="agent.jar"/>
<shared-ref type="stdlib" name="afc"/>
</target>
</agentdescriptor>
Replace "AGENTCLASS" with the class name of your agent, for example "tryllian.template.myagent.MyAgent".
Different agents can be stored in different jar files; however, to simplify matters, all agents can also be stored in one jar file. In this case, all agent code is in agent.jar. This means that all descriptors will have the same "file" tag:
<file name="agent.jar"/>
Since all agents use the AFC, they have the same shared-ref:
www
<shared-ref type="stdlib" name="afc"/>
Create an ANT target.
A new ANT target is needed to actually generate the DNA file. Create a new target in the file build.xml that looks like the following:
<target name="AGENTNAME" depends="init, jar">
<dna dna="${agents.dnadir}/AGENTNAME.dna"
agentdescriptor="${relative.descriptors}/AGENTNAME.descriptor.xml"
keystore="${jarsign.keystore}"
alias="${jarsign.tryllian-developer}"
storepass="${jarsign.password}">
<content
name="agent.jar"
file="${relative.jarfiles}/agent.jar"
target="standard"
/>
</dna>
</target>
Replace the three occurrences of AGENTNAME with the name of your agent, for this example, use "myagent". In order to make the target called "all" create your agent, add the agent's name to the "depends" attribute. This can be done by modifying the following line from
<target name="all" depends="example"/>
to
<target name="all" depends="example, myagent"/>
Now, you can type build all to create your new agent. For more information on ANT, refer to its website (jakarta.apache.org/ant). In addition, the ANT document, found in the directory docs\devguide\ant.html of your ADK installation directory, introduces several custom ANT tasks distributed with the ADK and describes how these tasks can be used.
Create your own habitat XML file.
To run a habitat with your agent, modify the exampleHabitat.xml (or create your own XML file). A habitat XML file describes which agents are found in the habitat. Look at the following example:
<habitat>
<agent dna="agents/example.dna"/>
</habitat>
If you want to add your own agent, put an "agent" tag in a habitat and specify the location of the DNA file of the agent. You must also specify the directory where your project is located (in this example, it is "agent-template").
At some point, you might want to use third-party libraries for your agent, such as the JMF (Java Media Framework) or an XML parser. First, add the library to the build classpath. Edit the property project.classpath in the build.properties file. Then, add the library to the DNA file by modifying the descriptor file and, if necessary, the ANT target.
Libraries can be added to the DNA in two ways:
Add as a file.
This will add the library to the DNAfile of the agent. You still have to add a "file" tag in the descriptor XML file that names the file. Don't add a path, just specify the filename!
<file name="MyJar.jar"/>
Then, you must edit the ANT DNA target in the build.xml file that produces the DNA by adding an extra "content" tag.
<content
name="MyJar.jar"
file="path to/extra.jar"
target="standard"
/>
At this time, "standard" is the only target you can specify.
Adding a library as a shared ref will introduce a reference to the library from the DNA file. This will save disk space, because only one copy of the file is needed. The afc.jar is an example of this. The library must be registered in the "dna.catalog" of the ADK config directory to do this.
Add the following entry to the dna.catalog file:
<alias>=file:${are.home}/agent-template/lib/ThirdParyJar.jar
You also need to add a shared-ref entry in the descriptor XML file:
<shared-ref type="stdlib" name="alias"/>
In any case, don't forget to sign your shared reference libraries using the jarsigner tool. The shared reference libraries that the ADK packages are already signed.
The sample project examines smaller demo projects. For larger projects, it is not practical to have a single jar file containing classes for all agents and the application. Creating one or more jar files containing the general classes can solve this. Also, create one jar file per agent that only contains those agent's classes. There are two approaches to this, and the following sections provide some direction and hints. However, before trying these approaches, it may be useful to be familiar with using ANT and the structure of DNA files.
The directory structure does not have to be modified for this situation, but new jar targets for each jar must be created. Refer to the ANT jar task to see how to include only specific packages and/or classes in a jar. Additionally, the DNA targets should be modified to reflect the new jar structure. Finally, the agent descriptor files should also be edited by changing the "file" tags.
This approach is the best way to avoid undetected dependencies between classes that would not be found using the previous approach. This method does not require you to specify the package, since you put the entire classes directory into your jar file, but adds some complexity to your source structure. A possible setup for this:
Produce a "sources" directory containing a directory for every jar to be produced (i.e., for every agent and for every "common" jar) instead of a single "src" directory. These directories contain their own "src" and "classes" directory.
sources/agent1/src
sources/agent1/classes
sources/agent2...
sources/common/src
sources/common/classes