Skip to content

Plugins

g-agent now supports runtime extension plugins via Python entry points.

What plugins can extend

  • register custom tools
  • register custom channels
  • register custom provider factories

Entry point group

Use this entry point group in your plugin package:

[project.entry-points."g_agent.plugins"]
my_plugin = "my_package.plugin:MyPlugin"

MyPlugin can be:

  • a plugin instance
  • a plugin class (no-arg constructor)
  • a factory function returning a plugin instance

Plugin base class

Use PluginBase and PluginContext from g_agent.plugins:

from g_agent.plugins import PluginBase, PluginContext


class MyPlugin(PluginBase):
    name = "my-plugin"

    def register_tools(self, registry, context: PluginContext) -> None:
        # registry.register(MyTool(...))
        pass

    def register_channels(self, channels, context: PluginContext) -> None:
        # channels["my-channel"] = MyChannel(...)
        pass

    def register_providers(self, providers, context: PluginContext) -> None:
        # providers["my-provider"] = lambda route, config: MyProvider(...)
        # providers["default"] = lambda route, config: FallbackProvider(...)
        pass

Provider factory keys:

  • exact route provider name ("anthropic", "openai", "proxy", etc.) for targeted override
  • "default" for fallback when no exact key matches

Runtime behavior

  • plugins are loaded from installed entry points (g_agent.plugins)
  • load failures are logged and skipped (non-fatal)
  • duplicate plugin names are skipped
  • invalid channel objects from plugins are rejected
  • invalid provider factories from plugins are rejected

Plugin policy in config

You can control plugin activation from ~/.g-agent/config.json:

{
  "tools": {
    "plugins": {
      "enabled": true,
      "allow": ["my-plugin"],
      "deny": ["experimental-plugin"]
    }
  }
}
  • enabled: false disables all plugins
  • allow (optional) limits to named plugins only
  • deny (optional) blocks named plugins (takes precedence)

Verification

Run gateway and confirm plugin load logs:

g-agent gateway

You should see:

  • Loaded plugin ... in logs
  • Plugins loaded: ... in CLI startup output

CLI inspection

Use plugin diagnostics directly from CLI:

g-agent plugins list
g-agent plugins doctor
g-agent plugins doctor --strict
  • list: shows discovered plugins, hooks, and policy status
  • doctor: validates policy (enabled/allow/deny) against discovered plugins