Language Agnostic Definition

An Autonomous Economic Agent is, in technical terms, defined by the following characteristics:

  • It MUST be capable of receiving and sending Envelopes which satisfy the following protobuf schema:
    syntax = "proto3";
    
    package aea;
    
    message Envelope{
        string to = 1;
        string sender = 2;
        string protocol_id = 3;
        bytes message = 4;
        string uri = 5;
    }
    
    The format for the above fields, except message, is specified below.
    • to and sender: an address derived from the private key of a secp256k1-compatible elliptic curve
    • protocol_id: this must match a defined regular expression (see below)
    • message: a bytes string representing a serialized message in the specified protocol
    • URI: this syntax
  • It MUST implement each protocol's message with the required meta-fields:
    import "google/protobuf/struct.proto";
    
    
    message DialogueMessage {
        int32 message_id = 1;
        string dialogue_starter_reference = 2;
        string dialogue_responder_reference = 3;
        int32 target = 4;
        bytes content = 5;
    }
    
    message Message {
        oneof message {
            google.protobuf.Struct body = 1;
            DialogueMessage dialogue_message = 2;
        }
    }
    
    where content is replaced with the protocol specific content (see here for details).
  • It MUST implement protocols according to their specification (see here for details).
  • It SHOULD implement the fetchai/default:0.11.0 protocol which satisfies the following protobuf schema:
    syntax = "proto3";
    
    package aea.fetchai.default;
    
    message DefaultMessage{
    
        // Custom Types
        message ErrorCode{
            enum ErrorCodeEnum {
                UNSUPPORTED_PROTOCOL = 0;
                DECODING_ERROR = 1;
                INVALID_MESSAGE = 2;
                UNSUPPORTED_SKILL = 3;
                INVALID_DIALOGUE = 4;
              }
            ErrorCodeEnum error_code = 1;
        }
    
    
        // Performatives and contents
        message Bytes_Performative{
            bytes content = 1;
        }
    
        message Error_Performative{
            ErrorCode error_code = 1;
            string error_msg = 2;
            map<string, bytes> error_data = 3;
        }
    
        message End_Performative{}
    
    
        oneof performative{
            Bytes_Performative bytes = 5;
            End_Performative end = 6;
            Error_Performative error = 7;
        }
    }
    
  • The protocol id MUST match the following regular expression: ^([a-zA-Z_][a-zA-Z0-9_]{0,127})/([a-zA-Z_][a-zA-Z0-9_]{0,127})(:((any|latest|((0|[1-9]\d*))\.((0|[1-9]\d*))\.((0|[1-9]\d*))(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?)))?$
  • It is recommended that it processes Envelopes asynchronously. Note, the specification regarding the processing of messages does not impose any particular implementation, and the AEA can be designed to process envelopes either synchronously and asynchronously. However, asynchronous message handling enables the agent to be more responsive and scalable in maintaining many concurrent dialogues with its peers.
  • It MUST have an identity in the form of, at a minimum, an address derived from a public key and its associated private key (where the elliptic curve must be of type SECP256k1).
  • It SHOULD implement handling of errors using the fetchai/default:0.11.0 protocol. The protobuf schema is given above.
  • It MUST implement the following principles when handling messages:
    • It MUST ALWAYS handle incoming envelopes/messages and NEVER raise an exception when decoding and validating the message. This ensures another AEA cannot cause the agent to fail by sending a malicious envelope/message.
    • It MUST NEVER handle outgoing messages and ALWAYS raise an exception when validating the message. An exception implies that the handler is resolving a bug in the implementation.

Note

Additional constraints will be added soon!