Plugins

Overview

Plugins are extensions that modify agent behavior at the runtime level. They can register new tools, inject system prompt context, intercept messages, and hook into the agent lifecycle. Plugins are the lowest-level extension mechanism in ArgentOS. For a hands-on guide to building your own plugin, see Building Plugins.

Plugin Location

Plugins are discovered from two directories:

~/.argentos/extensions/          # Global (user-level)
.argent/extensions/              # Workspace (project-level)

Each plugin is a directory containing at minimum an argent.plugin.json manifest and an entry point (index.ts or index.js):

~/.argentos/extensions/
├── response-validator/
│   ├── argent.plugin.json
│   └── index.ts
├── atera/
│   ├── argent.plugin.json
│   └── index.ts
└── canvas-docs-enforcer/
    ├── argent.plugin.json
    └── index.ts

Plugin Manifest

Every plugin has an argent.plugin.json manifest used for discovery and config validation:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string",
        "description": "API key (prefer service-keys.json)"
      }
    }
  },
  "uiHints": {
    "apiKey": { "sensitive": true, "label": "API Key" }
  }
}

Manifest Fields

Field	Required	Description
`id`	Yes	Unique plugin identifier
`configSchema`	Yes	JSON Schema for plugin config (even if empty)
`name`	No	Display name
`description`	No	Short summary
`version`	No	Semver version
`uiHints`	No	UI hints for config fields (sensitive, labels, placeholders)
`kind`	No	Plugin kind (e.g., `"memory"`)
`channels`	No	Channel IDs registered by this plugin
`providers`	No	Provider IDs registered by this plugin
`skills`	No	Skill directories to load (relative to plugin root)

Plugin Capabilities

Tool Registration

Plugins register tools programmatically in their entry point via api.registerTool():

export default function register(api: any) {
  api.registerTool({
    name: "weather_lookup",
    description: "Look up current weather for a location",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" },
      },
      required: ["city"],
    },
    async execute(_id: string, params: any) {
      const data = await fetchWeather(params.city);
      return { content: [{ type: "text", text: data }] };
    },
  });
}

Tools can be marked as optional (opt-in via allowlists):

api.registerTool({ /* ... */ }, { optional: true });

System Prompt Injection

Plugins can inject text into the agent’s system prompt via the before_agent_start hook:

api.on("before_agent_start", async (ctx: any) => {
  ctx.systemPromptSuffix = "When creating documents, always use doc_panel.";
});

Lifecycle Hooks

Hook	When	Use Case
`before_agent_start`	Before each agent run	Inject context, nudge agent for setup

Service Keys

Plugins can read API keys from ~/.argentos/service-keys.json (managed via the dashboard) rather than requiring separate configuration. See Building Plugins for the full pattern.

Plugin Allowlist

If plugins.allow[] in argent.json has entries, only listed plugins are enabled:

{
  "plugins": {
    "allow": ["atera", "canvas-docs-enforcer"],
    "entries": {
      "atera": { "enabled": true, "config": { } }
    }
  }
}

Non-bundled plugins default to enabled when the allowlist is empty.

Tool Name Conflicts

When multiple plugins register tools with the same name, the built-in tool wins. Plugin tools with conflicting names are skipped silently.

Managing Plugins

# List installed plugins
argent plugins list

# Enable/disable a plugin
argent plugins enable <name>
argent plugins disable <name>

Building Plugins — End-to-end guide with service keys, config persistence, and hooks
Marketplace — Browse and install community packages

Getting Started

Installation

Channels

Agents

Connectors

Tools

Concepts

Memory

Model Router

Overview

Plugin Location

Plugin Manifest

Manifest Fields

Plugin Capabilities

Tool Registration

System Prompt Injection

Lifecycle Hooks

Service Keys

Plugin Allowlist

Tool Name Conflicts

Managing Plugins

​Overview

​Plugin Location

​Plugin Manifest

​Manifest Fields

​Plugin Capabilities

​Tool Registration

​System Prompt Injection

​Lifecycle Hooks

​Service Keys

​Plugin Allowlist

​Tool Name Conflicts

​Managing Plugins

​Related

Overview

Plugin Location

Plugin Manifest

Manifest Fields

Plugin Capabilities

Tool Registration

System Prompt Injection

Lifecycle Hooks

Service Keys

Plugin Allowlist

Tool Name Conflicts

Managing Plugins

Related