IBM Agent Building Environment Developer's Toolkit


Chapter 6. Building and Starting Your Agent

Building and starting an agent includes the following run time functions:

You can accomplish these functions by using one of the sample agent programs (one for c++; another for Java) that is provided with the IBM Agent Building Environment Developer's Toolkit, or by writing your own agent program. One of the sample agents is sufficient for demonstration, trying out the IBM Agent Building Environment Developer's Toolkit and for a some single client applications. Refer to "Using the Sample Agent Programs" for more guidance in using the sample agents. However, for most applications involving an agent server environment or multiple user agent operations, you will need to write your own agent program.

Writing Your Own Agent Program

More information on writing your own agent program can be found in Chapter 10. "Adding an Agent to Your Application".

The IAAgent class (refer to Chapter 2. "Agent Reference" of the Components and Adapter Reference book) is provided to give you the ability to write your own agent program. You configure the agent by using the addEngine(), addAdapter(), and addLibrary() methods. The configuration requirements can be either imbedded (hard-coded) in your agent program or provided as input to your agent program through menus, files, commands, or other methods that are appropriate for your application.

You can use the loadConductSet() and unloadConductSet() methods to initially load and subsequently change the loaded conduct sets for your application. The loaded conduct sets represent the currently available rules and facts that can control inferencing for your application. Refer to Chapter 2. "Agent Reference" of the Components and Adapter Reference book for more information on loading and unloading conduct sets for your application.

After establishing your agent configuration and initial conduct sets, your agent program can use the IAAgent start() method to start the agent. It can also use stop() to stop the agent program.

Configuring Adapters That Are Written in Java

When an adapter uses the Java interface, (such as the sample Stock Adapter) it requires the use of the Java Interface Adapter (loadable module iagajava) and a Java class to represent the adapter.

The Java Interface Adapter is a special adapter that supports adapters that are written in Java. You do not have to be aware of what it does for your Java adapter because it is all done for you internally. In general it handles some of the adapter initialization and callback functions for your Java adapter and gets them to your adapter in a manner that is consistent with the Java adapter interface. You only need to specify the the Java interface adapter loadable module (iagajava) when configuring an adapter that is written in Java. If you write your own agent program, Java adapters are specified by using the addAdapter() method of IAAgent (refer Chapter 2. "Agent Reference" of the Components and Adapter Reference book for use of the method). The addAdapter() method's second parameter (loadable module name) is always iagajava.

To specify the class name for an adapter that is written in Java via your own agent program, use addAdapter (refer to Chapter 2. "Agent Reference" of the Components and Adapter Reference book for details of the method). The addAdapter() method's third parameter allows you to pass parameters for initializing the adapter. In the case of a Java adapter, this parm must be a string and the first word of that string must be the Java package and class name that contains the IAAdapter methods for that adapter. For example, were you to specify the Java package and class name for the sample Stock Adapter, it would be: ibm.AgentBuilder.samples.stock.StockAdapter. If your adapter requires additional start-up parameters, they would follow this classname parm that is required for adapters written in Java.

The java classes needed by the Java Interface Adapter to support the adapters that are written in Java are in the abesampl.jar file. This file should be in your CLASSPATH statement along with the Java runtime class files. (For any adapter written in Java your CLASSPATH should identify a directory that contains all of the Java classes used to implement that adapter).

Configuring Adapters That Are Provided With the IBM Agent Building Environment Developer's Toolkit

Whether you write your own agent program or use the sample agent program (both described below), you may want to use one or more of the adapters that are provided by the IBM Agent Building Environment Developer's Toolkit. To configure these particular adapters, you will need to know the domain name and dll name (loadable module name) for each of these adapters. Following is a summary of that information:

 Domain Name       DLL Name        Java Package/Class

    File           iagafile
    HTTP           iagahttp
    NNTP           iaganntp
    Time           iagatime
    Util           iagautil
    SampMail       sampmail
    StockAdapter   iagajava   ibm.AgentBuilder.samples.stock.StockAdapter

                   (for the StockAdapter, as for any Java adapter,
                   iagajava is the DLL for the for the Java Interface
                   Adapter.  The Java Interface Adapter is an internal
                   adapter that is used to bridge some IAAdapter methods
                   from Java to C++).

The domain name is a case-sensitive, unique identifier for each adapter and is used in various ways to identify an adapter by the agent and/or engines. The DLL name is used to load the code for the adapter at run time. For adapters written in Java, the DLL name specified is the DLL for the internally supplied Java Interface Adapter, DLL name iagajava.

Using the Sample Agent Programs

There are two sample agent programs, one written in C++ and one in Java. You run the C++ sample agent by invoking iagent. To start the Java sample agent you invoke the following:

java ibm.AgentBuilder.samples.agent.JavaAgent

The java classes needed by the Java sample program are in the agentbld.jar file. This file must be in your CLASSPATH statement along with the Java runtime class files.

The options that you can specify with either of these sample agent programs are described below.

