Agent Transfer Protocol ATP/0

Agent Transfer Protocol -- ATP/0.1

Danny B. Lange and Yariv Aridor

IBM Tokyo Research Laboratory

Draft number : 4

Last updated: March 19, 1997.

0. Status of this Draft

This draft is a working document of the Aglets team at IBM Tokyo Research Laboratory. The latest version is available from: http://www.trl.ibm.co.jp/aglets/.

Distribution of this document is unlimited.

This draft has been made available for public review. Any questions, comments, and suggestions regarding the content of this draft should be directed to aglets@yamato.ibm.co.jp.

1. Abstract

Mobile agent are programs capable of being transferred to remote hosts in order to carry out different tasks on behalf of their users. The Agent Transfer Protocol (ATP) is an application-level protocol for distributed agent-based systems. It can be used for transferring mobile agents between networked computers.

While mobile agents may be programmed in different languages and for a variety of vendor specific agent platforms (consisting of virtual machines and libraries), ATP offers the opportunity to handle mobility of agents in a general and uniform way.

ATP/0.1 is implemented in the atp-package as a part of the IBM Aglets Workbench that can be downloaded from: http://www.trl.ibm.co.jp/aglets/.

2. Introduction

2.1 Purpose of ATP

An agent is a program that carry out a set of operations on behalf of a user. It does so with some degree of autonomy to satisfy its user's goals. Mobile (transportable) agents have the ability to travel through the network. A Mobile agent can halt its execution, move to another host on the network while maintaining their state, and resume execution on the destination host.

Aimed at the Internet, ATP offers a simple and platform independent protocol for transferring agents between networked computers. While mobile agents may be programmed in many different languages and for a variety of vendor specific agent platforms (consisting of virtual machines and libraries), ATP offers the opportunity to handle agent mobility in a general and uniform way:

A machine hosting agents has an ATP-based agent service which is a component capable of receiving and sending agents from remote hosts via the ATP protocol. The agent service is identified by a unique address, independent of the specific agent platforms supported by the machine. A machine can run multiple agent services.
A machine can host different types of agents, provided it supports the corresponding agent platforms.
Any agent platform should include a handler of ATP messages.
An ATP message carries sufficient information to identify the specific agent platform (at the receiver host) and calling its ATP handler to handle the message.

Figure 1. An agent host with an ATP-based agent service provides a uniform address space for multiple vendor specific agent platforms.

Figure 1 shows an example of an agent host machine supporting two agent platforms (of vendor A and vendor B) and an ATP-based agent service identified by a unique address atp://john.doe.com.

2.2 Scope of ATP

This document describes a protocol (ATP) that will allow agent services on the Internet to support agent mobility, even if these agents are based on platforms from different vendors and supported by different programming languages. Areas covered by ATP/0.1 are:

Naming of agent services (See ATP URLs in section 4.2)
Agent identifiers (See section 4.3)
Agent transportation (See ATP messages in section 5 )

2.3 Terminology

This specification uses the following terms to refer to the entities related to ATP communication:

Agent. A program that carry out a set of operations on behalf of a user. It does so with some degree of autonomy to satisfy its user's goals.
Connection. A transport layer virtual circuit established between two programs for the purpose of communication.
Message. The basic unit of ATP communication of a byte stream matching the syntax defined in section 5 and transmitted via a connection.
Request. An ATP request message, as defined in section 6.
Response. An ATP response message, as defined in section 7.
Message Body. The information transferred as the payload of a request or response. Interpretation of the body content is implementation specific.
Sender. The role of an application/system that establishes connections for the purpose of sending requests.
Recipient. The role of an application/system that accepts connections in order to service requests and to send back responses.
Agent Service. A system capable of acting both as sender and recipient of agents.
Proxy. An intermediary agent service which acts as both a recipient and a sender for the purpose of making requests on behalf of other senders.

2.4 Overall Operation

The ATP protocol is based on a request/response paradigm between agent services. Agent service A establishes a connection with agent service B, then sends a request to B and waits for the response. Thus, A acts as a sender (of the request) and B acts as a recipient.

A request includes a request line, specifying the request method, the protocol version and the required resource, followed by MIME-like message containing request modifiers, sender information and possible content in its body. A response include a status line, specifying a success or error code and the protocol version, followed by a MIME-like message containing response modifiers, sender information and possible content in its body.

ATP defines four standard request methods for agent services:

Dispatch
Retract
Fetch.
Message

2.4.1 Dispatch an Agent

To dispatch an agent from an agent service A to an agent service B, A sends a dispatch request to B. The agent is contained in the body of the request. When B receives the agent, it will reply to A with a response containing a status code.

2.4.2 Retract an Agent

To retract an agent from an agent service B to agent service A, the later sends a retract request to B. The reply from B is a response with a status code and the specified agent in its body.

2.4.3 Fetch the Class

To execute the agent, an agent service B may need to retrieve executable code from the agent's origin, say, an agent service A. To do so, B sends a fetch request to A. The reply from A is a response with a status code and the required executable code in its body.

2.4.4 Send a Message

To send a message from an agent in agent service A to an agent in agent system B, A sends a message request to B, containing that message. The reply from B is a response with a status code.

3. Notational Convention

This specification uses Extended Backus-Naur Form (EBNF) to describe the syntax of the mechanisms in ATP. The use of EBNF in this document includes the following constructs:

Rule: name=definition

Rules are consisting of a name part and a definition part separated by the equal character. Several basic rules are predefined: Digit=<any US-ASCII digit "0".."9">

Octet=<any 8-bit sequence of data>

Literal: LITERAL

Quotation marks surround literal text. Unless stated otherwise, the text is case-insensitive. Certain characters and strings are predefined: SP represents the space character, CRLF represents a character sequence of carriage return (<US-ASCII CR, (13)) followed by line feed (<US-ASCII LF, (10)).

Alternatives: rule1 | rule2

Elements separated by a bar are alternatives.

Optional: [ rule ]

Elements enclosed in square brackets are optional.

Repetition: rule^*

Elements succeeded by a superscript multiplication sign are repeated zero or more times. Superscript addition sign, '⁺', is used to denote a repetition of one or more times.

Informal: <Explanation>

Informal explanations are enclosed in '<' and '>' brackets.

4. Protocol Parameters

ATP messages relies on a number protocol parameters. The syntax and semantics of those parameters are described in this section.

4.1 ATP Version

ATP uses a "major.minor" numbering scheme to indicate versions of the protocol. The protocol version policy is intended to allow the sender to indicate the format of a message and its capacity for understanding further ATP communication, rather than the features obtained via that communication. The minor number is incremented when the changes made to the protocol add features which do not change the general message parsing algorithm, but which may add to the message semantics and imply additional capabilities of the sender. The major number is incremented when the format of a message within the protocol is changed.

The version of an ATP message is indicated by an ATP_version field in the first line of the message.

ATP_version = "ATP/" Major . Minor

Major = Digit⁺

Minor = Digit⁺

Note that the major and minor numbers should be treated as separate integers and that each may be incremented higher than a single digit. Thus, "ATP/1.2" is a lower version than "ATP/1.23", which in turn is lower than "ATP/12.3".

Applications sending Requests or Responses, as defined by this specification, must include an ATP_version of "ATP/0.1". Use of this version number indicates that the sending application is compliant with this specification.

4.2 Uniform Resource Identifiers

The Uniform Resource Identifier (URI) represents the combination of Uniform Resource Locators (URL) and Names (URN). As far as ATP is concerned, a URI is a formatted string which identify an agent resource. For information on URI syntax and semantics, see RFC 1738 [3] and RFC 1808 [4].

4.2.1 ATP URL

The "atp:" scheme is used to locate agent resources in network via the ATP protocol.

ATP_URL = Service_host [ Agent_resource | Class_resource ]

Service_host = "atp://" Host [ : Port ]

Host = <An Internet host domain name or IP address>

Port = Digit+

Agent_resource = [Name] "#" Agent_identifier

Name= "/" <a string>

Class_resource = Class_path

Class_path = <A legal absolute path specification>

If the port number is not given, port 434 (port reserved for mobile agents) is assumed, accordingly to RFC1700 [2]. On certain systems this port number is only available for application with system or root privileges. On those systems, the suggested port number is 10434.

Examples of ATP URLs that identifies agent services are atp://joe.trl.ibm.com or atp://joe.trl.ibm.com:10434.

An example of an ATP URL that identifies a specific agent is atp://joe.trl.ibm.com#2874678383. See section 4.3 for the syntax of an agent identifier. The agent resource includes a name field which can be used, for example, to distinguish a specific working set of agents running in a given agent service. For example, an ATP URL that identifies a specific agent (id=2874678383) within danny's agent working set of agents of an agent service is: atp://joe.trl.ibm.com/danny#2874678383. .

The last example is an ATP URL that identifies a file (agents/classes/Hello.class) from an agent service is: atp://joe.trl.ibm.com/agents/classes/Hello.class.

4.2.1.1. An Absolute URI versus a Relative URI

A URI in ATP can be represented by an absolute form or relative to some known base URI, depending upon the context of its use. The two forms are differentiated by the fact that an absolute URI always begin with the ATP scheme name followed by a colon ("atp:"). In addition, a relative URI may not include the agent service identifier.

4.3 Agent Identifier

An agent is identified by a string of alphanumeric characters.

