AEA quick start
If you want to create Autonomous Economic Agents (AEAs) that can act independently of constant user input and autonomously execute actions to achieve their objective, you can use the Fetch.ai AEA framework.
This example will take you through the simplest AEA in order to make you familiar with the framework basics.
System Requirements
The AEA framework can be used on Windows
, Ubuntu/Debian
and MacOS
.
You need Python 3.6 or higher as well as Go 1.14.2 or higher installed.
Option 1: Manual system preparation
Install a compatible Python and Go version on your system.
The following hints can help:
-
To install Go, follow the official guide, depending on your platform here
-
Python is already included by default on many Linux distributions (e.g. Ubuntu), as well as MacOS. To check you have the right version, open a terminal and run:
python3 --version
-
To install Python on Windows machines, you can download a specific release here.
-
Ubuntu/Debian systems only: install Python headers, depending on the Python version you have installed on your machine. E.g. for Python 3.7:
sudo apt-get install python3.7-dev
-
Windows users: install tools for Visual Studio.
Option 2: Using Docker
We also provide a Docker image with all the needed dependencies.
Docker approach
To use the image you will first have to pull it and than run it with your current local directory mounted as a docker volume. This allows you to keep your agents local while working on them from within the docker container. To pull:docker pull fetchai/aea-user:latest
docker run -it -v $(pwd):/agents --workdir=/agents fetchai/aea-user:latest
docker run -it -v %cd%:/agents --workdir=/agents fetchai/aea-user:latest
Preliminaries
We have created a template repo for AEA development here which you can optionally fork and use immediately.
Alternatively, create and enter into a new working directory:
mkdir my_aea_projects/
cd my_aea_projects/
Unless you are using the docker image, we highly recommend using a virtual environment to ensure consistency across dependencies.
Check that you have pipenv
.
which pipenv
If you don't have it, install it. Instructions are here.
Once installed, create a new environment and open it (here we use Python 3.7 but the AEA framework supports any Python >= 3.6).
touch Pipfile && pipenv --python 3.7 && pipenv shell
For more guidance on setting up a development environment check out this guide.
Installation
The following installs the entire AEA package which also includes a command-line interface (CLI).
pip install aea[all]
If you are using zsh
rather than bash
type
pip install 'aea[all]'
If the installation steps fail, it might be a dependency issue. Make sure you have followed all the relevant system specific steps above under System Requirements
.
Setup author name
AEAs are composed from components. The components can be developed by anyone and are available on the AEA registry. To use the registry we need to register an author name.
You can setup your author name using the init
command:
aea init
This is your unique author name in the Fetch.ai ecosystem.
You should see a similar output (with your input replacing the sample input):
Do you have a Registry account? [y/N]: n
Create a new account on the Registry now:
Username: fetchai
Email: [email protected]
Password:
Please make sure that passwords are equal.
Confirm password:
_ _____ _
/ \ | ____| / \
/ _ \ | _| / _ \
/ ___ \ | |___ / ___ \
/_/ \_\|_____|/_/ \_\
v0.9.1
AEA configurations successfully initialized: {'author': 'fetchai'}
Note
If you would rather not create an account on the registry at this point, then run `aea init --local` instead.
Echo skill demo
The echo skill demo is a simple demo that introduces you to the main business logic components of an AEA. The echo skill simply echoes received messages back to the sender.
The fastest way to create your first AEA is to fetch it!
aea fetch fetchai/my_first_aea:0.18.0
cd my_first_aea
To learn more about the folder structure of an AEA project read on here.
Alternatively: step by step install
Create a new AEAFirst, create a new AEA project and enter it.
aea create my_first_aea
cd my_first_aea
Add the echo skill
Second, add the echo skill to the project.
aea add skill fetchai/echo:0.13.0
Communication via envelopes and messages
AEAs use envelopes containing messages for communication. To learn more check out the next section in the getting started series.
Usage of the stub connection
In this demo we use a stub connection to send envelopes to and receive envelopes from the AEA.
The stub connection is already added to the AEA by default.
A stub connection provides an I/O reader and writer. It uses two files for communication: one for incoming envelopes and the other for outgoing envelopes.
The AEA waits for a new envelope posted to the file my_first_aea/input_file
, and adds a response to the file my_first_aea/output_file
.
The format of each envelope is the following:
TO,SENDER,PROTOCOL_ID,ENCODED_MESSAGE,
For example:
recipient_aea,sender_aea,fetchai/default:0.11.0,\x08\x01\x12\x011*\x07\n\x05hello,
Run the AEA
Run the AEA with the default fetchai/stub:0.15.0
connection.
aea run
or
aea run --connections fetchai/stub:0.15.0
You will see the echo skill running in the terminal window.
_ _____ _
/ \ | ____| / \
/ _ \ | _| / _ \
/ ___ \ | |___ / ___ \
/_/ \_\|_____|/_/ \_\
v0.9.1
Starting AEA 'my_first_aea' in 'async' mode ...
info: Echo Handler: setup method called.
info: Echo Behaviour: setup method called.
info: [my_first_aea]: Start processing messages...
info: Echo Behaviour: act method called.
info: Echo Behaviour: act method called.
info: Echo Behaviour: act method called.
...
The framework first calls the setup
method on the Handler
, and Behaviour
code in that order; after which it repeatedly calls the Behaviour method act
. This is the main agent loop in action.
Add a message to the input file
From a different terminal and same directory, we send the AEA a message wrapped in an envelop using the CLI interact command:
cd my_first_aea
aea interact
You can now send the AEA messages via an interactive tool by typing hello
into the prompt and hitting enter twice (once to send, once more to check for a response). You will see the Echo Handler
dealing with the envelope and contained message (your dialogue reference will be different):
info: Echo Behaviour: act method called.
info: Echo Handler: message=Message(dialogue_reference=('1', '') message_id=1 target=0 performative=bytes content=b'hello'), sender=my_first_aea_interact
info: Echo Behaviour: act method called.
info: Echo Behaviour: act method called.
Manual approach
Optionally, from a different terminal and same directory (i.e. the `my_first_aea` project), we send the AEA a message wrapped in an envelope via the input file.echo 'my_first_aea,sender_aea,fetchai/default:0.11.0,\x12\x10\x08\x01\x12\x011*\t*\x07\n\x05hello,' >> input_file
info: Echo Behaviour: act method called.
Echo Handler: message=Message(sender=sender_aea,to=my_first_aea,content=b'hello',dialogue_reference=('1', ''),message_id=1,performative=bytes,target=0), sender=sender_aea
info: Echo Behaviour: act method called.
info: Echo Behaviour: act method called.
Stop the AEA
Stop the AEA by pressing CTRL C
You should see the AEA being interrupted and then calling the teardown()
methods:
info: Echo Behaviour: act method called.
info: Echo Behaviour: act method called.
^C my_first_aea interrupted!
my_first_aea stopping ...
info: Echo Handler: teardown method called.
info: Echo Behaviour: teardown method called.
Write a test for the AEA
We can write an end-to-end test for the AEA utilising helper classes provided by the framework.
Writing tests
The following test class replicates the preceding demo and tests it's correct behaviour. The `AEATestCase` classes are a tool for AEA developers to write useful end-to-end tests of their AEAs. First, get the packages directory from the AEA repository (execute from the working directory which contains the `my_first_aea` folder):svn export https://github.com/fetchai/agents-aea.git/trunk/packages
import signal
import time
from aea.common import Address
from aea.mail.base import Envelope
from aea.protocols.base import Message
from aea.protocols.dialogue.base import Dialogue
from packages.fetchai.protocols.default.dialogues import DefaultDialogue, DefaultDialogues
from packages.fetchai.protocols.default.message import DefaultMessage
from packages.fetchai.protocols.default.serialization import DefaultSerializer
from aea.test_tools.test_cases import AEATestCase
class TestEchoSkill(AEATestCase):
"""Test that echo skill works."""
def test_echo(self):
"""Run the echo skill sequence."""
process = self.run_agent()
is_running = self.is_running(process)
assert is_running, "AEA not running within timeout!"
# add sending and receiving envelope from input/output files
sender_aea = "sender_aea"
def role_from_first_message(
message: Message, receiver_address: Address
) -> Dialogue.Role:
return DefaultDialogue.Role.AGENT
dialogues = DefaultDialogues(sender_aea, role_from_first_message)
message_content = b"hello"
message = DefaultMessage(
performative=DefaultMessage.Performative.BYTES,
dialogue_reference=dialogues.new_self_initiated_dialogue_reference(),
content=message_content,
)
sent_envelope = Envelope(
to=self.agent_name,
sender=sender_aea,
protocol_id=message.protocol_id,
message=DefaultSerializer().encode(message),
)
self.send_envelope_to_agent(sent_envelope, self.agent_name)
time.sleep(2.0)
received_envelope = self.read_envelope_from_agent(self.agent_name)
assert sent_envelope.to == received_envelope.sender
assert sent_envelope.sender == received_envelope.to
assert sent_envelope.protocol_id == received_envelope.protocol_id
received_message = DefaultMessage.serializer.decode(received_envelope.message)
assert message.content == received_message.content
check_strings = (
"Echo Handler: setup method called.",
"Echo Behaviour: setup method called.",
"Echo Behaviour: act method called.",
"content={}".format(message_content),
)
missing_strings = self.missing_from_output(process, check_strings)
assert (
missing_strings == []
), "Strings {} didn't appear in agent output.".format(missing_strings)
assert (
self.is_successfully_terminated()
), "Echo agent wasn't successfully terminated."
pytest test.py
Delete the AEA
Delete the AEA from the parent directory (cd ..
to go to the parent directory).
aea delete my_first_aea
Next steps
To gain an understanding of the core components of the framework, please continue to the next step of 'Getting Started':
For more demos, use cases or step by step guides, please check the following: