Preface

Agent technology promises to revolutionize the World Wide Web and a range of other domains.[1]The prospects for the development of artificial intelligence are only now beginning to be glimpsed. From information agents searching the web, to a new kind of travel agent helping drivers/travelers navigate traffic and busy schedules, to stock agents aiding in the management of user portfolios, to agents joining forces in the defense against terrorism, the ubiquitous use of agent technology is beginning to see the light of dawn.[2]

Despite the heralding of a new age of computing and integration of artificial intelligence into everyday life, there has been very little distribution and implementation of agent technology on a routine basis.[3]

Given the widening gap between promises of widespread use and actual availability, we at the Intelligent Software Agents Lab wanted to develop a means by which agent technology could be made accessible, both physically and technically, to expert agent developers/programmers, as well as early, non-expert adopters of agent technology. We wanted to produce a package that would allow comparatively easy building, testing and interacting with agents and communities, while also allowing expert developers to experiment with complex agent configurations.

Furthermore, and admittedly as a means for promotion of our own research and development, we wanted this distribution to be based on the RETSINA model of agent community architectures. We feel that the RETSINA system merits this promotion and distribution, given its advanced development and the demonstrably sound principles on which it has been based (see below). This RETSINA Agent Foundation Classes (AFC) kit is the result of the RETSINA research vision and the need for an Agent Building kit that meets the demands for relatively wide distribution and easy assembly and use of agent technology.

While the RETSINA vision for agents and agent communities is described in detail in our academic publications,[4]a brief overview of this vision is in order here.

Since the inception of agent research, we have acknowledged that while agents of any complexity could theoretically be developed, their actual use would always depend on their functioning within a community of other agents and software infrastructure. That is, we assumed from the outset that agents are social, that other agents were often different than themselves, and that agents should be free to join and leave communities “at will.” Given these and other conditions, agents should nevertheless be able to find and communicate with each other. It was under these assumptions that we developed the RETSINA Multi-Agent Infrastructure (MAS). This infrastructure would not impose constraints upon individual agent design. It would not limit agents to one language. It would not require a centralized system of registration and communication. It would support the ongoing introduction of new agent types and services.

As one can see, these acknowledged conditions begin to suggest requirements for an MAS. To meet these requirements, we developed a communications language that would allow different types of agents to talk, despite speaking different languages (LARKS). We developed a “white pages” directory that allowed agents to have names and addresses available to each other and to infrastructure components (Agent Name Server or ANS). We developed a “yellow pages” that allowed agents to locate other agents who fit descriptions of service providers they needed (Matchmaker). We developed a means by which agents who had little or no knowledge of each other could find each other in either Local Area Networks (LAN) or Wide Area Networks (WAN). This means is known as Discovery. Finally, we have demonstrated the interoperability of disparate agent communities by means of an “Interoperator,” a translation agent who can mediate between heterogeneous MASs.

This kit represents the first release of RETSINA MAS agents and infrastructure to a wider public. While the entire capability of our agents cannot be included here, we have provided the main components of our agents and their infrastructure support, as well as the libraries for the more complex agent development. We invite you to test the agents provided, to build your own agents and agent communities, and to provide feedback to our researchers and developers.

For more detailed information about the RETSINA MAS Infrastructure, please visit our website at http://www.cs.cmu.edu/~softagents

PART I: OVERVIEW, System REquirements AND INSTALLATION

Overview: RETSINA Agent Types, Agent Classes and Multi-Agent System (MAS) Infrastructure

Before you begin with the installation and use of the RETSINA agent libraries and Developers’ kit, you should have some understanding of the agents you will use and build, and their relationship to the agent system where they will live. Here, we will introduce you to the agent types and classes on which the AFC is based, and the RETSINA MAS to which they contribute and from which they derive their design parameters.

The advantages of this agent-builder kit are those derived from the RETSINA MAS itself (see Introduction). Using the AFC, you will be able to build agents that can

