Addons

AIO Agent supports customer-owned addons inside the plugin data folder:


plugins/aio_agent/data/addons/

Addons are for customer-specific behavior that should survive normal AIO Agent updates. Instead of editing core files in plugins/aio_agent/src/, put the customer changes in data/addons.

Your update process must preserve plugins/aio_agent/data/. If an updater deletes the whole aio_agent folder, it will also delete customer addons, knowledgebase files, prompt customizations, and cache data.

When To Use An Addon

Use an addon when a customer needs a custom AIO setup that is more than normal dashboard configuration, but should not become a hard-coded fork.

Good addon use cases:

customer-specific prompt files or prompt fragments
customer-specific default settings
extra prompt variables
extra knowledgebase text or sources
a branded ticket intake workflow
reload behavior tied to custom files

Do not use an addon for basic settings that already exist in the dashboard. Normal values like model name, timezone, docs URL, enabled modules, staff IDs, FAQ entries, and moderation settings should stay in AIO Agent configuration.

Folder Structure

Each addon gets its own folder:


plugins/aio_agent/data/addons/example/
  addon.json
  config.json5
  index.js
  README.md
  prompts/
    ticket-system.md
    owner-system.md

addon.json is the manifest. config.json5 is customer-owned config for the addon. index.js receives the AIO addon API and registers whatever the addon needs.

Manifest

Example addon.json:


{
  "id": "example",
  "name": "Example Customer Addon",
  "version": "1.0.0",
  "enabled": true,
  "required": false,
  "entry": "index.js",
  "config": "config.json5"
}

Field	Required	Description
`id`	yes	Stable addon ID. Use lowercase letters, numbers, dashes, or underscores.
`name`	yes	Human-friendly addon name shown in logs.
`version`	no	Addon version for support/debugging.
`enabled`	no	Set to `false` to skip the addon. Defaults to enabled.
`required`	no	If true, AIO Agent fails plugin load when this addon fails. Optional addons only log errors.
`entry`	no	JavaScript entry file. Defaults to `index.js`.
`config`	no	Addon config file. Defaults to `config.json5`.

The addon is skipped if either addon.json has enabled: false or config.json5 has enabled: false.

Addon API

The entry file exports a function or setup(api):


module.exports.setup = (api) => {
  api.registerConfigDefaults({
    tickets: {
      cooldown_seconds: 3
    }
  })
 
  api.registerPromptVariables(() => ({
    customer_policy_url: "https://example.com/policy"
  }))
 
  api.registerPromptFileOverrides({
    ticket: "prompts/ticket-system.md"
  })
 
  api.registerKnowledgeSource({
    id: "addon:example:policy",
    source: "addon/example/policy",
    title: "Example Policy",
    content: "Only answer policy questions from configured policy text."
  })
}

Available API methods:

Method	Purpose
`registerConfigDefaults(object)`	Adds fallback config values. Live dashboard/config values still win.
`registerPromptVariables(objectOrFunction)`	Adds prompt variables before prompt templates render.
`registerPromptFileOverrides(object)`	Overrides prompt files such as `ticket`, `owner`, `chat`, `ticket_role_body`, `ticket_important_context`, or `security_preamble`.
`registerPromptFragment(name, valueOrFunction)`	Adds a single prompt variable/fragment by name.
`registerKnowledgeSource(source)`	Adds text to the in-memory knowledgebase before search/full/hybrid retrieval.
`registerReloadHook(function)`	Runs custom reload logic during `/aio reload`.
`registerStartupNote(text)`	Adds a startup log note when the addon loads.
`readText(relativePath)`	Reads a file inside the addon folder.
`resolvePath(relativePath)`	Resolves a path inside the addon folder. Paths cannot escape the addon directory.

Prompt File Overrides

Prompt overrides can point to files inside the addon folder:


api.registerPromptFileOverrides({
  ticket: "prompts/ticket-system.md",
  owner: "prompts/owner-system.md",
  ticket_role_body: "prompts/ticket-role-body.md",
  ticket_important_context: "prompts/ticket-important-context.md"
})

The prompt file can use all normal AIO variables plus addon variables:


You are {{brand_name}}'s assistant.
 
Customer policy:
{{customer_policy_url}}
 
{{knowledgebase_block}}

Knowledgebase Addons

Addon knowledge sources are loaded at startup and /aio reload, then treated like other knowledgebase sources. They work with all knowledgebase modes:

full
search
hybrid
off

Use addon knowledge for short customer-specific facts, policy summaries, or workflow boundaries. Use plugins/aio_agent/data/knowledgebase/ for larger customer docs.

Updating AIO Safely

Recommended update behavior:


Update/replace:
plugins/aio_agent/src/
plugins/aio_agent/main.js
plugins/aio_agent/data/configs/
plugins/aio_agent/data/dashboard/
plugins/aio_agent/data/prompts/   only if the customer did not customize it

Preserve:
plugins/aio_agent/data/addons/
plugins/aio_agent/data/knowledgebase/
plugins/aio_agent/data/cache/
configuration/aio_agent.json5
configuration/aio_agent_lang.json5

If you are sending a customer a custom AIO build, package it as:


aio_agent/

Do not package it with a staging folder name. The plugin must still install as plugins/aio_agent because the config, dashboard, command, and handler paths expect the plugin ID aio_agent.

Troubleshooting

If an addon does not load:

Confirm the folder is under plugins/aio_agent/data/addons/.
Confirm addon.json exists and is valid JSON.
Confirm enabled is not false in addon.json or config.json5.
Confirm the entry file exists.
Check console logs for aio_agent:addons.
Run /aio reload after editing addon config, prompt files, or knowledge text.

Optional addon failures are logged and AIO Agent continues loading. Required addon failures stop AIO Agent from loading so the broken customer setup is not used silently.