home » user manual » agent configuration

Configuring Nuin Agents

As other chapters of this user guide show, Nuin agents are very flexible. They can be configured with different knowledge sources, reasoners, scripts, services, and basic setup parameters like name (URI) and label. In order to make the startup process for the agent engine as flexible as possible, a general configuration API allows agents to be configured at run-time using an OWL (ontology) model. This model may be derived from a serialised OWL document that is read in from some URL, and indeed this is a typical usage. However, the model can be constructed in other ways (including programatically), so there are many potential routes to configuring a Nuin agent system. Since the principal means of configurating Nuin agents is via a serialised OWL document, this chapter will concentrate on the format of the RDF configuration files.

Configuring an agent

The Nuin agent class takes a configurer as a constructor parameter. The configurer may be null, but if not null the configurer sets the options and configurable elements of the agents by processing an RDF/OWL model. The default configurer is able to handle the standard configuration options (see below), but the class can easily be extended to add additional configuration options. The work is actually handled by delegation to various sub-classes of the abstract configurer class, which are specialised to translate the OWL statements in the configuration model into the state changes in the object (agent, service, ks, etc) being configured.

For many applications, users will not need to understand or extend the configuration process. Simply setting the configuration options in the config document will be sufficient for most common purposes. However, the flexibility is there to extend the configuration process if necessary. The most convenient entry point for creating agents, using a configuration document to configure the agent, is with the AgentRunnerFactory. The entry points on this class allow an agent (or several agents) to be built, configured, and started in one step.

Outline structure of the configuration document

Figure 1 shows a complete configuration document (actually a snapshot at the time of writing of the Jade ping example configuration):

<!-- Configuration file for Jade ping demo agents -->
<!-- CVS $Id: config.xml,v 1.6 2004/06/08 09:30:05 ian_dickinson Exp $ -->

<!DOCTYPE rdf:RDF [
    <!ENTITY nuin      'http://www.nuin.org'>
    <!ENTITY ncore     '&nuin;/ontology/'>

    <!ENTITY rdf       'http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
    <!ENTITY xsd       'http://www.w3.org/2001/XMLSchema#'>
    <!ENTITY owl       'http://www.w3.org/2002/07/owl#'>
    
    <!ENTITY nconf     '&ncore;config#'>
    <!ENTITY parsers   '&ncore;parsers#'>
    <!ENTITY smodel    '&ncore;selfModel#'>
    <!ENTITY service   '&ncore;service#'>
    
    <!ENTITY base      '&nuin;/2004/01/jping'>
    <!ENTITY jping     '&base;#'>
]>


<rdf:RDF
    xmlns:rdf          ="&rdf;"
    xmlns:xsd          ="&xsd;"
    xmlns:owl          ="&owl;"
    xmlns:parsers      ="&parsers;"
    xmlns:nconf        ="&nconf;"
    xmlns:service      ="&service;"
    xmlns:jping        ="&jping;"
    xmlns              ="&jping;"

    xml:base           ="&base;"