1. Interoperate with each other, and other, heterogeneous agent types and systems;

2. Advertise their services and capabilities, and find agents whose capabilities they seek, using the RETSINA Matchmaker;

3. Find and communicate with each other across distributed systems, on a peer-to-peer basis;

4. Link to a planning or reasoning component that controls the activities of the agent.

In this Guide, we will illustrate each of the features of the system, by means of examples. After most of the examples, we give step-by-step instructions on how to build them. The developer can then go on to build other agents and agent interactions.

RETSINA Agent Types

In the RETSINA MAS, there are four primary agent types: Information Agents, Task Agents, Interface Agents and Middle Agents.

Interface Agents interact with users, receive user input, and display results to users.

Task Agents help users perform tasks. They formulate problem-solving plans and carry out these plans by coordinating and exchanging information with other software agents.

Information Agents provide intelligent access to a heterogeneous collection of information sources

Middle Agents help match agents that request services with agents that provide services.

We discuss these agent types, their uses and construction, in the course of this Developers’ Guide.

In addition to these agent types, the RETSINA MAS Infrastructure includes the Agent Name Service (ANS) server. The RETSINA ANS server acts as a registry or "white pages" of agents, storing agent names, host machines, and port numbers in its cache. The ANS server helps to manage inter-agent communication by providing a mechanism for locating agents.

When an agent becomes active and an ANS server is available, the agent registers with an ANS server by providing its name, host name, and port number. An ANS server keeps a list of agent locations, so that, should agents relocate to different host machines, other agents will still be able to find them. Agents locate other agents by querying ANS servers that store the location data of the agents that they wish to find. The means by which agents locate ANS servers and each other has been radically revised by the addition of Discovery.

The RETSINA MAS Infrastructure includes the Matchmaker. The Matchmaker helps make connections between agents that request services and agents that provide services. The Matchmaker serves as a "yellow pages" of agent capabilities, matching service providers with service requestors based on agent capability descriptions. The Matchmaker system allows agents to find each other by providing a mechanism for registering each agent's capabilities. An agent's registration information is stored as an "advertisement," which provides a short description of the agent, a sample query, input and output parameter declarations, and other constraints.

When the Matchmaker agent receives a query from a user or another software agent, it searches its dynamic database of "advertisements" for a registered agent that can fulfill the incoming request. The Matchmaker thus serves as a liaison between agents that request services and agents that can fulfill requests for services.

