[FEATURE] Plugin Protocol Definition

[github-actions]

Overview

Create the new Plugin Protocol that will serve as the primary abstraction for high-level agent features, replacing HookProvider.

Parent Issue: #1636

---

Problem Statement

The current HookProvider naming doesn't clearly communicate its purpose as a mechanism for high-level agent features. The Plugin terminology is more intuitive and widely understood in the industry.

Proposed Solution

Introduce a new Plugin Protocol with clear semantics for extending agent functionality.

Implementation Requirements

Plugin Protocol Definition

• Location: src/strands/hooks/registry.py (alongside HookProvider)
• Properties:
  • name: str - Identifier for the plugin
• Methods:
  • init_plugin(self, agent: Agent) -> None - Initialize the plugin with an agent
  • Support both sync and async implementations

Example Protocol Shape

@runtime_checkable
class Plugin(Protocol):
    """Protocol for objects that extend agent functionality.
    
    Plugins provide a composable way to add behavior changes to agents.
    They are initialized with an agent instance and can register hooks,
    modify agent attributes, or perform other setup tasks.
    
    Example:
        class MyPlugin:
            name = "my-plugin"
            
            def init_plugin(self, agent: Agent) -> None:
                agent.add_hook(BeforeModelCallEvent, self.on_model_call)
    """
    name: str
    
    def init_plugin(self, agent: Agent) -> None | Awaitable[None]:
        """Initialize the plugin with an agent instance.
        
        Args:
            agent: The agent instance to extend.
        """
        ...

Files to Modify

• src/strands/hooks/registry.py - Add Plugin Protocol
• src/strands/hooks/__init__.py - Export Plugin
• src/strands/__init__.py - Consider exporting Plugin at top level
• tests/strands/hooks/test_registry.py - Add Plugin Protocol tests

Acceptance Criteria

• Plugin Protocol is defined with name property and init_plugin method
• Both sync and async init_plugin implementations are supported (similar to HookCallback)
• Plugin is exported from strands.hooks
• Unit tests verify Protocol behavior with both sync and async implementations
• Docstrings follow Google style with examples

Technical Notes

• Use @runtime_checkable decorator for runtime isinstance checks
• Consider using Awaitable[None] return type annotation to support both sync/async
• Plugin is intentionally separate from HookProvider (no inheritance relationship)

Dependencies

• None (this is the foundation for other plugin-related sub-issues)

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the repository structure and existing patterns. Here's what I found:

Existing Patterns in src/strands/hooks/registry.py

• HookProvider Protocol (lines 89-114): Uses @runtime_checkable, has register_hooks method with docstring examples
• HookCallback Protocol (lines 117-142): Uses None | Awaitable[None] return type to support both sync/async - this pattern should be followed for init_plugin

Testing Patterns in tests/strands/hooks/test_registry.py

• Uses pytest fixtures for registry and agent mocks
• Tests async behavior with @pytest.mark.asyncio and unittest.mock.AsyncMock
• Tests sync/async callback validation

Design Document Review

Reviewed the design document - the Plugin Protocol definition aligns with this issue's requirements.

---

Implementation Assessment

✅ Scope: Appropriate for single PR (~1-2 days work)
✅ Dependencies: None (foundation for other sub-issues)
✅ Testing: Unit tests only (per parent issue #1636)
✅ No GitHub workflow changes needed

---

Clarifying Questions

1. Docstring Example API

The proposed Protocol example shows:

def init_plugin(self, agent: Agent) -> None:
    agent.add_hook(BeforeModelCallEvent, self.on_model_call)

However, agent.add_hook() is being added in sub-issue #3 (Add add_hook Convenience Method). Should the example:

• Option A: Use the existing API agent.hooks.add_callback(BeforeModelCallEvent, self.on_model_call)
• Option B: Keep the future agent.add_hook() API (shows intended usage pattern)

2. Top-Level Export

The issue mentions "Consider exporting Plugin at top level" for src/strands/__init__.py. Should this:

• Be included in this PR?
• Be deferred to a later sub-issue?

---

Files to Modify (Confirmed)

• src/strands/hooks/registry.py - Add Plugin Protocol definition
• src/strands/hooks/__init__.py - Export Plugin
• tests/strands/hooks/test_registry.py - Add Protocol unit tests
• src/strands/__init__.py - Pending clarification on top-level export