>
  <!-- global settings -->
  <nconf:Configuration>
    <!-- service registrations -->
    <nconf:registerServiceType>
      <nconf:ServiceRegistration>
        <nconf:serviceType><service:JadeMessageService /></nconf:serviceType>
        <nconf:serviceMakerClass rdf:datatype="&xsd;string">
          org.nuin.integration.jade.JadeMessageAdapterService
        </nconf:serviceMakerClass>
      </nconf:ServiceRegistration>
    </nconf:registerServiceType>
    
    <nconf:registerServiceType>
      <nconf:ServiceRegistration>
        <nconf:serviceType><service:JadeAcquaintanceModel /></nconf:serviceType>
        <nconf:serviceMakerClass rdf:datatype="&xsd;string">
          org.nuin.integration.jade.JadeAcquaintanceModelService
        </nconf:serviceMakerClass>
      </nconf:ServiceRegistration>
    </nconf:registerServiceType>
    
    <nconf:registerServiceType>
      <nconf:ServiceRegistration>
        <nconf:serviceType><service:JadeContainerService /></nconf:serviceType>
        <nconf:serviceMakerClass rdf:datatype="&xsd;string">
          org.nuin.integration.jade.JadeContainerService
        </nconf:serviceMakerClass>
      </nconf:ServiceRegistration>
    </nconf:registerServiceType>
  </nconf:Configuration>
  
  
  <nconf:AgentConfiguration>
      <nconf:name rdf:resource="urn:x-nuin:agent0" />
      <nconf:label rdf:datatype="&xsd;string">Jade ping agent 0</nconf:label>
      <nconf:keepAlive rdf:datatype="&xsd;boolean">true</nconf:keepAlive>

      <!-- scripts -->
      <nconf:hasScript>
        <nconf:AgentScript>
          <nconf:language rdf:resource="&parsers;nuinscript" />
          <nconf:location rdf:resource="file:examples/jade-ping/scripts/agent0.ns" />
        </nconf:AgentScript>
      </nconf:hasScript>

      <!-- services -->
      <nconf:hasService>
        <service:JadeAcquaintanceModel/>
      </nconf:hasService>
      <nconf:hasService>
        <service:JadeMessageService/>
      </nconf:hasService>
  </nconf:AgentConfiguration>


  <nconf:AgentConfiguration>
      <nconf:name rdf:resource="urn:x-nuin:agent1" />
      <nconf:label rdf:datatype="&xsd;string">Jade ping agent 1</nconf:label>
      <nconf:keepAlive rdf:datatype="&xsd;boolean">true</nconf:keepAlive>
      
      <!-- scripts -->
      <nconf:hasScript>
        <nconf:AgentScript>
          <nconf:language rdf:resource="&parsers;nuinscript" />
          <nconf:location rdf:resource="file:examples/jade-ping/scripts/agent1.ns" />
        </nconf:AgentScript>
      </nconf:hasScript>
      
      <!-- services -->
      <nconf:hasService>
        <service:JadeAcquaintanceModel/>
      </nconf:hasService>
      <nconf:hasService>
        <service:JadeMessageService/>
      </nconf:hasService>
  </nconf:AgentConfiguration>

</rdf:RDF>

Figure 1: sample configuration document

After the premable defining XML namespaces for the various resources, and corresponding XML entities for convenience, there are three main sections in this example configuration. First, a collection of global configuration options, that don't pertain to any particular single agent, then two single agent declarations. In this particular example, the declarations are very similar, but this need not be the case. Note that, in RDF terms, each agent declaration in this example is an anonymous node of type nconf:AgentConfiguration. The configuration resource need not be an anonymous node, but note that the URI of the configuration is not the identity of the agent itself. The agent's identity is specified by the nconf:name property, or, if omitted, is a auto-generated UUID.

Note that a common pattern in Nuin configuration models is the use of a typed anonymous node to denote a structured value. For example, a new service is introduced as an anonymous resource of rdf:type nconf:ServiceTypeRegistration. The properties of this resource declare the particulars of the service being registered, including name, service type and the Java class that implements the service.

The following sections summarise the current configuration options recognised by the standard configuration worker classes.

Global configuration options

The global configuration options are declared against a resource of rdf:type nconf:Configuration. A given Configurer object should only have one resource of this type in its attached model. The Configuration node may have any of the following properties:

Property name	Domain type	Range type	Description
nconf: registerServiceType	nconf:Configuration	nconf: ServiceTypeRegistration	Introduces a new agent service that can be accessed both from the agent configuration itself and the agent's script.
nconf:serviceType	nconf: ServiceTypeRegistration	instance of a service class	Denotes the service type by introducing an individual (usually anonymous) whose `rdf:type` is the OWL class denoting the service type. This allows the use of the OWL class hierarchy to define hierarchical service types, without needing to directly reference the OWL service type class as a property value.
nconf: serviceMakerClass	nconf: ServiceTypeRegistration	string denoting a fully-qualified Java class name	Denotes the name of the Java class that provides the implementation of the service to the agent at run time.

Agent configuration options

Nuin agent configuration options are declared against a resource of rdf:type nconf:AgentConfiguration. An AgentConfiguration node may have any of the following properties:

Property name	Domain type	Range type	Description
nconf:label	nconf: AgentConfiguration	an xsd:string	A human-readable label for the agent, which may in some circumstances be used to display (a reference to) the agent. Optional.
rdfs:label	nconf: AgentConfiguration	an xsd:string	Alternative to `nconf:label`, with the same meaning
nconf:comment	nconf: AgentConfiguration	an xsd:string	A textual description of the agent. Optional.
nconf:name	nconf: AgentConfiguration	URI denoting the identity of the agent	Denotes the unique identity of the agent. The URI does not have to be declared at configuration time; if not specified here it will default to a system generated UUID. Note that configuring two agents with the same agent ID will cause a configuration exception at run-time.
nconf:keepAlive	nconf: AgentConfiguration	an xsd:boolean	Flag that specifies the agent's behaviour once it has run out of active intentions. If `keep alive` is true, the agent will wait in a quiescent state until new events arise or the application terminates. Otherwise, the agent will terminate itself once all active intentions have completed and its event queue is empty.
nconf: hasService	nconf: AgentConfiguration	nconf:AgentService	Introduces a service that this agent has access to. The range value is an instance of the service-type OWL class that represents the service. For example, to configure an agent with the capability of using a local message service, the range value of the `hasService` property is an instance of `service:LocalMessageService`.
nconf:hasScript	nconf: AgentConfiguration	nconf:AgentScript	Introduces a script that defines the agent's behaviour. An instance, typically anonymous, of the `AgentScript` OWL class is the subject node for the various script declaration parameters (see below). There may be more than one `hasScript` property per agent.
ksconf:hasKS	nconf: AgentConfiguration	ksconf: AgentKnowledgeStore	Introduces a knowledge store for the agent. An instance, typically anonymous, of the `AgentKnowledgeStore` OWL class is the subject node for the various KS declaration parameters (see below).

Agent script configuration options

Agent script configuration options are declared against a resource of rdf:type nconf:AgentScript. An AgentScript node may have any of the following properties:

Property name	Domain type	Range type	Description
nconf:location	nconf: AgentScript	a resource denoting the URL of the script to be loaded	Denotes the resolvable URL of a script file that the agent will load to define the agent's run-time behaviour. Note that the location must be a URL, so files on the local file system are denoted with a `file:` protocol. Required for each `AgentScript` declaration.
nconf:language	nconf: AgentScript	a resource denoting the script language of the referenced script	Denotes the language the script is written in, and hence the parser that will be used to load the script, as a resource. The default value for this property, if omitted, is `http://www.nuin.org/ontology/parsers/nuinscript`.

Agent KS configuration options

Knowledge source configuration options are declared against a resource of rdf:type ksconf:AgentKS. An AgentKS node may have any of the following properties:

Property name	Domain type	Range type	Description
ksconf:ksOntology	ksconf:AgentKS	a resource denoting the URI of an ontology that underlies this KS	Denotes the URI of an ontology that applies to the sentences in the KS.
ksconf:hasKsType	ksconf:AgentKS	an instance of an OWL class denoting the type of the knowledge source.	A resource (symbol) denoting the type of the knowledge source. Some of the pre-defined types are: `ksconfig:KSType_KnowledgeStore` `ksconfig:KSType_RDFKnowledgeStore` `ksconfig:KSType_Dispatcher` `ksconfig:KSType_FCS` `ksconfig:KSType_RTP` `ksconfig:KSType_GoalBase`
ksconf:isUpdateable	ksconf:AgentKS	xsd:boolean	Flag that denotes whether the KS can be updated.
ksconf:ksAxioms	ksconf: AgentKnowledgeStore (rdfs:subClassOf ksConf:AgentKS)	ksconf:AxiomSource	Introduces a structured value defining some source of axioms for the KS.
ksconf: axiomEncoding	ksconf:AxiomSource	a resource URL	Denotes the URL representing the encoding language of the axioms, and hence which parser will be used to read them in to the KS.
ksconf:axiomSyntaxOption	ksconf:AxiomSource	a string	Denotes an extra option that may be passed to the parser to select additional parsing options. For example, the Jena RDF parser can parse input in RDF/XML, N3 or N-TRIPLE formats.
ksconf:axiomsLocation	ksconf:AxiomSource	a resource URL	Denotes the URL of a document containing initial axiom data for the store, serialised in some syntax.
ksconf:overKS	ksconf: AgentReasoner (rdfs:subClassOf ksconf:AgentKS)	a URI denoting the name of a KS	In Nuin, reasoners can be composed in layers. So, for example, a backward-chaining reasoner can wrap around a basic knowledge store, to gain additional inferencing capability. An `AgentReasoner` resource allows such a reasoner to be defined, with the `overKS` property stating the name (i.e. `conf:capabilityName`) of the knowledge source to which the reasoner is applied.

Creating configuration files

At the present time, the recommended tool for creating configuration files is a text editor. The N3 syntax can be used to make the configuration file more compact (Jena's rdfcopy tool is a convenient way to translate N3 documents to RDF/XML syntax). In a future version of Nuin, we hope to implement an agent configuration editor.

« prev: events & messages | agent configuration | next: agent services »