Agent_identifier = <an alphanumeric string>

4.4 ATP Date

In ATP, the date format should follow the IETF [1] standard date syntax.

ATP_date = < IETF standard date syntax>

"Sat, 12 Aug 1995 13:30:00 GMT" is an example of the IETF standard date syntax. ATP senders should only send date values in this format. However, ATP recipients of date values are encouraged to be robust in accepting commonly used date values.

5. ATP Message

ATP messages consist of requests and responses. Every request and response can be attributed by header fields and a body.

ATP_message = Request | Response

The format and encoding system of the body of an ATP message is defined by the header fields Content_type (see section 8.6) and Content_encoding (see section 8.7), respectively. The length of the body is specified by the Content-Length header field.

Message_body = Octet^*

6. Request

A request message from a sender to a recipient includes the method to be applied to the resource, the identity of the resource, and the protocol version in use.

Request = Request_Line CRLF Header_field^* CRLF [ Message_body ]

Request_Line = Method SP resource_URI SP ATP_version CRLF

6.1 Method

The method token indicates the method to be performed on a resource at the by the recipient . The set of methods is extensible. If a recipient does not understand an extension method, it will respond to the sender with status code 401 NOT IMPLEMENTED.

Method = DISPATCH | RETRACT | FETCH | MESSAGE | Extension_method

Extension_Method = Token

(see [] for definition of Token)

6.1.1 DISPATCH

The dispatch method is used to transport an agent from one host (the sender) to another host (the recipient) in the network.

6.1.2 RETRACT

The retract method is used to retrieve an agent from a remote host.

6.1.3 FETCH

The fetch method is used for a host to retrieve the executable code required to execute a given agent.

6.1.4 MESSAGE

The message method is used to forward a message to an agent.

6.2 Resource URI

This URI identifies the resource upon which to apply the request. The form of the URI is dependent on the nature of the request and whether a proxy server is involved. see section for the missing definitions.

Resource_URI = <Relative resource URI> | <Absolute resource URI>

6.2.1 Relative URI

The interpretation of a relative resource URI depends on the related request method:

6.2.1.1. DISPATCH

The URI identifies a possible resource like a user or a distinguished group of agents to whom the agent is dispatched. This resource should be identified by a valid name. The validity of the name depends on its specific interpretation. The syntax this URI is: ["/" Name]. Examples are : /joe or /marchant_agents

6.2.1.2. RETRACT

The URI identifies the agent to be retracted. The syntax for this URI is: [ Name] Agent_identifier, where Name can specify a possible resource (a user, agent group) to whom the agent belongs. Examples are: /joe#2874678383 and #2874678383.

6.2.1.3. FETCH

The URI provides the local file path to the requested executable code. The syntax for this URI is simply <File path>. An example is /agents/classes/Hello.class.

6.2.1.4. MESSAGE

The URI identifies the agent who is the receiver of the carried message. The syntax for this URI is: [ Name] # Agent_identifier. Examples are: /joe#2874678383 and #2874678383.

6.2.2 Absolute URI

An absolute URI is only used when the recipient of the request is a proxy. In that case the proxy will use the absolute URI is to forward the request message and return the response to the sender.

7. Response

After receiving and processing a request message, a recipient replies in the form of an ATP response message. The response message includes the protocol version in use, the status code, and a reason phrase.

Response = Status_line CRLF Header_field^* CRLF [ Message_body ]

Status_line= ATP_version SP Status_code SP Reason_phrase CRLF

8. Header Fields

Header fields are associated with ATP messages. Some are valid only with respect to the sender, some only with respect to the recipient, and others are valid with respect to both. A header field is a name/value pair.

Header_field = Name : [ Value ] CRLF

Value = <Text, excluding CR/LF>

The table below indicates the usage of header fields for each of the four request methods and the response. In this table, yes means that the corresponding header field should be included in the message and may be used by the recipient, while no means that it is not included.

	Request				Response
	DISPATCH	RETRACT	FETCH	MESSAGE
Date	yes	yes	yes	yes	yes
User-Agent	yes	yes	yes	yes	yes
From	yes	yes	yes	yes	no
Agent-System	yes	yes	yes	yes	yes
Agent-Language	yes	no	yes	yes	yes
Content-Type	yes	no	no	yes	yes
Content-Encoding	yes	no	no	yes	yes
Content-Length	yes	no	no	yes	yes
Agent-Id	yes	yes	no	yes	yes

8.1 Date

The Date field represents the date and time at which the message was originated. This field is valid for both a sender and a receiver. See section 4.4 for the definition of ATP_date.

Date = "Date:" ATP_date

An example is :

Date:"Sat, 12 Aug 1995 13:30:00 GMT"

8.2 User-Agent

