Configure your agent platform

Provides a brief overview of the agent platform, and then 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, you must 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:

The location (system and port) of each Pool.
The services that will run in the platform.
The agents that are allowed to run in the platform.

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. For a conceptual overview of the distributed platform and more information about the available agent services, see the following concept article: Agent platform.

Define the agent platform

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

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

Note: 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.

The following code samples taken from ableplatform.preferences provide examples of how to modify the platform preferences:

Note: 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.

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 service, 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, you must associate a service principal with each agent pool; for more information about using Kerberos service principals, see the Secure your agent environment topic. The following is an example of how a set of agent pools could be defined:
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
```
#----------------------------------------------------------------------
# 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
#----------------------------------------------------------------------
```
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, you must 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
```
Note: 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 will keep 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 native 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
  If you specify to turn this property on, when you restart the platform all previously persisted data will be cleared from the database.
Define 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, you must 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 the Secure your agent environment topic.
- 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.
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, trustlevels, and how they are used and defined to secure the agent platform, see: Secure 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.