File Structure

An agent that is generated using the AEA framework is a modular system with different connections, contracts, protocols and skills.

An AEA Project's File Structure

The file structure of an AEA is fixed.

The top level directory has the AEA's name. Below is a aea-config.yaml configuration file, then directories containing the connections, contracts, protocols, and skills developed by the developer as part of the given project. The connections, contracts, protocols and skills used from the registry (local or remote - added via aea fetch or aea add) are located in vendor and sorted by author. Build artefacts are placed in the .build/ directory and certificates are placed in the .certs/ directory. Finally, there are files containing the private keys of the AEA.

When we create a new agent with the command aea create my_aea we create the file structure that looks like the following:

aea_name/
  aea-config.yaml       YAML configuration of the AEA
  fetchai_private_key.txt   The private key file
  connections/          Directory containing all the connections developed as part of the given project.
    connection_1/       First connection
    ...                 ...
    connection_n/       nth connection
  contracts/            Directory containing all the contracts developed as part of the given project.
    connection_1/       First connection
    ...                 ...
    connection_n/       nth connection
  protocols/            Directory containing all the protocols developed as part of the given project.
    protocol_1/         First protocol
    ...                 ...
    protocol_m/         mth protocol
  skills/               Directory containing all the skills developed as part of the given project.
    skill_1/            First skill
    ...                 ...
    skill_k/            kth skill
  vendor/               Directory containing all the added resources from the registry, sorted by author.
    author_1/           Directory containing all the resources added from author_1
      connections/      Directory containing all the added connections from author_1
        ...             ...
      protocols/        Directory containing all the added protocols from author_1
        ...             ...
      skills/           Directory containing all the added skills from author_1
        ...             ...

The developer can create new directories where necessary but the core structure must remain the same.

AEA Configuration YAML

The aea-config.yaml is the top level configuration file of an AEA. It defines the global configurations as well as the component/package dependencies of the AEA. In some sense, the AEA can therefore be understood as an orchestrator of components.

For the AEA to use a package, the public_id for the package must be listed in the aea-config.yaml file, e.g.

connections:
- fetchai/stub:0.21.3

The above shows a part of the aea-config.yaml. If you see the connections, you will see that we follow a pattern of author/name_package:version to identify each package, also referred to as public_id. Here the author is the author of the package.

Vendor and Package Directories

The vendor folder contains the packages from the registry (local or remote) which have been developed by ourselves, other authors or Fetch.ai and are placed in different namespaces according to the author name.

The packages we develop as part of the given AEA project are in the respective connections/, contracts/, protocols/, and skills/ folders.

In the above configuration example, the package is authored by Fetch.ai and is located inside the vendor/fetchai/connections folder.

Importing Modules from Packages

The way we import modules from packages inside the agent is in the form of packages.{author}.{package_type}.{package_name}.{module_name}. So for the above example, the import path is packages.fetchai.connections.stub.{module_name}.

The framework loads the modules from the local agent project and adds them to Python's sys.modules under the respective path.

We use a custom package management approach for the AEAs rather than the default Python one as it provides us with more flexibility, especially when it comes to extension beyond the Python ecosystem.

Python Dependencies of Packages

Python dependencies of packages are specified in their respective configuration files under dependencies. They will be installed when aea install is run on an agent project.

Create a Package

If you want to create a package, you can use the CLI command aea scaffold connection/contract/protocol/skill [name] and this will create the package and put it inside the respective folder based on the command for example if we scaffold skill with the name my_skill it will be located inside the folder skills in the root directory of the agent (my_aea/skills/my_skill).

Use Published Packages from the Registry

If you want to use a finished package, you can use a package from the registry.

There or two registries. The remote registry operated by Fetch.ai and a local registry stub. The local registry stub is a directory called packages which contains packages in a nested structure with authors on the top level, followed by the package type, then package name. An example of such a directory is the packages directory located in the AEA repository. The local registry is useful for development.

You can use the CLI to interact with the registry. By default, the CLI points to the remote registry. You can point it to the local registry via the flag --local.

Package Versioning

By default, the AEA can only handle one version per package. That is, a project should never use both some_author/some_package_name:0.1.0 and some_author/some_package_name:0.2.0.

If two AEA packages with the same author and name but different versions are used in the same Python process, then only the code from one of the packages (generally not deterministic) will be available in sys.modules. This can lead to inconsistencies and exceptions at runtime.