The User-Agent field contains information about the application originating a message.

User-Agent = "User-Agent:" Comment

Comment = <Textual description>

An example is:

User-Agent: Tahiti aglet viewer

8.3 From

The From field in requests contains an Internet email address for the human user who controls or owns the requesting sender application.

From = "From:" Mail_address

Mail_address = <Normal email address>

An example is:

From: AgentMaster@trl.ibm.co.jp

8.4 Agent-System

The Agent-System field in requests contains information about the agent platform of the originating agent. This information is used to call the request handler of a specific agent platform (see section 2.1)

Agent_system = "Agent-System:" Comment

Comment = <Textual description>

Examples are:

Agent-System: ibm.aglets

Agent-System: ibm.aglets/Alpha4b

8.5 Agent-Language

The Agent-Language field contains information about the language processor or system needed to execute or interpreter a code (transferred agent or a fetched class) in the message body.

Agent_language = "Agent-Language:" Comment

Comment = <Textual description>

An example is:

Agent-Language: java

8.6 Content-Type

The Content-Type field is used to determine the media type of the message body. It can be omitted if the message body is null

Content_type = "Content-Type:" Comment

Comment = <Textual description>

An example (for a dispatch request) is:

Content-Type: x-aglets

8.7 Content-Encoding

The Content-Encoding field is used as a modifier to the Content-Type field. When present, it indicates what coding mechanism has been applied to the message body, and thus what decoding mechanism must be applied to obtain the original content of that body.

Content_encoding = "Content-Encoding:" Comment

Comment = <Textual description>

An example is:

Content-Encoding: gzip

8.8 Content-Length

The Content-Length field indicates the size of the message body to be transferred, regardless of type and encoding.

Content_length = "Content -Length "Length

Length = <Decimal number>

An example is:

Content-Length: 8401

8.9 Agent-Id

The Agent-Id field in requests identifies the identifier of the agent whom the request refers to. See section 4.3 for the syntax of an agent identifier. It is also used by a response to a retract request to specify the identifier of the retracted agent.

Agent-Id = "Agent-Id: " Agent_identifier

Agent-Id: 2874678384

9. Status Code and Reason Phrase

The status code is a 3-digit integer result code of the recipient's attempt to process the request message. The reason phrase is intended to give a short textual description of the status code. The body of the response message can be used to give detailed status information.

Status_code = Digit⁺

Reason_phrase = <Text, excluding CR/LF>

9.1 Successful 1xx

Response status codes beginning with the digit one (1) indicates that the request message was received, understood, and properly processed.

100 OKAY

The request has succeeded.

9.2 Redirection 2xx

Response status codes beginning with the digit two (2) indicates that further action needs to be taken by the sender in order to see the request fulfilled.

200 MOVED

The requested resource is no longer at the recipient. For example, trying to retract an agent which had been already dispatched to another host. The body of the response message may contain the new URL of the requested resource.

9.3 Sender Error 3xx

Response status codes beginning with the digit three (3) indicates that the sender apparently has erred.

300 BAD REQUEST

The recipient was unable to understand the request due to malformed syntax.

301 FORBIDDEN

Although the recipient understood the request message, it is refusing to fulfill it. For example, trying to retract an agent which can not be retract due to security reasons.

302 NOT FOUND

The recipient could not find the requested resource. For example, trying to fetch a class which does not exist at the destination host.

9.4 Recipient Error 4xx

Response status codes beginning with the digit four (4) indicates that the recipient has erred or is unable of performing the request.

400 INTERNAL RECIPIENT ERROR

The recipient encountered an unexpected condition which prevented it from fulfilling the request. For example, The current ATP version at the recipient does not matched with the ATP version specified in the request line.

401 NOT IMPLEMENTED

The recipient does not support the functionality required to fulfill the request. For example, using a request method which is neither implemented nor familiar to the recipient.

402 BAD GATEWAY

The recipient, while acting as a gateway or proxy, received an invalid response from upstream server.

403 SERVICE UNAVAILABLE

The recipient is currently unable to handle the request due to a temporary overloading of the recipient. That is, the recipient is busy handling previous messages.

10. Acknowledgments

This specification is modeled on the HTTP/1.0 specification. Thanks to its authors Tim Berners-Lee, Roy Fielding, and Henrik Frystyk.

References

[1] R. Braden. "Requirements for Internet hosts-application and support", STD 3, RFC 1123, IETF, October 1989.

[2] J. Reynolds, J. Postel. "Assigned Numbers", STD2, RFC 1700, IETF, October 1994.

[3] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource Locators (URL)", RFC 1738, CERN, December 1994.

[4] R. Fielding. "Relative Uniform Resource Locators", RFC 1808, UC Irvine, June 1995.