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 AEA framework.
This example will take you through a simple AEA to familiarise you with the basics of the framework.
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.
GCC installation is required:
* Ubuntu: apt-get install gcc
* Windows (with choco
installed): choco install mingw
* MacOS X (with home brew): brew install gcc
Option 1: Manual system preparation
Install a compatible Python and Go version on your system (see this external resource for a comprehensive guide).
Manual approach
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:
- 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:
- Windows users: install tools for Visual Studio.
Option 2: Using an automated install script
We provide a script to automatically install all framework dependencies and the framework itself. This means that if you follow this option, you can skip the installation step that comes later on this page.
Automated install script approach
On MacOS or Ubuntu run the following commands to download and install:curl https://raw.githubusercontent.com/fetchai/agents-aea/main/scripts/install.sh --output install.sh
chmod +x install.sh
./install.sh
install.ps1 with the PowerShell terminal.
Option 3: 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: To run the image on Linux and MacOs: And on Windows: Once successfully logged into the docker container, you can follow the rest of the guide the same way as if not using docker. Preliminaries
Ensure, you are in a clean working directory:
-
either you create it manually
mkdir my_aea_projects/ && cd my_aea_projects/, then add an empty directory calledpackageswith the following commandmkdir packages/, -
or you clone the template repo as described in
Approach 1in the development setup guide.
At this point, when typing ls you should see a single folder called packages in your working environment. This will act as your local registry for AEA components.
Unless you are using the docker image, we highly recommend using a virtual environment to ensure consistency across dependencies.
Check that you have 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).
Installation
The following installs the entire AEA package which also includes a command-line interface (CLI). (You can skip this step if you used the install script above: Option 2 .)
If you are using zsh rather than bash type
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. AEAs and AEA components can be developed by anyone and pushed to the AEA registry for others to use. To use the registry, we need to register an author name.
You can set up your author name using the init command:
This is your unique author (or developer) name in the AEA ecosystem.
You should see a similar output (with your input instead of the sample username and email):
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:
_ _____ _
/ \ | ____| / \
/ _ \ | _| / _ \
/ ___ \ | |___ / ___ \
/_/ \_\|_____|/_/ \_\
v1.1.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
This is a simple demo that introduces you to the main components of an AEA.
The fastest way to have your first AEA is to fetch one that already exists!
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.
Add the stub connection
Second, add the stub connection to the project.
Add the echo skill
Third, add the echo skill to the project. This copies the
fetchai/echo:0.20.1 skill code containing the "behaviours", and "handlers" into the project, ready to run. The identifier of the skill fetchai/echo:0.20.1 consists of the name of the author of the skill, followed by the skill name and its version.
Echo skill
Just like humans, AEAs can have skills to achieve their tasks. As an agent developer, you can create skills to add to your own AEAs. You can also choose to publish your skills so others add them to their AEAs. More details on skills can be found on this page .
The above agent has an echo skill, fetched from the registry, which simply echoes any messages it receives back to its sender.
Communication via envelopes and messages
AEAs use envelopes containing messages for communication. To learn more, check out the next section.
Stub connection
Besides skills, AEAs may have one or more connections enabling them to interface with entities in the outside world. For example, an HTTP client connection allows an AEA to communicate with HTTP servers. To read more about connections see this page.
In this demo, we use the stub connection (fetchai/stub0.15.0) to send envelopes to and receive envelopes from the AEA.
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:
For example:
Install AEA dependencies
Add and create a private key
All AEAs need a private key to run. Add one now:
Run the AEA
Run the AEA.
You will see the echo skill running in the terminal window (an output similar to the one below).
_ _____ _
/ \ | ____| / \
/ _ \ | _| / _ \
/ ___ \ | |___ / ___ \
/_/ \_\|_____|/_/ \_\
v1.1.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 methods in the skill's Handler and Behaviour classes in that order; after which it repeatedly calls the act method of Behaviour class. This is the main agent loop in action.
Add a message to the input file
You can send the AEA a message wrapped in an envelope using the CLI's interact command.
From a different terminal and same directory (ensure you are in the same virtual environment: pipenv shell):
You can now send messages to this AEA via an interactive tool by typing anything into the prompt and hitting enter twice (once to send the message and once more to check for a response).
Let us send hello to this AEA (type hello and press enter twice). In the original terminal, you will see the Echo Handler dealing with this envelope and its contained message. You should see an output similar to the one below but with a different dialogue_reference.
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. themy_first_aea project), you can send the AEA a message wrapped in an envelope via the input file.
echo 'my_first_aea,sender_aea,fetchai/default:1.0.0,\x12\x10\x08\x01\x12\x011*\t*\x07\n\x05hello,' >> input_file
Echo Handler dealing with the envelope and responding with the same message to the output_file, and also decoding the Base64 encrypted message in this case.
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.
aea interact command.
Stop the AEA
You can stop an AEA by pressing CTRL C.
Once you do, 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. TheAEATestCase 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):
Then write the test:
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."
test.py in your AEA project directory (the same level as the aea-config.yaml file).
To run, execute the following:
Delete the AEA
Delete the AEA from the parent directory (cd .. to go to the parent directory).
Next steps
To gain an understanding of the core components of the framework, please continue to the next page:
For more demos, use cases or step by step guides, please check the following: