Skip to content



The AEA framework can be used on Windows, Ubuntu/Debian and MacOS.

System Requirements

  1. You need Python 3.8, 3.9 or 3.10 on your system.
  2. GCC installation is also required:

    apt-get install gcc
    brew install gcc
    choco install mingw
  • Ubuntu/Debian: install Python headers, depending on the Python version you have installed on your machine. For example for Python 3.8:

    sudo apt-get install python3.8-dev
  • Windows: install tools for Visual Studio.

Alternatively: Use Docker

We also provide a Docker image with all the needed dependencies.

  1. Pull the image:

    docker pull fetchai/aea-user:latest
  2. Run the image 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:

    docker run -it -v $(pwd):/agents --workdir=/agents fetchai/aea-user:latest
    docker run -it -v %cd%:/agents --workdir=/agents fetchai/aea-user:latest

Once successfully logged into the docker container, you can follow the rest of the guide the same way as if not using docker.

For Agent Development


  1. Create a new working directory. Let's call it my_aea_projects. This is where you will create your agent projects.

  2. Inside my_aea_projects, add an empty directory called packages. This is a local registry for your agents' components.

You should now have the following directory structure:

└── packages

Alternatively, clone a template repo:

Instead of the above, you can clone the template repo as described in Approach 1 in the development setup guide.

Virtual Environment

Unless you are using the docker image, we highly recommend using a virtual environment so that your setup is isolated from the rest of your system. This prevents clashes and ensures consistency across dependencies.

You can use any common virtual environment manager for Python, such as pipenv and poetry. If you do not have either, install one.

Once installed, create a new virtual environment in the my_aea_projects directory and enter it:

Use any Python version supported in the command:

pipenv --python 3.9 && pipenv shell

poetry init -n && poetry shell


The latest version of the Python implementation of the AEA Framework is:



If you are upgrading your AEA project from a previous version of the AEA framework, make sure you check out the upgrading notes.

Using pip

Install the AEA framework using pip:

pip install aea[all]
pip install 'aea[all]'

To ensure no cache is used, add --force --no-cache-dir to the installation command.

Using pipx

Install the AEA framework using pipx:

pipx install aea[all]

For Contributing to the AEA Framework

To contribute to the development of the framework or related tools (e.g. ACN), please refer to the Contribution and Development guides in our GitHub repository.

Other Tools You Might Need

Depending on what you want to do, you might need extra tools on your system:

  • To use the Agent Communication Network (ACN) for peer-to-peer communication between agents (e.g. using the fetchai/p2p_libp2p connection) you will need Golang 1.14.2 or higher.
  • The framework uses Google Protocol Buffers for message serialization. If you want to develop protocols, install the protobuf compiler on your system. The version you install must match the protobuf library installed with the project (see pyproject.toml).
  • To update fingerprint hashes of packages, you will need the IPFS daemon.