Configuring your agent platform

 

This topic provides a brief overview of the agent platform and also provides detailed configuration steps for modifying the platform preferences file. Before you begin using the Intelligent Agents console in iSeries™ Navigator, you first need to configure the agent platform.

Agent platform overview

To manage agents using the intelligent agents console, first define, secure, and start an agent platform that the console will connect to. An agent platform is nothing more than a set of Java™ Virtual Machines, or agent pools, that run the services and agents of the platform. The ableplatform.preferences and able.preferences files are used to define a platform.

In its simplest form, with security turned off, ableplatform.preferences defines:

Once the agent platform is set up, the services that run on or across the platform allow an agent to receive a unique name, look up other agents in a directory, log history or requests, pass messages to one another, or control the state of an agent.

Defining the agent platform

To begin configuring your platform, define your agent pools, agent services, permitted agents, and add Kerberos security principals by modifying the ableplatform.preferences file.

The default location of ableplatform.preferences is QIBM/ProdData/OS400/Able.

Notes:

  1. Multiple platforms can be configured, and you need to ensure that your platform does not reside at the same location as an existing platform using the same port. See the Start the agent platform topic for more details.

  2. When you open the file and begin making changes to the content, understand that small errors and misspellings will cause the agent platform to fail, and there is currently no easy way to debug your mistakes. Avoid commenting out properties that are unused, commenting out an unused property can cause the platform to fail. For example, if you choose to run the platform with security turned off, do not comment out the principal properties through the file.

The following code samples taken from ableplatform.preferences provide examples of how to modify the platform preferences. To configure your platform, follow these steps:

  1. Define agent pools.

    A platform is nothing more than a set of distributed Java Virtual Machines. Each JVM is called an agent pool, and each JVM or pool can host multiple services and agents (an agent pool does not have to host services, it could be used to run just agents). You must define the location of each of your Java Virtual Machines (agent pools) in the preferences file by specifying the IP address (fully qualified system name) and port. Also, specify an alias (any unique name) for each agent pool. When security is turned on, associate a service principal with each agent pool. For more information about using Kerberos service principals, see Securing your agent environment. The following is an example of how a set of agent pools could be defined: 

    #----------------------------------------------------------------------
# Java Virtual Machines #----------------------------------------------------------------------
AgentPool.1.Alias     = Pool1 AgentPool.1.IpAddress = systemname.ibm.com AgentPool.1.Port      = 55551 AgentPool.1.Principal = servicePrincipal1 
AgentPool.2.Alias     = Pool2 AgentPool.2.IpAddress = systemname.ibm.com AgentPool.2.Port      = 55552 AgentPool.2.Principal = servicePrincipal1 
AgentPool.3.Alias     = Pool3 AgentPool.3.IpAddress = systemname.ibm.com AgentPool.3.Port      = 55553 AgentPool.3.Principal = servicePrincipal2 #----------------------------------------------------------------------

  2. Define agent services.

    Define the agent services that you want to run on the platform, and specify the alias of the agent pool you want them to run in. Each agent service must point to a factory. The factory is a Java Class that creates the agent service. The Persistence service is used to restart a platform to its previous state. Specify to turn persistence on or off. If you turn persistence on, specify a Database, Table, and Schema so that persistence has a location to store backed up data on. You can also specify a value for the PersistenceRetry property. If the persistence service fails and you specified a value of 5000 for the PersistenceRetry property, it will attempt to retry every 5000 milliseconds. The following code example shows how three different services, Directory, Logging, and Persistence, could be defined: 

    Services=Agent-Directory-Service,Agent-Logging-Service,