Discoveryis a means by which knowledge of agents and infrastructure entities is propagated in Local and Wide Area Networks. Using Discovery, agents are dynamically registered and unregistered on multiple ANS servers, and clients (a module in the agent) and servers update their lists of available agents and servers on a dynamic basis. As agents and ANS servers come and go from the network, the client and server lists are expanded and contracted respectively. Agents can be initiated before an ANS server is online, and instead of failing, they will register with an ANS server when one becomes available. ANS servers can be updated with knowledge about agents from other servers who relay agent registrations and unregistrations to them. We describe ANS and Discovery below, and in more detail in the document entitled ANS v.2.8 (file name: javaANS.PDF – included in the CD distribution and online at http://www.cs.cmu.edu/~softagents/ans/ANSv2.9.PDF).

Agent Design in RETSINA AFC

Agents can be designed and built in many ways. Several toolkits (AgentBuilder, JADE, Tryllian) already exist. Each of these toolkits implements agents differently, based on different design philosophies and different agent architectures. The agents built with the Agent Foundation Classes are based on the RETSINA software agent architecture. In Figure 1, we show the RETSINA agent types, as derived from the basic agent:

Every agent is based on the basic agent. In AFC terms, every agent inherits from the BasicAgent class. Any class derived from the basic agent is part of the Agent Abstraction Layer (AAL). All other lower level components are part of the Communications Abstraction Layer (CAL). These CAL components are used by the basic agent, and are of course available to all agents. Of these CAL components, the Communicator module and one or more look-up modules are already incorporated into the basic agent.

Even though it is possible to write an agent based on the BasicAgent class, it is recommended that agent creators and programmers base new agents on one of the existing sub-classes deriving from the basic agent. These four agents are the second level down in the inheritance tree.

Within this tree there are several more levels, depending on the complexity of the agent class and how much development exists along a branch. For example, as Figure 2 shows, middle agents can be further refined into: Matchmakers, Brokers and BlackBoards. We have identified sixteen types of middle agents in our research, but in AFC only provide the three types shown below. Developers are invited to derive their own set of middle agents.

Figure 2

Anatomy of an Agent

Before exploring agent functions, we first need to define an agent, and how we can view them from a software standpoint. We could describe a generic agent as a standalone survivable piece of code with communicative and intelligent behavior. What should be noticed immediately is that this describes an entity that is completely separate from any system design or configuration. We therefore need a construction abstract enough to facilitate intelligent behavior, while also allowing for integration into existing operating systems.

Figure 3

The mechanism by which we do this is called “containment.” We contain the agent in a sub-shell with a well-designed Agent Protocol Interface (API), so that developers can write custom binding for specific operating systems and architectures. The actual abstract agent is what we will work with to create complex agent types. Figure 3 illustrates the principle whereby the barrier between operating system and agent is termed the AgentShell, and the Agent base code (base class) itself is termed the BasicAgent.

The agent shell has two main functions. First, it makes the existence of an agent possible in the world of heterogeneous operating systems. Secondly, it provides the agent with a number of basic facilities. For example, when writing a shell, a developer will have to provide the agent with a one second resolution timer. It will also have to handle messages originating from within the agent regarding its operation. An agent can indicate that it wishes to shutdown or, if it has a visible client area, it can indicate that this should be minimized or even hidden from view. A number of pre-defined agent shells are shipped with the AFC distribution. These standard shells are:

- CDlgContainer, a Microsoft MFC based shell that encapsulates an MFC dialog window;

- CSDIContainer, which can be used to create MFC SDI based applications;

- CMDIContainer, this is the same as the previous shell but creates an MDI window;

- CQtContainer, A Unix and Windows targeted shell for visual agents;

- CDeamonContainer, a shell for Unix daemon development;

Figure 4

The instructions below (see Building the First Example Agents) contain detailed instructions on how to develop a new agent shell using the BasicAgent class.

For generic agent development, you do not need elaborate knowledge of the operating system or agent shell programming. You will most likely remain within the basic agent context and will use the tools provided by the AFC.

The basic agent itself runs and manages a set of client modules designed to manage data and dialogs with external entities, as shown in Figure 4. Their tasks can range from providing file logging to interaction visualization, to middle agent interaction. The AFC provides a number of tools and base classes to develop custom clients, and we highly recommend their use whenever an agent is designed to interact with other agents.

All of the modules managed by the basic agent are run separately and have no direct influence on one another. This modular independence makes the agent more robust and prevents total agent failure due to a cascading effect.

Basic Agent Behavior

Every agent designed and developed with the AFC will incorporate a set of basic behaviors. These behaviors were developed for the agent’s survival, maintenance and management.

Agent Life Cycle

All agents constructed using the AFC SDK will have a fixed and well-defined life cycle. Each stage of this cycle represents a checkpoint at which either the agent or agent developer can influence the behavior of the agent. Since all AFC agents are event driven, so too is the life cycle. Each cycle or stage can be triggered by an

- Internal event

- External event

- Agent developer imposed event

In the process of the development of your agent, you will be confronted with decisions regarding each of the agent’s life stages. There are a number of main events/triggers that drive the cycle transitions. All of the events and stages are managed and generated by the Basic agent. There are 5 main stages an agent can experience during its lifetime. These are:

- Agent Birth

- Agent Initialization

- Agent Creation

- Agent Main

- Agent Shutdown

- Agent Destruction

The stages listed above correspond to virtual methods within the CBasicAgent class. Within the Main stage, an agent can be given more detailed events. (The Main stage is the main running loop of the agent’s life cycle). Overriding one or more of these methods will provide you (the developer) with control over the agent’s general behavior.

Other methods are provided to govern and refine your agent. For instance, every agent is equipped with lookup modules, which give your agent the capability to investigate its network surroundings. There are also modules designed to work specifically with specific infrastructure components such as matchmakers and logging agents. We will explain how to work with these events in the section below entitled, “Building the First Example Agents.”

Agent Logging Behavior

Every agent is configured with one or more file-logging modules. These modules provide detailed information to external entities as to the functioning of the agent. The file-logging module allows an agent to stream internal events to a file on disk. The file contains detailed information on the agent’s actions. We will demonstrate in a later section how to add entries to the log-file. All log-files are maintained in the root (RETSINA) directory under a subdirectory called “Logfiles”. These files are organized in date-stamped directories. (See Installation Instructions, below, for how to manage the behavior of logging modules). All log-files are created by the agent in a directory with the name of the day and month on which the agent was started.

Agent Process ID (PID)

All agents built with the AFC maintain PID files in the RETSINA system directory. The PID provides for the following functions:

1) It assists agents in identifying other agents running on the same platform. If it is programmed to communicate with a user via a voice, for example, an Interface agent should be able to find a SpeechAgent running on the same system.