If you use one of these sample agent programs, your agent is built at run time based on configuration selections in a configuration file that you set up before you run the agent program. This configuration file includes statements for defining the parts of the IBM Agent Building Environment Developer's Toolkit that are to be selected for use, as well as the conduct sets that are to be initially loaded for inferencing by the agent. The agent is automatically started by the sample agent program after this initial configuration is completed.

Start Up Options for the Sample Agent Programs

The following command-line options are recognized by the iagent program:
 -fFILENAME     where FILENAME is the name of the configuration file
                to use.  By default, iagent.cfg in
                your current directory is used.  The configuration file
                is used to control which engines and adapters are to
                be configured for the agent program.  The configuration
                file is described below.

 -c             Check the configuration file.  The named engines and
                adapters are loaded, but the agent is not started.

 -v             Verbose.  Causes the agent registry to be printed to
                standard output before starting the agent.

 -d             Run the agent as a background program (a "daemon").
                In this mode, after starting the agent, commands will not
                be read from standard input.  The agent is terminated by
                sending one of the following signals:  SIGINT (ctl-C),
                SIGTERM.  This option is in effect automatically if
                standard input is not a tty.

 -m             Activate throughput monitoring.  This option monitors
                the agent throughput, and regularly prints a message
                to the console indicating the number of completed
                events per second (events/second).  Currently the
                monitoring occurs every 3 seconds.

 -?             Display help information for the agent program

A slash may be used instead of a dash to start an option. Further, options may be grouped together in one argument preceded by a dash or slash. For example, "iagent -vd" says to start the agent with the -v and -d options in effect.

After starting the agent program, iagent will read commands from standard input if the daemon option is not in effect. The following commands are recognized:

  help or ?                - Display help information for available commands

  quit, stop, or end       - Terminate the agent program

  loadcs   csname selector - Dynamically load conduct set.
                             See NOTE below for details on the
                             csname (conduct_set_name) and selector
                             parameters.  If this is replacing a conduct
                             set that was loaded previously (same conduct
                             set and selector), then it may be
                             appropriate to use the reset command (below)
                             before using this command (to also reset the
                             adapter's state for the specified selector.

  unloadcs csname selector - Dynamically unload conduct set.
                             See NOTE below for details on the
                             csname (conduct_set_name) and selector
                             parameters.  If you are finished with a
                             conduct set and not wanting to replace it
                             with another one, it is appropriate to use
                             use this command.  However, if you also
                             want to reset all state for adapters in
                             scope of this conduct set's
                             selector, you would use the
                             reset command (below) instead of this
                             command.

  reset selector -           Dynamically reset the engine and all
                             adapters state in the scope of the specified
                             selector.  This includes unloading
                             conduct set(s) that are associated with the
                             specified selector.  If you want to stop
                             inferencing on conduct set(s) for a
                             selector, but preserve adapter's state for
                             that selector, use the unload command instead.

Note: See "Configuration File for the Sample Agent Programs". "conductset". Sending EOF on standard input will cause iagent to cease reading from standard input, waiting exclusively on a signal to terminate the agent program.

Configuring Adapters That Are Written in Java

When an adapter uses the Java interface, (such as the sample Stock Adapter) it requires the use of the Java Interface Adapter (loadable module iagajava) and a Java class to represent the adapter.

The Java Interface Adapter is a special adapter that supports adapters that are written in Java. You do not have to be aware of what it does for your Java adapter because it is all done for you internally. In general it handles some of the adapter initialization and callback functions for your Java adapter and gets them to your adapter in a manner that is consistent with the Java adapter interface. You only need to specify the the Java interface adapter loadable module (iagajava) when configuring an adapter that is written in Java. For the sample agent, you do this by specifying it in the configuration file, as described in "Configuration File for the Sample Agent Programs". To specify the Java class name via the sample agent for an adapter that is written in Java, see "Configuration File for the Sample Agent Programs".

The java classes needed by the Java Interface Adapter to support the adapters that are written in Java are in the agentbld.jar file. This file should be in your CLASSPATH statement along with the Java runtime class files. (For any adapter written in Java your CLASSPATH should identify a directory that contains all of the Java classes used to implement that adapter).

Configuration File for the Sample Agent Programs

The Configuration File allows you to communicate your selection of an agent configuration. The default configuration file name is iagent.cfg. You can use the Configuration File to define an agent configuration consisting of components from the IBM Agent Building Environment Developer's Toolkit, and, in the case of adapters, you can configure in adapters that you have written yourself. You have the capability for establishing and changing this configuration each time that you start up an agent using the functions from the IBM Agent Building Environment Developer's Toolkit. With this Level 6 of the IBM Agent Building Environment Developer's Toolkit, some of your configuration choices are limited. As further development takes place, these choices will grow to permit choices of many more adapters, additional engines, and additional library repositories.

Configuration File Statements

The following are the valid statements that you can use in the Configuration File. Each statement occupies a line in the file, where a line ends with a newline character (ENTER key). You separate keywords with one or more blanks. Empty lines in the file are ignored. Lines beginning with # or * can contain your comments. Keywords for an entry must begin in the first position of a line. The first keyword is not case sensitive.

Statements should appear in exactly the following order:


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]