Persistence-Service 
Agent-Directory-Service.AgentPool         = Pool1 Agent-Directory-Service.Factory =
com.ibm.able.platform.RMIVerifiableDirectoryServiceFactory     
Agent-Directory-Service.Persistence       = off Agent-Directory-Service.PersistenceDatabase = *LOCAL Agent-Directory-Service.PersistenceTable  = qahadir Agent-Directory-Service.PersistenceSchema = QUSRSYS Agent-Directory-Service.PersistenceRetry  = 5000 
Agent-Logging-Service.AgentPool           = Pool1 Agent-Logging-Service.Factory =
com.ibm.able.platform.RmiAgentLoggingServiceFactory Agent-Logging-Service.Persistence         = off Agent-Logging-Service.PersistenceDatabase = *LOCAL Agent-Logging-Service.PersistenceTable    = qahalog Agent-Logging-Service.PersistenceSchema   = QUSRSYS Agent-Logging-Service.PersistenceRetry    = 5000 Agent-Logging-Service.Properties          = history-log-max : 100

    You can specify to control performance by adding a history-log-max property to the Logging service. If you specify history-log-max=100, each agent keeps only its 100 most current history logs. 

    Persistence-Service.AgentPool    = Pool1 Persistence-Service.Factory =
com.ibm.able.platform.RmiPlatformPersistenceServiceFactory Persistence-Service.Properties   = 
persistence-driver : com.ibm.db2.jdbc.app.DB2Driver,
persistence-protocol : jdbc,
persistence-subProtocol : db2,
blob-type : BLOB,
persistence-dbFlushTime : 1000, 
persistence-dbResetAll : off

    The Persistence service provides backup and recovery for your agent platform. To use persistence with agent services running on or across your platform, you need to define several Persistence-Service.Properties:

    • persistence-driver

      Defines the JDBC driver that the persistence service will use. By default the persistence-driver is set to use the integrated DB2® driver.

    • persistence-protocol and subProtocol

      Defines the database protocol that the persistence service will use. By default the protocol is set to jdbc and the subProtocol is set to db2.

    • blob-type

      Defines the BLOB type associated with the JDBC driver you are using. The default for DB2 is set to BLOB, but if you choose to use a different database, like CloudScape for example, you would define BLOB type as blob-type : LONG VARBINARY.

    • persistence-dbFlushTime

      Specifies the rate at which you want the persistence service to flush data to the database in milliseconds.

    • persistence-dbResetAll

      Specifies if all previously persisted data will be cleared from the database when you restart the platform.

  3. Defining permitted agents.

    You must define all of the agents that you want to allow access to the platform and the agent services running on or across the platform. The following is an example of how an agent could be defined. More details about each agent property are listed after the following example: 

    Agent.1.Alias=Agent1 Agent.1.AutonomyLevel=Medium Agent.1.ClassName=
com.ibm.able.platform.examples.EServerTemplateAgent Agent.1.ConstructorArgs=String:agentName Agent.1.EligiblePrincipals=principalAlias1, principalAlias2 Agent.1.EligibleAgentPools=pool1, pool2, pool3 
Agent.1.InitArgs= 
Agent.1.LastChangedDate=January 11, 2003 11:11am Agent.1.Type=Tester1 Agent.1.Vendor=IBM1 Agent.1.Version=1.1

    • Alias

      Provide a unique name for your agent. This name will be used by the agent console.

    • AutonomyLevel

      Specify the agents initial autonomy level. A user can change this setting from the console. Determine the level of independence you want to associate with your agent, and set the automation level accordingly. The higher you set the automation level, the less your agent will request permission to take an action. If you set an agent to High automation, it will perform most actions without requesting a response first. If you are concerned about an agent's behavior, you may want to lower the automation level (increasing the frequency by which the agent requests permission to take action), by changing the setting to Medium automation.

    • ClassName

      Specifies the the actual agent Java Class.

    • ConstructorArgs

      Allows you to provide arguments in the properties file that you want to pass to your agent.

    • EligiblePrincipals

      When security is turned on, define who has authority to start an instance of your agent by associating one or more user principal aliases with each agent. For more information about using Kerberos service principals, see Securing your agent environment.

    • EligibleAgentPools

      Specify the alias of one or more agent pools that you want to use to run your agents on the platform.

    • InitArgs

      Allows you to pass in any Init arguments to your agent from the preferences file.

  4. Secure your agent platform.

    After you have defined your agent pools, agent services, and permitted agents, you may want to configure security on the platform. For more information on Kerberos principals, trust levels, and how they are used and defined to secure the agent platform, seeSecuring your agent environment.

After you have defined your agent pools, agent services, and permitted agents, and optionally set up security, you need to start the agent platform.

 

Parent topic:

Set up your agent environment

Related concepts
Agent platform

Related tasks
Starting the agent platform