feat: add plugins parameter to Agent (#1734)

Co-authored-by: Strands Agent <217235299+strands-agent@users.noreply.github.com>

Author: Unshure

src/strands/agent/agent.py

@@ -46,6 +46,8 @@
 from ..interrupt import _InterruptState
 from ..models.bedrock import BedrockModel
 from ..models.model import Model
+from ..plugins import Plugin
+from ..plugins.registry import _PluginRegistry
 from ..session.session_manager import SessionManager
 from ..telemetry.metrics import EventLoopMetrics
 from ..telemetry.tracer import get_tracer, serialize
@@ -126,6 +128,7 @@ def __init__(
         name: str | None = None,
         description: str | None = None,
         state: AgentState | dict | None = None,
+        plugins: list[Plugin] | None = None,
         hooks: list[HookProvider] | None = None,
         session_manager: SessionManager | None = None,
         structured_output_prompt: str | None = None,
@@ -176,6 +179,10 @@ def __init__(
                 Defaults to None.
             state: stateful information for the agent. Can be either an AgentState object, or a json serializable dict.
                 Defaults to an empty AgentState object.
+            plugins: List of Plugin instances to extend agent functionality.
+                Plugins are initialized with the agent instance after construction and can register hooks,
+                modify agent attributes, or perform other setup tasks.
+                Defaults to None.
             hooks: hooks to be added to the agent hook registry
                 Defaults to None.
             session_manager: Manager for handling agent sessions including conversation history and state.
@@ -265,6 +272,8 @@ def __init__(
 
         self.hooks = HookRegistry()
 
+        self._plugin_registry = _PluginRegistry(self)
+
         self._interrupt_state = _InterruptState()
 
         # Initialize lock for guarding concurrent invocations
@@ -311,6 +320,11 @@ def __init__(
         if hooks:
             for hook in hooks:
                 self.hooks.add_hook(hook)
+
+        if plugins:
+            for plugin in plugins:
+                self._plugin_registry.add_and_init(plugin)
+
         self.hooks.invoke_callbacks(AgentInitializedEvent(agent=self))
 
     @property

tests/strands/agent/test_agent.py

@@ -2619,3 +2619,73 @@ def untyped_callback(event):
 
     with pytest.raises(ValueError, match="cannot infer event type"):
         agent.add_hook(untyped_callback)
+
+
+def test_agent_plugins_sync_initialization():
+    """Test that plugins with sync init_plugin are initialized correctly."""
+    plugin_mock = unittest.mock.Mock()
+    plugin_mock.name = "test-plugin"
+    plugin_mock.init_plugin = unittest.mock.Mock()
+
+    agent = Agent(
+        model=MockedModelProvider([{"role": "assistant", "content": [{"text": "response"}]}]),
+        plugins=[plugin_mock],
+    )
+
+    plugin_mock.init_plugin.assert_called_once_with(agent)
+
+
+def test_agent_plugins_async_initialization():
+    """Test that plugins with async init_plugin are initialized correctly."""
+    plugin_mock = unittest.mock.Mock()
+    plugin_mock.name = "async-plugin"
+    plugin_mock.init_plugin = unittest.mock.AsyncMock()
+
+    agent = Agent(
+        model=MockedModelProvider([{"role": "assistant", "content": [{"text": "response"}]}]),
+        plugins=[plugin_mock],
+    )
+
+    plugin_mock.init_plugin.assert_called_once_with(agent)
+
+
+def test_agent_plugins_multiple_in_order():
+    """Test that multiple plugins are initialized in order."""
+    call_order = []
+
+    plugin1 = unittest.mock.Mock()
+    plugin1.name = "plugin1"
+    plugin1.init_plugin = unittest.mock.Mock(side_effect=lambda agent: call_order.append("plugin1"))
+
+    plugin2 = unittest.mock.Mock()
+    plugin2.name = "plugin2"
+    plugin2.init_plugin = unittest.mock.Mock(side_effect=lambda agent: call_order.append("plugin2"))
+
+    Agent(
+        model=MockedModelProvider([{"role": "assistant", "content": [{"text": "response"}]}]),
+        plugins=[plugin1, plugin2],
+    )
+
+    assert call_order == ["plugin1", "plugin2"]
+
+
+def test_agent_plugins_can_register_hooks():
+    """Test that plugins can register hooks during initialization."""
+    hook_called = []
+
+    class TestPlugin:
+        name = "hook-plugin"
+
+        def init_plugin(self, agent):
+            def hook_callback(event: BeforeModelCallEvent):
+                hook_called.append(True)
+
+            agent.add_hook(hook_callback)
+
+    agent = Agent(
+        model=MockedModelProvider([{"role": "assistant", "content": [{"text": "response"}]}]),
+        plugins=[TestPlugin()],
+    )
+
+    agent("test")
+    assert len(hook_called) == 1