Development

Plugins

Plugins are the main extension model in Agent Zero. Use them to ship backend logic, frontend UI, scoped settings, and activation rules without forking core code. You can keep plugins private or share them with the community through the Plugin Index.

Plugin Overview

Agent Zero discovers plugins from directory conventions and loads user plugins before built-in plugins. This makes local customization safe while preserving core defaults.

What a Plugin Can Add

  • Backend: API handlers, tools, helpers, and lifecycle extensions
  • Frontend: plugin settings pages and WebUI extension-point content
  • Agent profiles: plugin-distributed profiles via agents/<profile>/agent.yaml
  • Scoped settings: project and agent-profile aware config loading
  • Activation controls: ON/OFF rules per scope using toggle files

Priority order: usr/plugins/ overrides plugins/ when plugin folder names collide.

Manifest: plugin.yaml

Every plugin must include a YAML manifest. JSON manifests are legacy and should be migrated. 

title: My Plugin
description: What this plugin does.
version: 1.0.0
settings_sections:
  - agent
per_project_config: false
per_agent_config: false
always_enabled: false

Key Fields

  • title: human-readable display name shown in the UI
  • description: short summary shown in the plugin list
  • version: plugin version string
  • settings_sections: where settings appear (agent, external, mcp, developer, backup)
  • per_project_config: enables project-scoped config and toggle rules
  • per_agent_config: enables agent-profile scoped config and toggle rules
  • always_enabled: forces plugin ON and disables UI toggles

Recommended Structure

usr/plugins/<plugin_name>/
├── plugin.yaml
├── default_config.yaml              # optional defaults
├── api/
├── tools/
├── helpers/
├── prompts/
├── agents/
│   └── <profile>/agent.yaml
├── extensions/
│   ├── python/<extension_point>/
│   └── webui/<extension_point>/
└── webui/
    ├── config.html                  # optional settings UI
    └── ...

Scoped Settings Resolution

Plugin settings resolve from most specific scope to least specific fallback.

  1. project/.a0proj/agents/<profile>/plugins/<name>/config.json
  2. project/.a0proj/plugins/<name>/config.json
  3. usr/agents/<profile>/plugins/<name>/config.json
  4. usr/plugins/<name>/config.json
  5. plugins/<name>/default_config.yaml

Note: save operations are scope-aware, while fallback defaults can be YAML.

Activation Model

Toggle Files

  • .toggle-1 = ON
  • .toggle-0 = OFF
  • No explicit rule = ON by default

WebUI States

  • ON/OFF: simple global state from explicit rule or default
  • Advanced: appears when project/profile-specific overrides exist
  • Switch modal: scope-aware control surface for per-scope activation

Scope sync: "Configure Plugin" in the switch modal passes the currently selected scope into settings, so activation and configuration stay aligned.

Plugin Management API

Core endpoint: POST /api/plugins

  • get_config
  • save_config
  • list_configs
  • delete_config
  • toggle_plugin

Best Practices

  • Build custom plugins in usr/plugins/, not in core plugins/
  • Keep plugin folder names stable — they are the unique plugin identifier
  • Use default_config.yaml for safe defaults and keep overrides minimal
  • Use always_enabled only for plugins that must never be disabled
  • Expose settings via webui/config.html when users need scope-level control
  • Add a README.md and LICENSE to your plugin — they're shown in the Plugin List UI

For deeper implementation details, see AGENTS.plugins.md.

Plugin Index

The Plugin Index is a community-maintained registry of Agent Zero plugins. Listing your plugin there makes it discoverable by all Agent Zero users.

Two Distinct plugin.yaml Files

There are two separate plugin.yaml schemas used at different stages — they must not be confused:

Runtime manifest — lives inside your plugin directory and drives Agent Zero behavior:

title: My Plugin
description: What this plugin does.
version: 1.0.0
settings_sections:
  - agent
per_project_config: false
per_agent_config: false

Index manifest — submitted to the a0-plugins repo for discoverability only:

title: My Plugin
description: What this plugin does.
github: https://github.com/yourname/your-plugin-repo
tags:
  - tools
  - example

Repository Structure

Community plugins should live in their own GitHub repository, with the plugin contents at the repository root. The github field in the index manifest must point to that repository. 

your-plugin-repo/       ← GitHub repository root
├── plugin.yaml         ← runtime manifest
├── default_config.yaml
├── README.md
├── LICENSE
├── api/
├── tools/
├── extensions/
└── webui/

How to Submit

  1. Create a GitHub repository with the runtime plugin.yaml at the repo root.
  2. Fork agent0ai/a0-plugins and add plugins/<your-plugin-name>/plugin.yaml (index manifest) to your fork. Optionally include a square thumbnail image (≤ 20 KB).
  3. Open a Pull Request — one PR must add exactly one new plugin folder.
  4. CI validates automatically. A maintainer reviews and merges.

For available tags, see TAGS.md in the Plugin Index repository.

Plugin Marketplace Coming Soon

A built-in Plugin Marketplace (an always-active plugin) is planned for a future release. It will allow users to browse the Plugin Index and install or update community plugins directly from the Agent Zero UI — no manual file management required.

This page will be updated once the Plugin Marketplace is released.