Skip to content

Core components - Part 1

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

The following sections discuss the inner workings of the AEA framework and how it calls the code in custom packages (see inversion of control and a helpful comparison here). 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

Envelope

Envelope of an AEA

AEA objects communicate asynchronously via Envelopes.

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 AEAs. As such, they include:

  • Messages defining the syntax of messages;

  • Serialization defining 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:1.1.2). This Protocol provides a bare-bones implementation for an AEA Protocol which includes a DefaultMessage class and associated DefaultSerializer and DefaultDialogue classes.

Additional Protocols, for new types of interactions, can be added as packages. For more details on Protocols you can read the protocol guide. To learn how you can easily automate protocol definition, head to the guide for the protocol generator.

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 networks, ledgers or 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.21.1). 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 read the Connection guide .

An AEA runs and manages 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 zero, one or more Handler objects. There is a one-to-one correspondence between Handlers and the protocols in an AEA (also known as the registered protocols). Handlers implement AEAs' reactive behaviour. If an AEA understands a Protocol referenced in a received Envelope (i.e. the protocol is registered in this AEA), this envelope is sent to the corresponding Handler which executes the AEA's reaction to this Message.
  • Behaviour: a skill can have zero, one or more Behaviours, each encapsulating 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 simple and composite behaviours (e.g. cyclic, one-shot, finite-state-machine, etc), and these define how often and in what order a behaviour and its sub-behaviours must be executed.
  • Model: zero, one or more Models that inherit from the Model abstract base class and are accessible via the SkillContext.
  • Task: zero, 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) an AEA's state (as summarised in the AgentContext), and suggests 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 corresponds to a different trading strategy.

The framework places no limits on the complexity of Skills. They can implement simple (e.g. if-this-then-that) logic or be 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 head over to the Skill guide .

Agent loop

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

  • it calls the act() function of all active registered Behaviours at their respective tick rate.
  • it grabs all Envelopes waiting in the InBox queue and calls the handle() function for the Handlers currently registered against the Protocol of the Envelope.
  • it dispatches the internal Messages from the decision maker (described below) to the handler in the relevant Skill.

The AgentLoop and Multiplexer are decoupled via the InBox and OutBox, and both are maintained by the Runtime.

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: