Skip to content

Core components - Part 1

The AEA framework consists of several core elements, some of which are required to run an AEA and others which are optional.

The following sections discuss the use of the AEA framework, in particular its dominant usage where the framework is in charge of calling the code in custom packages (see inversion of control). Whilst it is in principle possible to use parts of the framework as a library, we do not recommend it.

The elements each AEA uses

AEAs communicate asynchronously via Envelopes.

Envelope

Envelope of an AEA

An Envelope is the core object with which agents communicate. It is a vehicle for Messages with five attributes:

  • to: defines the destination address.

  • sender: defines the sender address.

  • protocol_id: defines the id of the Protocol.

  • message: is a bytes field which holds the Message in serialized form.

  • Optional[context]: an optional field to specify routing information in a URI.

Messages must adhere to a Protocol.

Protocol

Protocols define agent-to-agent as well as component-to-component interactions within agents. As such, they include:

  • Messages, which define the representation;

  • serialization logic, which define how a Message is encoded for transport; and, optionally

  • Dialogues, which define rules over Message sequences.

The framework provides one default Protocol, called default (current version fetchai/default:0.11.0). This Protocol provides a bare-bones implementation for an AEA Protocol which includes a DefaultMessage class and associated DefaultSerializer and DefaultDialogue classes.

Additional Protocols - i.e. a new type of interaction - can be added as packages and generated with the protocol generator. For more details on Protocols also read the Protocol guide here.

Protocol specific Messages, wrapped in Envelopes, are sent and received to other agents, agent components and services via Connections.

Connection

A Connection wraps an SDK or API and provides an interface to network, ledgers and other services. Where necessary, a Connection is responsible for translating between the framework specific Envelope with its contained Message and the external service or third-party protocol (e.g. HTTP).

The framework provides one default Connection, called stub (current version fetchai/stub:0.15.0). It implements an I/O reader and writer to send Messages to the agent from a local file.

Additional Connections can be added as packages. For more details on Connections also read the Connection guide here.

An AEA can run Connections via a Multiplexer.

Multiplexer

Multiplexer of an AEA

The Multiplexer is responsible for maintaining potentially multiple Connections.

It maintains an InBox and OutBox, which are, respectively, queues for incoming and outgoing Envelopes from the perspective of Skills.

Skill

Skills of an AEA

Skills are the core focus of the framework's extensibility as they implement business logic to deliver economic value for the AEA. They are self-contained capabilities that AEAs can dynamically take on board, in order to expand their effectiveness in different situations.

A Skill encapsulates implementations of the three abstract base classes Handler, Behaviour, Model, and is closely related with the abstract base class Task:

  • Handler: each Skill has none, one or more Handler objects, each responsible for the registered messaging Protocol. Handlers implement AEAs' reactive behaviour. If the AEA understands the Protocol referenced in a received Envelope, the Handler reacts appropriately to the corresponding Message. Each Handler is responsible for only one Protocol.
  • Behaviour: none, one or more Behaviours encapsulate actions which further the AEAs goal and are initiated by internals of the AEA, rather than external events. Behaviours implement AEAs' pro-activeness. The framework provides a number of abstract base classes implementing different types of behaviours (e.g. cyclic/one-shot/finite-state-machine/etc.).
  • Model: none, one or more Models that inherit from the Model can be accessed via the SkillContext.
  • Task: none, one or more Tasks encapsulate background work internal to the AEA. Task differs from the other three in that it is not a part of Skills, but Tasks are declared in or from Skills if a packaging approach for AEA creation is used.

A Skill can read (parts of) the state of the the AEA (as summarised in the AgentContext), and suggest actions to the AEA according to its specific logic. As such, more than one Skill could exist per Protocol, competing with each other in suggesting to the AEA the best course of actions to take. In technical terms this means Skills are horizontally arranged.

For instance, an AEA which is trading goods, could subscribe to more than one Skill, where each Skill corresponds to a different trading strategy. The Skills could then read the preference and ownership state of the AEA, and independently suggest profitable transactions.

The framework places no limits on the complexity of Skills. They can implement simple (e.g. if-this-then-that) or complex (e.g. a deep learning model or reinforcement learning agent).

The framework provides one default Skill, called error. Additional Skills can be added as packages. For more details on Skills also read the Skill guide here.

Main loop

The main AgentLoop performs a series of activities while the Agent state is not stopped.

  • act(): this function calls the act() function of all active registered Behaviours.
  • react(): this function grabs all Envelopes waiting in the InBox queue and calls the handle() function for the Handlers currently registered against the Protocol of the Envelope.
  • update(): this function dispatches the internal Messages from the decision maker (described below) to the handler in the relevant Skill.

Next steps

We recommend you continue with the next step in the 'Getting Started' series:

Relevant deep-dives

Most AEA development focuses on developing the Skills and Protocols necessary for an AEA to deliver against its economic objectives.

Understanding Protocols is core to developing your own agent. You can learn more about the Protocols agents use to communicate with each other and how they are created in the following section:

Most of an AEA developer's time is spent on Skill development. Skills are the core business logic components of an AEA. Check out the following guide to learn more:

In most cases, one of the available Connection packages can be used. Occasionally, you might develop your own Connection: