Agent Tools & Plugins

Tools and plugins give agents the ability to take actions beyond generating text. The Plugins page in the sidebar provides full plugin management — installing, configuring, diagnosing, and updating plugins. Individual plugins are then assigned to agents from the agent profile dialog.

The Plugins Page

Open Plugins from the sidebar. The page has three tabs:

Tab	Purpose
Installed	View, search, filter, enable/disable, configure, and remove plugins
Doctor	Run diagnostics to check plugin health
Updates	Check for and install available plugin updates

The page header shows the total installed count and active count (e.g., “15 installed · 12 active”).

Plugin Types

Plugins have two scopes, shown as badges on each plugin card:

Scope	Badge	Meaning
Gateway	Default badge	Runs on every request. Infrastructure-level plugins like rate limiting, caching, and authentication.
Per-Agent	Purple badge	Assigned individually to agents. Capability plugins like memory, web search, and code execution.

Agent-Scoped Plugins

These plugins provide tools that agents use during conversations. Assign them per-agent from the profile dialog:

Plugin	Description
Memory	Persistent memory — store and recall facts across conversations
Web Search	Search the web and retrieve page content
File I/O	Read, write, and manage files in the workspace
Code Exec	Execute code in a sandboxed runtime

Gateway Plugins

These plugins run at the gateway level and apply to all requests:

Plugin	Description
Rate Limiter	Request rate limiting
Request Logger	Log incoming requests
CORS	Cross-origin resource sharing
Auth	Authentication and authorization
IP Filter	IP-based access control
Usage Quota	Usage quota enforcement
Webhook Dispatcher	Webhook event delivery
Circuit Breaker	Fault tolerance and circuit breaking
Response Cache	Response caching
Request Validator	Request validation
Compression	Response compression

Trust Levels

Each plugin has a trust level badge:

Level	Badge	Meaning
Official	Green shield	Built-in or platform-maintained
Verified	Blue shield	Reviewed and verified
Community	Amber users icon	Community-contributed
Unverified	Gray shield	New or unreviewed

Plugin Cards (Installed Tab)

Each plugin is displayed as an expandable card showing:

• Category icon with a health indicator dot (green = active, red = error, gray = inactive)
• Plugin name with trust level badge, scope badge, and update badge (if available)
• Description (one line)
• Enable/disable toggle — switch the plugin on or off globally
• Configure button (gear icon) — opens the configuration dialog (only shown if the plugin has configurable settings)
• Expand/collapse button — reveals detailed metadata

When expanded, the card shows:

• Version, Author, Source (builtin, npm, local, archive), License
• Provided Tools — tools the plugin makes available to agents
• Registered Channels — channels the plugin registers
• Slash Commands — commands the plugin provides
• Lifecycle Hooks — hooks the plugin implements
• Dependencies — other plugins this one depends on
• Install date and Last updated
• Homepage link (if available)
• Uninstall button (for non-builtin plugins)

Searching and Filtering

The Installed tab provides:

• Search — Filter plugins by name
• Category filter — Filter by category (memory, messaging, tools, security, etc.)
• Trust level filter — Filter by Official, Verified, Community, or Unverified

Installing Plugins

Click Install Plugin at the top of the Plugins page. The install dialog supports three sources:

Source	Description	Example
npm Package	Install from the npm registry	@aigentic/plugin-memory
Local Path	Install from a local directory	/path/to/plugin
Archive URL	Install from a .tar.gz archive	https://example.com/plugin.tar.gz

You can optionally provide a display name and description. After installing, a restart banner appears — click Restart Engine to activate the new plugin.

Configuring Plugins

Plugins with configurable settings show a gear icon on their card. Click it to open the configuration dialog, which dynamically renders fields based on the plugin’s config schema:

Field Type	Control
Boolean	Toggle switch
String	Text input
Number	Number input
Select	Dropdown with predefined options

Required fields are marked with a red asterisk. Changes require an engine restart to take effect.

Assigning Plugins to Agents

Per-agent plugins must be assigned to specific agents before they can use them:

1. On the Agents page, click the agent card to open the profile dialog.
2. Go to the Plugins tab.
3. Toggle individual plugins on or off for this agent.

The tab header shows the count of active plugins (e.g., “Agent Plugins (3 active)”). A link to the full Plugins page is available at the top.

Plugin Doctor (Diagnostics)

The Doctor tab runs diagnostic checks on all plugins. Click Run Doctor to start a scan. Each plugin gets a status:

Status	Icon	Meaning
OK	Green check	Plugin is healthy
Warning	Amber triangle	Plugin has a non-critical issue
Error	Red X	Plugin has a critical problem

An overall health badge appears at the top: Healthy, Degraded, or Unhealthy.

Plugin Updates

The Updates tab checks for newer versions of installed plugins. Click Check Updates to scan. Each available update shows:

• Current version and new version
• Breaking changes warning (if applicable)
• Changelog (if available)
• Update button to install the new version

When all plugins are current, the tab shows “All plugins are up to date.”

Restart Banner

When you install, uninstall, toggle, configure, or update a plugin, a banner appears at the top of the page:

Plugin configuration changed. Restart the backend to apply.

Click Restart Engine to apply changes. A progress bar shows the restart status.

Permission Model

Aigentic uses a configurable permission model for tools:

1. Per-agent configuration — Each agent has its own plugin assignments. Enabling a plugin on one agent does not affect others.
2. Runtime enforcement — Tool permissions are enforced by the Rust backend. Even if the model attempts to use a disabled tool, the request is rejected.

How Tool Invocation Works

1. The AI model decides to use a tool based on the conversation context.
2. The model generates a tool invocation request with parameters.
3. The gateway checks the request against the agent’s permissions.
4. If permitted, the request is forwarded to the tool executor.
5. The tool executes and returns its result.
6. The result is sent back to the model, which incorporates it into the response.

If the request is denied, the model receives an error message and generates a text response instead.

Audit Trail

Every tool invocation is logged to the audit log, including:

• Which agent invoked the tool
• What parameters were passed
• Whether the invocation was permitted or denied
• The result (success or failure)
• Timestamp and duration

Skills vs Plugins

Skills are a separate extension system. See Skills for details.

Aspect	Plugins	Skills
Source	Built-in or installed from npm, local path, or archive	Installed from ClawHub catalog or created with SkillForge/SkillCreator
Scope	Gateway (all requests) or Per-Agent (assigned individually)	Per-Agent (attached individually)
Examples	Memory, Web Search, Rate Limiter, CORS	Custom API integrations, workflows
Configuration	Toggle on/off, configurable settings with restart	Install, then attach to agents

Best Practices

1. Principle of least privilege — Only assign the plugins an agent actually needs. A research agent needs web search but may not need code execution.
2. Review the audit log — Periodically check the audit log to see what tools your agents are using and whether any unexpected invocations are occurring.
3. Test before connecting to channels — When adding new plugins to an agent, test them in a direct conversation before connecting the agent to external channels.
4. Run Doctor regularly — Use the Doctor tab to catch plugin health issues early.
5. Check for updates — Keep plugins up to date for bug fixes and new features.