Connections
A Connection
wraps an SDK or API and provides an interface to network, ledgers and other services. As such a connection is concerned with I/O bound and continuously connected operations. Where necessary, a connection is responsible for translating between the framework specific protocol (an Envelope
with its contained Message
) and the external service or third-party protocol (e.g. HTTP
).
The messages constructed or received by a connection are eventually processed by one or several skills which deal with handling and generating messages related to a specific business objective.
The framework provides one default connection, called stub
. 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.
An AEA
can interact with multiple connections at the same time via the Multiplexer
.
It maintains an InBox
and OutBox
, which are, respectively, queues for incoming and outgoing envelopes and their contained messages.
Configuration
The connection.yaml
file of a connection package contains meta information on the connection as well as all the required configuration details. For more details have a look here
Developing your own
The easiest way to get started developing your own connection is by using the scaffold command:
aea scaffold connection my_new_connection
This will scaffold a connection package called my_new_connection
with three files:
__init__.py
connection.py
, containing the scaffolded connection classconnection.yaml
, containing the scaffolded configuration file
Primary methods to develop
The scaffolded connection.py
file contains a single class inherited from the Connection
base class.
The developer needs to implement four public coroutines:
-
The
connect
coroutine implements the setup logic required to be performed for the connection when it is initially launched. Theconnect
coroutine is called by the AEA framework once when the agent is being started. -
The
disconnect
coroutine implements the teardown logic required to be performed for the connection when it is eventually stopped. Thedisconnect
coroutine is called by the AEA framework once when the agent is being stopped. -
The
send
coroutine is called by the AEA framework each time when theMultiplexer
handles an outgoing envelope specified to be handled by the connection. Thesend
coroutine must implement the processing of the envelope leaving the agent. -
The
receive
coroutine is continuously called by the AEA framework. It either returnsNone
or an envelope. Thereceive
coroutine must implement the logic of data being received by the agent and if necessary its translation into a relevant protocol.
When developing your own connection you might benefit from inspecting the fetchai/http_server:0.15.0
and fetchai/http_client:0.16.0
connections to gain more familiarity and inspiration.
Configuration options
The connection.yaml
files contains a number of fields required to be edited by the developer of the connection:
connections: []
protocols: []
class_name: MyScaffoldConnection
config:
foo: bar
excluded_protocols: []
restricted_to_protocols: []
dependencies: {}
is_abstract: false
cert_requests: []
connections
specifies the list of other connection this connection depends onprotocols
specifies the list of protocols this connection depends onclass_name
needs to match the name of the connection class inconnection.py
config
can contain arbitrary configuration information which is available in the constructor of the connectionexcluded_protocols
lists the protocols which cannot be used in this connectionrestricted_to_protocols
lists the protocols which this connection is restricted to be used bydependencies
lists any Python dependencies of the packageis_abstract
specifies whether this connection is only used as an abstract base classcert_requests
lists certification requests of the connection (see proof of representation for details)