Skip to main content

​
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

FieldRequiredDescription
idYesUnique plugin identifier
configSchemaYesJSON Schema for plugin config (even if empty)
nameNoDisplay name
descriptionNoShort summary
versionNoSemver version
uiHintsNoUI hints for config fields (sensitive, labels, placeholders)
kindNoPlugin kind (e.g., "memory")
channelsNoChannel IDs registered by this plugin
providersNoProvider IDs registered by this plugin
skillsNoSkill 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

HookWhenUse Case
before_agent_startBefore each agent runInject 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