David Lillis :: ACRE Module

The ACRE Module supplies a number of actions that are available to agents for the management of conversations and protocols. These are outlined below. Each conversation is identified by a unique identifier (generated either by the module or by the other participating agent), which is referred to as ?cid in the following actions. Protocols also have a unique identifier (created by the protocol's author), which is referred to as ?pid .

For details on how to get started using the ACRE Module, please refer to the ACRE User Guide.

Setup

Before you can use any of the actions below, it is necessary to load the module into your agent. The class to load is is.lill.acre.agent.module.ACREModule .

addRepository(?url): This action is used to specify a protocol repository to be used. The ?url parameter specifies the location of the base of the repository. At present, this supports URLs beginning with http:// or file:// .
init: Initialise the ACRE module. This must be called by any ACRE-enabled agent and will result in the ACRE module binding itself to the Protocol Management Service, in order to fetch details of any repositories previously added using the addRepository action. On completion of the initialisation process, the belief ready(acre) is adopted for one iteration, and this can then be used to trigger the start of any communication with other agents.

Managing Contacts

The ACRE Module includes an internal address book. Any agent added as a contact to the address book may be referred to only by its name when saving messages. Thus, programmers need not be concerned with managing the addresses of agents once they have been added as contacts.

addContact(?aid): Add a contact to the address book. The ?aid parameter should be an agent identifier in the form: agentID(name,addresses(address1[,address2...])) . Once added to the address book, an agent may be referred to solely by its name, with the ACRE module finding the appropriate address from the address book (according to FIPA standards, agent names should be unique).
Alternatively, the ?aid can just be the name of the agent. ACRE will default to a local address on the same agent platform.
removeContact(?aid): Remove an agent from the contact list. Here, the ?aid parameter can either be the same format as for the addContact action (though it is only the name of the agent that is used to identify it) or just the agent's name..

Sending Messages

start(?pid,?receiver): Begin a new conversation, without sending any messages. The conversation begins in its start state, and the start action must be subsequently called in order to send messages as part of this conversation. The ?pid parameter identifies the protocol that the conversation is to follow, whereas ?receiver identifies the agent that is to be the other participant in the conversation.
start(?pid,?receiver,?performative,?content): Begin a new conversation and send the first message. The ?pid and ?receiver operate in the same way as the 2-parameter start action. The ?performative and ?content parameters refer to the details of the initial message that is to be sent. These are used in the same way as in the advance action, below.
start(?pid,?receiver,?performative): Identical to the 4-parameter version of start except that the message is sent with an empty content field.
advance(?cid,?performative,?content): Send a message as part of an existing conversation (identified by ?cid ). If ?cid is a list, then all the conversations whose identifiers are included in the list will be advanced using the same message details. The performative and content associated with the message are set in the ?performative and ?content parameters, respectively. If these do not match an active transition, an unmatchedMessage(?performative,?sender,?content) event will be raised by the ACRE Module.
advance(?cid,?performative): Identical to the 3-parameter version of advance except that the message is sent with an empty content field.

Managing Conversations

forget(?cid): Remove the conversation identified by ?cid from the agent's memory. Although possible for any conversation, it is recommended that this be used only for conversations that have been finished or failed. All details of the conversation will be permanently forgotten.
archive(?cid): Archive a conversation. When archived, beliefs will not be generated by the knowledge sensor for the conversation (other than a conversationArchived belief). This presents finished conversations polluting the belief base. Suitable for situations where it is not currently necessary to reason about the conversation but it is not desirable to forget its details entirely.
recall(?cid): Reverses the archiving of a conversation, restoring it to the belief base of the agent.
setTimeout(?cid,?timeout): Set a timeout for the conversation identified by ?cid . This is expressed in milliseconds in the ?timeout parameter. Outgoing messages will have an appropriate reply-by parameter set, and whenever a conversation is not advanced within the specified time, a conversationTimeout(?cid) event is raised to make the agent aware of this.
annotate(?cid,?annotation): Add an annotation to a conversation (e.g. to add some piece of additional information about the subject of the conversation). Annotations added in this way will persist until the conversation is removed from memory using the forget(?cid) action or until the annotation is removed using one of the deannotate actions.
deannotate(?cid): Remove all annotations from a conversation.
deannotate(?cid,?annotation): Remove a specified annotation from a conversation.

Cancelling

cancel(?cid): Initiate a cancel meta-protocol to cancel the conversation identified by ?cid
confirmCancel(?cid): Continue a cancel meta-protocol by agreeing to cancel the conversation identified by ?cid . This should only be called when a conversationCancelRequest(?cid) event has been raised to indicate that the other participant in the conversation has requested that it be cancelled. Otherwise, this action will have no effect.
denyCancel(?cid): After receiving a request to cancel a conversation (indicated by the conversationCancelRequest event), this action will prevent the parent conversation (identified by ?cid from being cancelled.

Event Percepts

Event Percepts are created by the event sensor: a component of the ACRE module that causes an agent to gain beliefs about one-off occurrences. Please note that if you are using the AF-AgentSpeak AOP language, only events that are handled by your program are visible in the debugger.

ready(acre): This indicates that the ACRE module has been successfully loaded and has bound itself to the Protocol Manager Service.
notBoundToACREService: This event indicates that the ACRE module may not yet be used as it has not bound to the platform service that it requires to gain access to protocol definitions.
conversationAdvanced(?cid,?state,?length): The conversation identified by ?cid advanced as a result of a message being sent or received. The current state of the conversation is now ?state (which will be the name of a state included in the protocol definition). The ?length parameter indicates the number of message that have been exchanged as part of this conversation.
conversationStarted(?cid): A new conversation identified by ?cid has been created.
conversationEnded(?cid): The conversation identified by ?cid has reached a final state and is now finished.
conversationFailed(?cid): The conversation identified by ?cid has failed. This occurs when a message is sent or received states that is is part of the specified conversation but is not capable of triggering a transition from its current state.
conversationCancelRequest(?cid): A request has been received from the other participant in the conversation identified by ?cid to cancel the conversation.
conversationCancelConfirmed(?cid): The other participant in the conversation has agreed to cancel the conversation identified by ?cid .
conversationCancelFailed(?cid): The other participant in the conversation has declined to cancel the conversation identified by ?cid after it has been requested.
conversationTimeout(?cid): The conversation identified by ?cid has timed out. This occurs when a timeout time has previously been set using the acre.timeout(?cid,?time) action and a response has not been received within the specified timeframe.
conversationMessage(?cid,?perf,?content): Details of a message that advanced a conversation (only arises alongside a conversationAdvanced event). The ?perf parameter is the performative of the message and ?content is the message content.
unmatchedMessage(?performative,?sender,?content): A problem occurred when attempting to associate a message with a conversation. This event is triggered whenever a message cannot be matched to an active conversation and is incapable of starting a conversation that follows a known protocol.
ambiguousMessage(?performative,?sender,?content): A problem occurred when attempting to associate a message with a conversation. This event is triggered whenever a message is capable of advancing multiple active conversations or starting new conversations following known protocols.

Knowledge Percepts

Knowledge percepts are created by the Knowledge Sensor. These are ongoing beliefs about the progress of conversations, and are available to the agent at all times during the lifetime of a conversation to aid reasoning about conversations.

conversationArchived(?cid,?pid,?aid): The conversation identified by ?cid has been archived. The ?pid holds the identifier of the protocol that the conversation followed, whereas the ?aid is the identifier of the other agent that was involved in the conversation.
conversationStatus(?cid,?status): This indicates the status of the conversation identified by ?cid . The ?status of a conversation may be one of the following list: ACTIVE, FAILED, FINISHED, STALE, READY, CANCELLING, CANCELLED.
conversationParticipant(?cid,?aid): This indicates that the other agent participating in the conversation identified by ?cid has the unique identifier ?aid .
conversationProtocolID(?cid,?pid): This indicates that the unique identifier of a the protocol a conversation is following. The conversation is identified by ?cid and the protocol has the identifier ?pid .
conversationProtocolName(?cid,?pname): The unique identifier of protocols consists of three distinct parts: the name, the namespace and the version of the protocol. It is sometimes preferable to deal with only portions of this identifier at a time. Thus, this belief indicates only the `name' portion of the protocol identifier (?pname ).
conversationProtocolNamespace(?cid,?pnamespace): This indicates only the `namespace' portion of the protocol's unique identifier (?pnamespace ).
conversationProtocolVersion(?cid,?pversion): This indicates the version of the protocol the conversation is following (?pversion ).
conversationState(?cid,?state): An active conversation is always in some named state (state names are specified in the protocol definition). This indicates that the conversation identified by ?cid is currently in the state named in the ?state parameter.
conversationLength(?cid,?length): This contains the number of messages that have been exchanged as part of the conversation thus far. The ?cid parameter again specifies the unique conversation identifier, with ?length being the number of messages.
knownProtocol(?pid): Indicates that a protocol with the unique identifier ?pid is known to the Protocol Manager and can be used by the agent.
annotation(?cid,?annotation): A belief to record an annotation that was added to a conversation earlier (using the annotate(?cid,?annotation) action).
conversationHistory(?cid,?index,?type,?perf,?content): Details about a message that was sent as part of the conversation identified by ?cid. The ?index parameter indicates where the message came in the conversation (1 for the first message, 2 for the second, etc.). The ?type parameter will be sent if this agent sent the message, or received if the message was sent by the other participant in the conversation. The ?perf and ?content parameters relate to the details of the message itself.