Create and cd into a new working directory.

mkdir my_aea/
cd my_aea/

We highly recommend using a virtual environment to ensure consistency across dependencies.

Check 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.

touch Pipfile && pipenv --python 3.7 && pipenv shell

At some point, you will need Docker installed on your machine (e.g. to run an OEF Node).

If you don't have it, please check the official documentation here and follow the instructions for your platform.


Install the Autonomous Economic Agent framework.

The following installs the entire AEA package which includes the cli too.

pip install aea[all]

However, you can run this demo by installing the base AEA, including the CLI (Command Line Interface) extension, alone.

pip install aea[cli]

Known issues

If the installation steps fail, it might a dependency issue.

The following hints can help:

  • Ubuntu/Debian systems only: install Python 3.7 headers.

    sudo apt-get install python3.7-dev

  • Windows users: install tools for Visual Studio.

Echo skill demo

The echo skill is a simple demo that introduces you to the main business logic components of an AEA.

Download the scripts and packages directories.

svn export
svn export

Create a new agent

First create a new agent project and enter it.

aea create my_first_agent
cd my_first_agent

Add the echo skill

aea add skill echo

This copies the echo application code for the behaviours, handlers, and tasks into the skill, ready to run.

Add a stub connection

AEAs use messages for communication. We will add a stub connection to send messages to and receive messages from the AEA.

aea add connection stub

A stub connection provides an I/O reader/writer.

It uses two files for communication: one for the incoming messages and the other for the outgoing messages. Each line contains an encoded envelope.

The AEA waits for new messages posted to the file my_first_agent/input_file, and adds a response to the file my_first_agent/output_file.

The format of each line is the following:


For example:

recipient_agent,sender_agent,default,{"type": "bytes", "content": "aGVsbG8="}

Run the agent

Run the agent with the stub connection.

aea run --connection stub

You will see the echo task running in the terminal window.

The echo call and response log

The framework first calls the setup method on the Handler, Behaviour, and Task code in that order; after which it repeatedly calls the Behaviour and Task methods, act and execute. This is the main agent loop in action.

Let's look at the Handler in more depth.

Add a message to the input file

We send the AEA a message wrapped in an envelope via the input file.

echo 'my_first_agent,sender_agent,default,{"type": "bytes", "content": "aGVsbG8="}' >> input_file

You will see the 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 Task: execute method called.
info: Echo Behaviour: act method called.
info: Echo Handler: message=Message(type=bytes content=b'hello'), sender=sender_agent
info: Echo Task: execute method called.
info: Echo Behaviour: act method called.
info: Echo Task: execute method called.
info: Echo Behaviour: act method called.
info: Echo Task: execute method called.

Stub connection input and output

Stop the agent

Stop the agent by pressing CTRL C

Delete the agent

Delete the agent from the parent directory via cd ...

aea delete my_first_agent