2) It allows agent management tools to rapidly see what agents are running and what agents have crashed, by providing a comparison of the file entries with the list of agents actually running on an ANS server.

System and Software Requirements

To use the RETSINA Agent Foundation Classes you will need

Pentium 90Mhz
16 Mb RAM
A minimum of 50 Mb free disk space for full installation
2x speed CDROM
Windows 95/98/NT/2000/Xp

The version of the RETSINA Agent Foundation Classes as described in
this manual requires that the following applications are present prior to
installation:

1. Visual Studio 6.0 (this has to have been run at least once prior to AFC installation)

2. Java 1.2 or higher (runtime environment)

Networking

To run agents on your own computer only, you do not need to be connected to a networked domain. To discover and communicate with agents running on your local area network (LAN) or across networks (WAN) (see Discovery section below), you will need a live Ethernet connection.

When we refer to Agent Name Servers below, we mean an agent infrastructure component that can reside locally on your machine. You can register with an ANS server on your own machine; you do not need to be connected to a specific network to connect to an ANS Server, but in order to find and communicate with other agents, you will need to find and register with non-local ANS servers using Discovery.

Installation Instructions

1.p; You must be logged in to Windows as the “Administrator” in order to properly install the AFC. If logged in otherwise, restart and login as “Administrator.”

2.p; Insert the AFC Development Kit CD-ROM into CD ROM Drive. The CD should start up automatically. If it does not, go to “Start” menu, scroll to “Run” and browse to the CD-ROM drive. Select the setup.exe file and click ok.

3.p; A welcome GUI (shown below) for the Installshield™ Wizard, which installs the RETSINA Agent Foundation Classes, should appear. To begin installation, click “Next.”

4.p; Please read and accept the CMU licensing agreement.

5.p; The Read-me file will appear. It contains information on the latest updates, which may not be reflected in this manual. It will be stored in the directory for the software. Click “Next.”

6.p; The next GUI is for setting the installation path. This path designates the root location where all the libraries, files and examples will be stored. The default path is C:\program files\RETSINA. You can change this path, but we recommended that you do not.

7.p; The next GUI is the “Setup Type” window.

Choose installation type and click “Next.” The options signify:

a.p; Administrator (for WinNT 2000 and XP, for installation of multiple users).

b.p; Compact: installs the smallest configuration necessary to build agents: for users with limited drive space or who do not need agent examples. Not recommended for first-time users.

c.p; Custom: To choose components. For experienced users.

d.p; Typical: To install complete set of files. This is the default and recommended installation setting.

8.p; The next window, “Start Copying Files,” is an overview of the installation. In this part of the installation, the program detects whether or not C Visual Studio 6.0 is installed on your computer.

