Addons¶

An addon gives the agent more skills, tools, MCP servers, or system prompt text. It can also need more python packages and more jobflow-remote workers. The core of atomatic stays the same.

Use an addon¶

List the installed addons. [x] marks the enabled ones:

$: atomatic addon

On the agent computer, install the packages of an addon and enable it:

$: atomatic addon --enable reactca

On the runner computer, install the packages for the runner and add the workers of the addon to your jobflow-remote config:

$: atomatic addon --enable reactca --runner

Disable an addon. Its packages stay. On the runner, --runner takes its workers out of the config:

$: atomatic addon --disable reactca

Specification¶

All addons¶

Name: one lowercase word, with no - or _, for example reactca. Use this name everywhere.

The addon dict: its keys are arguments of create_atomatic_agent. Each key is optional:

from pathlib import Path

addon = dict(
    skills=[str(Path(__file__).parent / "skills")],
    tools=[list_reactca_runs],
    mcp_servers=["http://127.0.0.1:8000/mcp"],
    system_prompt="\n\nDo not use the atomate2 tools for ReactCA grids.\n",
)

• skills: skill directories.
• tools: python functions or langchain tools.
• mcp_servers: MCP servers, as mcp.Client takes them.
• system_prompt: text after the atomatic system prompt.

The values of the enabled addons come before the values of the host. An unknown key stops the agent with an error.

Enabled addons: the .env holds their names, comma separated, with no spaces. atomatic addon writes this line, and atomatic configure keeps it:

ATOMATIC_ADDONS="reactca,mylab"

Workers: an addon can give jobflow-remote workers for each hpc site, in jfr_addenda/<site>.yaml next to its __init__.py. The site names are those of atomatic configure, for example hpc-nersc or local_remote. The file holds only the workers, as one mapping:

cpu_batch_reactca_1n:
  type: local
  scheduler_type: slurm
  work_dir: CHANGEME_PATH_TO_WORK_DIR/run
  pre_run: &reactca_env |
    source CHANGEME_PATH_TO_VENV
    export OMP_NUM_THREADS=1
  resources:
    account: CHANGEME_ACCOUNT
cpu_batch_reactca_1n_debug:
  pre_run: *reactca_env

• Use the CHANGEME values of the site template, for example CHANGEME_ACCOUNT.
• Do not use the anchors of the site template. Start your own anchors with the addon name.

The workers go at the end of workers: in the config, between two marker lines. The other lines of the config stay. atomatic configure adds the workers of an addon when this env has its runner extra, or when atomatic has no runner extra for it. atomatic addon --enable <name> --runner adds them to a config which is there already. It reads the site and the CHANGEME values from metadata: atomatic: in the config, and asks for any which are not there.

Built-in addons: a built-in addon is a subpackage of atomatic/addons. atomatic finds it there:

atomatic/addons/reactca/
├── __init__.py              # addon = dict(...)
├── jfr_addenda/hpc-nersc.yaml
└── skills/wf-reactca/
    ├── SKILL.md
    └── references/

Its packages are two extras of atomatic, in the addons section of pyproject.toml. <name> is for the agent computer, and runner-<name> is for the runner:

[project.optional-dependencies]
# addons
reactca = ["rxn-ca[workflow] @ git+https://github.com/mcgalcode/rxn-ca@4c1b9be"]
runner-reactca = ["rxn-ca[workflow] @ git+https://github.com/mcgalcode/rxn-ca@4c1b9be"]

External addons¶

An external addon is a python package of its own. atomatic finds it by its entry point in the group atomatic.addons. The entry point name is the addon name, and its value is the addon dict. The package ships its skill files and worker files as package data:

atomatic-mylab/
├── pyproject.toml
└── atomatic_mylab/
    ├── __init__.py          # addon = dict(...)
    ├── jfr_addenda/hpc-nersc.yaml
    └── skills/wf-mylab/SKILL.md

[project]
name = "atomatic-mylab"
dependencies = ["mylab-code"]

[project.optional-dependencies]
runner = ["mylab-code"]

[project.entry-points."atomatic.addons"]
mylab = "atomatic_mylab:addon"

Install and enable it:

$: uv pip install atomatic-mylab              # agent computer
$: atomatic addon --enable mylab
$: uv pip install "atomatic-mylab[runner]"    # runner computer
$: atomatic addon --enable mylab --runner

For your own addon, install it from its directory with uv pip install -e .

A built-in addon wins over an external addon of the same name.