Skip to main content

Getting Started

Let's get started with the ADK in less than 10 minutes.

What you'll need​

  • An AsterQuanta account.
  • Python version 3.13 and pip 26.2.1 only (will be less restrictive in future versions).
  • A Linux, macOS, or Windows development machine.

Quick start​

Setup development environment​

Make a new development environment with the following:

  1. Create and navigate to your agent directory:

    mkdir MyAgent/
    cd MyAgent/

  2. Create and enter a new venv for your agent (recommended):

    python -m venv .venv            # Create venv
    source ./.venv/bin/activate     # Activate venv

  1. Install the ADK:

    pip install --trusted-host pypi.asterquanta.com --index-url https://pypi.asterquanta.com/simple/ adk

    Now, you should be able to run genie -h and see the following:

    usage: genie [-h] {setup,run,update,status,model} ...

    Official AsterQuanta Genie ADK wizard.

    options:
    -h, --help            show this help message and exit

    commands:
    {setup,run,update,status,model}
        setup               Sets up the project, in a ready for development state.
        run                 Start the agent (runs src/main.py).
        update              Push the updates on settings.json to AQ server.
        status              Show agent detection and settings summary.
        model               Sub command tree for model related operations.

Create a new agent​

Roles and Permissions Required

If you are part of an organisation, before registering an agent, ensure that you have the required Agent Developer role to deploy agents. Not all Genie users are assigned this role by default. If you do not have the necessary permissions, you will not be able to register an agent.

Organization Users: Please verify your assigned role and required permissions with your administrator before proceeding with the ADK setup.

Create a new agent with the following:

  1. In your agent directory, run the following, and follow the instructions:

    genie setup -a <BASE_URL>

    Replace <BASE_URL> with the correct URL that your account is on:

    Genie should now have created the following directory structure:

    MyAgent
    ├── .agent_data/        # ADK internal data, do not modify manually!
    ├── .env                # ADK / server configuration.
    ├── settings.json       # Agent settings (name, description, default hyperparameters).
    ├── src                 # Agent source code directory.
    │   ├── agent.py        # RL agent implementation.
    │   ├── __init__.py     # Python init file for agent.
    │   └── main.py         # Agent / ADK connector entrypoint.

    See the Agents page to understand the full agent layout.

Update agent settings​

An agent's settings live in settings.json at the project root. You may edit this file to change the agent's name, description, hyper_parameters, or is_public visibility. You can also enable optional resource usage logging (resource_logging_options) to record CPU and memory samples to a local JSONL file while the agent is connected. You can push metadata changes to the AsterQuanta platform without restarting the agent by running:

genie update

For more info, refer to the Agent Settings page.

Update agent environment settings​

An agent's environment settings live in .env at the project root. You may edit this file to change connection settings and optional runtime identifiers such as INSTANCE_ID when running multiple copies of the same agent. Editing .env is generally only needed for deployment or local development; changes apply on the next agent start. For more info, refer to the Environment Settings page.

Create a new model​

This is the last step before a fully functional agent appears on the platform! A model is an abstraction that prevents developers from having to create a new agent for every circuit or system they build an agent for. It enables developers to implement one agent, once, and load it with different models depending on the task at hand. This is the Don't Repeat Yourself principle in full effect.

Create a new model with the following:

  1. In your agent directory:

    genie model add MyAgent-model

    You should now see a new models/ directory with the following structure created by genie:

    models/
    └── MyAgent-model
        ├── hyper_parameters.json
        ├── metadata.json
        ├── models
        ├── target_specifications.json
        └── world_control_specifications.json

  2. Modify models/MyAgent-model/metadata.json such that "bypass" is set to true, this makes it so that the model is not validated against the world control specifications and target specifications such that it can be used for any system:

    {
        ...
        "bypass": true,
        ...
    }

Start your agent​

Start the agent with:

genie run

or alternatively:

python src/main.py

Both of these commands run src/main.py, which typically creates a Connector and connects to the platform. See Running on the Cloud to start an optimization from the web UI.