In the figure below, you can see that version 1.10 of AFC will be installed and that the program has detected the presence of Visual Studio 6.0. Click “Next” to begin the installation.

If Visual Studio 6.0 has not been installed, cancel the installation. Install Visual Studio 6.0, and run it at least one time before reinitiating the installation.
If you have Visual Studio 6.0 installed, and it is not detected by AFC, then you may have never run the program. In order to set its environment, the program needs to run at least one time. Cancel the installation and run Visual Studio 6.0, then recommence installation.

9. Click “Finish”. The installation is complete.

General Running Instructions: Running An Agent

Note: This section provides general reference information on running agents. Follow the instructions in the example sections to begin running your first agents.

When you navigate to the directory examples (see instructions for using examples, below) you will find example projects with fully working agents.

Step1, Starting an Agent

An agent can be started in two ways, either by double clicking its icon or by starting it from the command line. There is a clear distinction from the agent's standpoint what the different methods signify. When an agent is started by double-clicking its icon, it assumes that it will have to find its basic information somewhere on disk, or from the user. When an agent is started from the command line it will expect to supplement the information it finds in well-known locations and resources with the information supplied in command-line parameters. If it doesn't find that information, it will revert to the first method, as if it had been started as an icon.

Every agent understands a number of command line parameters. Below is a list of all the parameters that every agent build with the Agent Foundation Classes understands:

Parameter:	Value:	Example:
-name	The name of the agent as should be registered with an ANS	-name SpeechBroker
-help	Show a help screen which explains the command line options	-help
-port	This specifies what port the agent should use for listening	-port 6678
-ansname	The hostname or ip address of the ANS	-ans midea.cimds.ri.cmu.edu
-ans	The port at which the ANS server is listening	-ans 6677

Every agent is compiled with a number of internal client modules. These modules complement the agent’s basic behavior and allow inspection of its internal workings. Other modules dictate basic behavior such as:

· Register with a MiddleAgent

· Process and/or propagate window parameters to the agent shell

· Enable/Disable internal components to create non-communicative agents

Below is a list of additional parameters that can be used to control a number of non-essential modules.

Parameter:	Value:	Example:
-win min	If the agent has a graphical window, minimize upon creation	-mm min
-win max	If the agent has a graphical window, maximize upon creation	-win max
-win hidden	Hide any graphical user interface from the desktop	-win hidden
-noans	Disable the ANS module and run standalone	-noans
-mm	The name of a primary MatchMaker	-mm MatchMaker
-ddp	Name of a visualizer or logging agent	-ddp DemoDisplay
-ddn	<enable/disable> Enable or disable the visualizing module	-ddn enable
-dpp	Portumber of a desktop agent (if used)	-dpp 6658

Step 2, Choosing a Visualization System

If you haven't specified a visualization system with command line parameters, the
agent will prompt you for the name of a visualization or logging agent. You will
not get this dialog box if the agent hasn't compiled support for this type of
logging. Below is a screenshot of the window, which will pop up when an AMS has not specified a visualization agent

When you don't specify anything at this point, but instead just click 'OK', the
visual logging module will be initialized with a default name. This is normally
'DemoDisplay'. After you've selected a different name for the target agent, click
on 'Commit'. This will ensure that information is propagated to the agent code.

Step 3, Registering with an ANS

If no ANS server was specified using either one of the configuration files or command line parameters, the agent will pop-up a dialog box. You can use this window to register with an Agent Name Server.

Choose a server from the list, or enter a new one. Then press 'register' and the agent should inform you whether or not the registration process was successful. Use the 'unregister' button if you accidentally register with the wrong server. This process will not affect the already-running agent. When all goes well, the dialog should look like the dialog box in the second figure, below. The list of agents you will see in the drop-down box is obtained from the RETSINA system directory. We provide more information on this in the following sections.

Example Five, Cont: Deriving an Agent that Uses the

CProblemSolver Class