feat(plugins): add plugins

src/strands/__init__.py

@@ -4,15 +4,19 @@
 from .agent.agent import Agent
 from .agent.base import AgentBase
 from .event_loop._retry import ModelRetryStrategy
+from .hooks.decorator import hook
+from .plugins.plugin import Plugin
 from .tools.decorator import tool
 from .types.tools import ToolContext
 
 __all__ = [
     "Agent",
     "AgentBase",
     "agent",
+    "hook",
     "models",
     "ModelRetryStrategy",
+    "Plugin",
     "tool",
     "ToolContext",
     "types",

src/strands/agent/agent.py

@@ -31,6 +31,7 @@
 from ..tools._tool_helpers import generate_missing_tool_result_content
 
 if TYPE_CHECKING:
+    from ..plugins.plugin import Plugin
     from ..tools import ToolProvider
 from ..handlers.callback_handler import PrintingCallbackHandler, null_callback_handler
 from ..hooks import (
@@ -129,6 +130,7 @@ def __init__(
         structured_output_prompt: str | None = None,
         tool_executor: ToolExecutor | None = None,
         retry_strategy: ModelRetryStrategy | _DefaultRetryStrategySentinel | None = _DEFAULT_RETRY_STRATEGY,
+        plugins: "list[Plugin] | None" = None,
     ):
         """Initialize the Agent with the specified configuration.
 
@@ -186,6 +188,12 @@ def __init__(
             retry_strategy: Strategy for retrying model calls on throttling or other transient errors.
                 Defaults to ModelRetryStrategy with max_attempts=6, initial_delay=4s, max_delay=240s.
                 Implement a custom HookProvider for custom retry logic, or pass None to disable retries.
+            plugins: List of Plugin instances to register with the agent.
+                Each plugin can contribute tools and hooks via ``@tool`` and ``@hook``
+                decorated methods, which are auto-discovered and registered during
+                agent initialization. An optional ``init_plugin(agent)`` callback is
+                invoked after registration for any additional setup.
+                Defaults to None.
 
         Raises:
             ValueError: If agent id contains path separators.
@@ -302,6 +310,16 @@ def __init__(
         if hooks:
             for hook in hooks:
                 self.hooks.add_hook(hook)
+
+        # Process plugins: register discovered tools, hooks, and call init_plugin
+        if plugins:
+            for plugin in plugins:
+                for plugin_tool in plugin.tools:
+                    self.tool_registry.register_tool(plugin_tool)
+                for plugin_hook in plugin.hooks:
+                    self.hooks.add_hook(plugin_hook)
+                plugin.init_plugin(self)
+
         self.hooks.invoke_callbacks(AgentInitializedEvent(agent=self))
 
     @property

src/strands/hooks/__init__.py

@@ -5,7 +5,7 @@
 built-in SDK components and user code to react to or modify agent behavior
 through strongly-typed event callbacks.
 
-Example Usage:
+Example Usage with Class-Based Hooks:
     ```python
     from strands.hooks import HookProvider, HookRegistry
     from strands.hooks.events import BeforeInvocationEvent, AfterInvocationEvent
@@ -25,10 +25,24 @@ def log_end(self, event: AfterInvocationEvent) -> None:
     agent = Agent(hooks=[LoggingHooks()])
     ```
 
-This replaces the older callback_handler approach with a more composable,
-type-safe system that supports multiple subscribers per event type.
+Example Usage with Decorator-Based Hooks:
+    ```python
+    from strands import Agent, hook
+    from strands.hooks import BeforeToolCallEvent
+
+    @hook
+    def log_tool_calls(event: BeforeToolCallEvent) -> None:
+        '''Log all tool calls before execution.'''
+        print(f"Tool: {event.tool_use}")
+
+    agent = Agent(hooks=[log_tool_calls])
+    ```
+
+This module supports both the class-based HookProvider approach and the newer
+decorator-based @hook approach for maximum flexibility.
 """
 
+from .decorator import DecoratedFunctionHook, hook
 from .events import (
     AfterInvocationEvent,
     AfterModelCallEvent,
@@ -48,6 +62,10 @@ def log_end(self, event: AfterInvocationEvent) -> None:
 from .registry import BaseHookEvent, HookCallback, HookEvent, HookProvider, HookRegistry
 
 __all__ = [
+    # Decorator
+    "hook",
+    "DecoratedFunctionHook",
+    # Events
     "AgentInitializedEvent",
     "BeforeInvocationEvent",
     "BeforeToolCallEvent",
@@ -56,12 +74,13 @@ def log_end(self, event: AfterInvocationEvent) -> None:
     "AfterModelCallEvent",
     "AfterInvocationEvent",
     "MessageAddedEvent",
+    # Registry
     "HookEvent",
     "HookProvider",
     "HookCallback",
     "HookRegistry",
-    "HookEvent",
     "BaseHookEvent",
+    # Multi-agent events
     "AfterMultiAgentInvocationEvent",
     "AfterNodeCallEvent",
     "BeforeMultiAgentInvocationEvent",