refactor(plugins): make PluginRegistry private with init_plugin invocation

- Rename PluginRegistry to _PluginRegistry (private implementation detail)
- Store agent reference in __init__ instead of passing to add_plugin
- add_plugin now calls init_plugin synchronously
- Add add_plugin_async for async init_plugin implementations
- Remove get_plugin, has_plugin, list_plugins (not needed for now)
- Update tests for new API and sync/async behavior

Author: strands-agent

src/strands/plugins/__init__.py

@@ -5,7 +5,7 @@
 
 Example Usage:
     ```python
-    from strands.plugins import Plugin, PluginRegistry
+    from strands.plugins import Plugin
 
     class LoggingPlugin:
         name = "logging"
@@ -15,18 +15,11 @@ def init_plugin(self, agent: Agent) -> None:
 
         def on_model_call(self, event: BeforeModelCallEvent) -> None:
             print(f"Model called for {event.agent.name}")
-
-    # Use with registry
-    registry = PluginRegistry()
-    plugin = LoggingPlugin()
-    registry.add_plugin(plugin, agent)
     ```
 """
 
 from .plugin import Plugin
-from .registry import PluginRegistry
 
 __all__ = [
     "Plugin",
-    "PluginRegistry",
 ]

src/strands/plugins/registry.py

@@ -1,9 +1,10 @@
 """Plugin registry for managing plugins attached to an agent.
 
-This module provides the PluginRegistry class for tracking and managing
+This module provides the _PluginRegistry class for tracking and managing
 plugins that have been initialized with an agent instance.
 """
 
+import inspect
 import logging
 from typing import TYPE_CHECKING
 
@@ -15,15 +16,15 @@
 logger = logging.getLogger(__name__)
 
 
-class PluginRegistry:
+class _PluginRegistry:
     """Registry for managing plugins attached to an agent.
 
-    The PluginRegistry tracks plugins that have been initialized with an agent,
-    providing methods to add, retrieve, and check for plugins by name.
+    The _PluginRegistry tracks plugins that have been initialized with an agent,
+    providing methods to add plugins and invoke their initialization.
 
     Example:
         ```python
-        registry = PluginRegistry()
+        registry = _PluginRegistry(agent)
 
         class MyPlugin:
             name = "my-plugin"
@@ -32,60 +33,64 @@ def init_plugin(self, agent: Agent) -> None:
                 pass
 
         plugin = MyPlugin()
-        registry.add_plugin(plugin, agent)
-
-        # Check if plugin is registered
-        if registry.has_plugin("my-plugin"):
-            retrieved = registry.get_plugin("my-plugin")
+        registry.add_plugin(plugin)
         ```
     """
 
-    def __init__(self) -> None:
-        """Initialize an empty plugin registry."""
+    def __init__(self, agent: "Agent") -> None:
+        """Initialize a plugin registry with an agent reference.
+
+        Args:
+            agent: The agent instance that plugins will be initialized with.
+        """
+        self._agent = agent
         self._plugins: dict[str, Plugin] = {}
 
-    def add_plugin(self, plugin: Plugin, agent: "Agent") -> None:
-        """Add and initialize a plugin with the given agent.
+    def add_plugin(self, plugin: Plugin) -> None:
+        """Add and initialize a plugin with the agent.
+
+        This method registers the plugin and calls its init_plugin method
+        synchronously. For async init_plugin implementations, use add_plugin_async.
 
         Args:
             plugin: The plugin to add and initialize.
-            agent: The agent instance to initialize the plugin with.
 
         Raises:
             ValueError: If a plugin with the same name is already registered.
+            RuntimeError: If the plugin's init_plugin is async (use add_plugin_async instead).
         """
         if plugin.name in self._plugins:
             raise ValueError(f"plugin_name=<{plugin.name}> | plugin already registered")
 
-        logger.debug("plugin_name=<%s> | registering plugin", plugin.name)
-        self._plugins[plugin.name] = plugin
-
-    def get_plugin(self, name: str) -> Plugin | None:
-        """Get a plugin by name.
+        if inspect.iscoroutinefunction(plugin.init_plugin):
+            raise RuntimeError(
+                f"plugin_name=<{plugin.name}> | plugin has async init_plugin, use add_plugin_async instead"
+            )
 
-        Args:
-            name: The name of the plugin to retrieve.
+        logger.debug("plugin_name=<%s> | registering and initializing plugin", plugin.name)
+        self._plugins[plugin.name] = plugin
+        plugin.init_plugin(self._agent)
 
-        Returns:
-            The plugin if found, None otherwise.
-        """
-        return self._plugins.get(name)
+    async def add_plugin_async(self, plugin: Plugin) -> None:
+        """Add and initialize a plugin with the agent asynchronously.
 
-    def has_plugin(self, name: str) -> bool:
-        """Check if a plugin with the given name is registered.
+        This method registers the plugin and calls its init_plugin method,
+        supporting both sync and async implementations.
 
         Args:
-            name: The name of the plugin to check.
+            plugin: The plugin to add and initialize.
 
-        Returns:
-            True if the plugin is registered, False otherwise.
+        Raises:
+            ValueError: If a plugin with the same name is already registered.
         """
-        return name in self._plugins
+        if plugin.name in self._plugins:
+            raise ValueError(f"plugin_name=<{plugin.name}> | plugin already registered")
+
+        logger.debug("plugin_name=<%s> | registering and initializing plugin", plugin.name)
+        self._plugins[plugin.name] = plugin
 
-    def list_plugins(self) -> list[str]:
-        """Get a list of all registered plugin names.
+        if inspect.iscoroutinefunction(plugin.init_plugin):
+            await plugin.init_plugin(self._agent)
+        else:
+            plugin.init_plugin(self._agent)
 
-        Returns:
-            A list of plugin names in registration order.
-        """
-        return list(self._plugins.keys())

tests/strands/plugins/test_plugins.py

@@ -4,7 +4,8 @@
 
 import pytest
 
-from strands.plugins import Plugin, PluginRegistry
+from strands.plugins import Plugin
+from strands.plugins.registry import _PluginRegistry
 
 # Plugin Protocol Tests
 
@@ -118,13 +119,7 @@ def init_plugin(self, agent):
     assert plugin.name == "property-plugin"
 
 
-# PluginRegistry Tests
-
-
-@pytest.fixture
-def registry():
-    """Create a fresh PluginRegistry for each test."""
-    return PluginRegistry()
+# _PluginRegistry Tests
 
 
 @pytest.fixture
@@ -133,20 +128,30 @@ def mock_agent():
     return unittest.mock.Mock()
 
 
-def test_plugin_registry_add_plugin(registry, mock_agent):
-    """Test adding a plugin to the registry."""
+@pytest.fixture
+def registry(mock_agent):
+    """Create a fresh _PluginRegistry for each test."""
+    return _PluginRegistry(mock_agent)
+
+
+def test_plugin_registry_add_plugin_calls_init_plugin(registry, mock_agent):
+    """Test adding a plugin calls its init_plugin method."""
 
     class TestPlugin:
         name = "test-plugin"
 
+        def __init__(self):
+            self.initialized = False
+
         def init_plugin(self, agent):
-            pass
+            self.initialized = True
+            agent.plugin_initialized = True
 
     plugin = TestPlugin()
-    registry.add_plugin(plugin, mock_agent)
+    registry.add_plugin(plugin)
 
-    assert registry.has_plugin("test-plugin")
-    assert registry.get_plugin("test-plugin") is plugin
+    assert plugin.initialized
+    assert mock_agent.plugin_initialized
 
 
 def test_plugin_registry_add_duplicate_raises_error(registry, mock_agent):
@@ -161,51 +166,82 @@ def init_plugin(self, agent):
     plugin1 = TestPlugin()
     plugin2 = TestPlugin()
 
-    registry.add_plugin(plugin1, mock_agent)
+    registry.add_plugin(plugin1)
 
     with pytest.raises(ValueError, match="plugin_name=<test-plugin> | plugin already registered"):
-        registry.add_plugin(plugin2, mock_agent)
+        registry.add_plugin(plugin2)
 
 
-def test_plugin_registry_get_plugin_not_found(registry):
-    """Test getting a plugin that doesn't exist returns None."""
-    assert registry.get_plugin("nonexistent") is None
+def test_plugin_registry_add_plugin_async_raises_runtime_error(registry):
+    """Test that add_plugin raises RuntimeError for async plugins."""
 
+    class AsyncPlugin:
+        name = "async-plugin"
 
-def test_plugin_registry_has_plugin_false(registry):
-    """Test has_plugin returns False for unregistered plugins."""
-    assert not registry.has_plugin("nonexistent")
+        async def init_plugin(self, agent):
+            pass
 
+    plugin = AsyncPlugin()
 
-def test_plugin_registry_list_plugins(registry, mock_agent):
-    """Test listing all registered plugins."""
+    with pytest.raises(RuntimeError, match="use add_plugin_async instead"):
+        registry.add_plugin(plugin)
 
-    class Plugin1:
-        name = "plugin-1"
 
-        def init_plugin(self, agent):
-            pass
+@pytest.mark.asyncio
+async def test_plugin_registry_add_plugin_async_with_sync_plugin(mock_agent):
+    """Test add_plugin_async works with sync plugins."""
+    registry = _PluginRegistry(mock_agent)
 
-    class Plugin2:
-        name = "plugin-2"
+    class SyncPlugin:
+        name = "sync-plugin"
+
+        def __init__(self):
+            self.initialized = False
 
         def init_plugin(self, agent):
-            pass
+            self.initialized = True
 
-    class Plugin3:
-        name = "plugin-3"
+    plugin = SyncPlugin()
+    await registry.add_plugin_async(plugin)
 
-        def init_plugin(self, agent):
-            pass
+    assert plugin.initialized
 
-    registry.add_plugin(Plugin1(), mock_agent)
-    registry.add_plugin(Plugin2(), mock_agent)
-    registry.add_plugin(Plugin3(), mock_agent)
 
-    plugin_names = registry.list_plugins()
-    assert plugin_names == ["plugin-1", "plugin-2", "plugin-3"]
+@pytest.mark.asyncio
+async def test_plugin_registry_add_plugin_async_with_async_plugin(mock_agent):
+    """Test add_plugin_async works with async plugins."""
+    registry = _PluginRegistry(mock_agent)
+
+    class AsyncPlugin:
+        name = "async-plugin"
+
+        def __init__(self):
+            self.initialized = False
+
+        async def init_plugin(self, agent):
+            self.initialized = True
+
+    plugin = AsyncPlugin()
+    await registry.add_plugin_async(plugin)
 
+    assert plugin.initialized
+
+
+@pytest.mark.asyncio
+async def test_plugin_registry_add_plugin_async_duplicate_raises_error(mock_agent):
+    """Test that add_plugin_async raises error for duplicate plugins."""
+    registry = _PluginRegistry(mock_agent)
 
-def test_plugin_registry_list_plugins_empty(registry):
-    """Test listing plugins when registry is empty."""
-    assert registry.list_plugins() == []
+    class TestPlugin:
+        name = "test-plugin"
+
+        async def init_plugin(self, agent):
+            pass
+
+    plugin1 = TestPlugin()
+    plugin2 = TestPlugin()
+
+    await registry.add_plugin_async(plugin1)
+
+    with pytest.raises(ValueError, match="plugin_name=<test-plugin> | plugin already registered"):
+        await registry.add_plugin_async(plugin2)