[FEATURE] Add plugins Parameter to Agent

[github-actions]

Overview

Add a new plugins parameter to the Agent class that accepts a list of Plugin instances for extending agent functionality.

Parent Issue: #1636

---

Problem Statement

Currently, high-level features are added via the hooks parameter using HookProvider. A dedicated plugins parameter provides clearer semantics for composable agent extensions.

Proposed Solution

Add plugins: list[Plugin] | None = None parameter to Agent.__init__ that initializes plugins after the agent is constructed.

---

Implementation Requirements

Based on clarification discussion and repository analysis:

Technical Approach

• Dependency: This issue requires [FEATURE] Plugin Protocol Definition #1689 (Plugin Protocol Definition) to be merged first
• No Explicit Type Checking: Do not add isinstance checks for Plugin validation - let failures occur naturally when init_plugin is called
• Async Handling: Use run_async() helper for async init_plugin methods (same pattern as existing Agent code)

Agent.init Changes

def __init__(
    self,
    # ... existing parameters ...
    plugins: list[Plugin] | None = None,
    hooks: list[HookProvider] | None = None,  # Keep for backwards compatibility
):
    # ... existing initialization ...
    
    # Register hooks (existing code)
    if hooks:
        for hook in hooks:
            self.hooks.add_hook(hook)
    
    # Initialize plugins after agent is fully constructed
    if plugins:
        for plugin in plugins:
            if inspect.iscoroutinefunction(plugin.init_plugin):
                # Handle async init_plugin
                run_async(lambda p=plugin: p.init_plugin(self))
            else:
                plugin.init_plugin(self)
    
    # Fire AgentInitializedEvent after plugins are initialized
    self.hooks.invoke_callbacks(AgentInitializedEvent(agent=self))

Plugin Initialization Order

1. Built-in components initialized (model, tools, hooks registry)
2. HookProviders registered (from hooks parameter - deprecated)
3. Plugins initialized (from plugins parameter) ← New
4. AgentInitializedEvent fired

Files to Modify

File	Changes
src/strands/agent/agent.py	Add plugins parameter, import Plugin, add initialization logic
tests/strands/agent/test_agent.py	Add unit tests for plugins parameter

Import Requirements

• Import Plugin from strands.hooks in agent.py (internal)
• Add inspect import for iscoroutinefunction check

Example Usage

from strands import Agent, Plugin

class LoggingPlugin:
    name = "logging"
    
    def init_plugin(self, agent):
        agent.add_hook(lambda e: print("Model call starting"), BeforeModelCallEvent)

class SkillsPlugin:
    name = "skills"
    
    async def init_plugin(self, agent):
        # Async initialization supported
        agent.add_hook(self.inject_skills, BeforeModelCallEvent)
    
    def inject_skills(self, event):
        pass

# Clean, intuitive API
agent = Agent(
    plugins=[
        LoggingPlugin(),
        SkillsPlugin(),
    ]
)

---

Acceptance Criteria

• plugins parameter added to Agent.__init__ with type list[Plugin] | None = None
• Plugins are initialized with the agent instance after construction
• Both sync and async init_plugin methods are handled correctly using run_async()
• Plugin initialization happens after HookProvider registration and before AgentInitializedEvent is fired
• Unit tests cover:
  • Plugin initialization with sync init_plugin
  • Plugin initialization with async init_plugin
  • Multiple plugins in order
  • Empty/None plugins parameter
• Docstring for plugins parameter added to Agent.__init__
• plugins parameter documented in Args section

---

Dependencies

• Blocked by: [FEATURE] Plugin Protocol Definition #1689 (Plugin Protocol Definition) - must be merged first

Technical Notes

• Follow existing patterns in Agent.__init__ for the hooks parameter
• No runtime type validation needed - let duck typing handle invalid plugins
• Use inspect.iscoroutinefunction() to detect async init_plugin methods
• The run_async() helper is already imported in agent.py

Design References

• Design Document
• Parent Issue: [FEATURE] Plugins - Expose High-level functionality on Agents #1636

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the repository structure and the related issues to understand the implementation context.

Current Architecture

• Agent.init (lines 112-314): Currently accepts hooks: list[HookProvider] | None parameter
• Hooks System: Uses HookRegistry for callback management; HookProvider is a Protocol
• Async Handling: Uses run_async() helper for executing async code from sync contexts (e.g., __init__)
• AgentInitializedEvent: Must be invoked with sync callbacks only (enforced at line 209-210 of registry.py)

Related Issues

• [FEATURE] Plugin Protocol Definition #1689 (Plugin Protocol Definition): Defines the Plugin Protocol - currently OPEN and listed as a dependency
• [FEATURE] Plugins - Expose High-level functionality on Agents #1636 (Parent Epic): Defines overall plugin system design and technical decisions

Implementation Path

Based on the issue specification:

1. Add plugins: list[Plugin] | None = None parameter to Agent.__init__
2. Initialize plugins after agent construction, before AgentInitializedEvent
3. Support both sync and async init_plugin methods using run_async()

Files to Modify

File	Purpose
src/strands/agent/agent.py	Add plugins parameter and initialization logic
tests/strands/agent/test_agent.py	Unit tests for plugins parameter

---

Clarifying Questions

1. Dependency Strategy

This issue depends on #1689 (Plugin Protocol Definition) which is still open. Should this issue:

• Option A: Be implemented in the same PR as [FEATURE] Plugin Protocol Definition #1689 (combined implementation)
• Option B: Wait for [FEATURE] Plugin Protocol Definition #1689 to be merged first (sequential implementation)

The combined approach could simplify testing since we'd have the actual Protocol available.

2. Error Handling for Invalid Plugins

How should the agent handle objects in the plugins list that don't conform to the Plugin Protocol?

• Option A: Raise TypeError at initialization with a clear error message
• Option B: Use isinstance() check (since Protocol is @runtime_checkable) and skip invalid items with a warning
• Option C: Let it fail naturally when init_plugin is called

Recommendation: Option A provides the best developer experience with clear feedback.

3. Import Location Consistency

The parent issue shows importing Plugin from strands.hooks. Should the example usage in this issue's description be updated to match?

# Current in issue:
from strands.hooks import Plugin

# Should also work (per #1689):
from strands import Plugin

---

Scope Assessment

This task appears appropriately scoped for a single PR:

• ✅ Single parameter addition
• ✅ Straightforward initialization loop (following existing hooks pattern)
• ✅ Clear acceptance criteria
• ✅ Unit tests only (per parent issue decisions)
• ✅ No GitHub workflow changes needed

Estimated effort: 1-2 days implementation + testing

[Unshure]

/strands

1. B, we will just refine the requirements here
2. Option C, we dont need to explicitly check the type of typed inputs
3. only use from strands import Plugin

[github-actions]

Task Refinement Complete

Summary

I've updated the issue description with refined implementation requirements based on our discussion.

Clarifications Incorporated

1. Dependency Strategy: Sequential implementation - this issue is blocked by [FEATURE] Plugin Protocol Definition #1689 (Plugin Protocol Definition)
2. Error Handling: No explicit type checking - let failures occur naturally via duck typing
3. Import Convention: Use from strands import Plugin in all examples

Key Implementation Details

• Add plugins: list[Plugin] | None = None parameter to Agent.__init__
• Use inspect.iscoroutinefunction() + run_async() pattern for async init_plugin support
• Initialize plugins after hooks registration, before AgentInitializedEvent
• Unit tests only (per parent issue [FEATURE] Plugins - Expose High-level functionality on Agents #1636 decisions)

Files to Modify

File	Purpose
src/strands/agent/agent.py	Add plugins parameter and initialization logic
tests/strands/agent/test_agent.py	Unit tests for plugins parameter

Estimated Effort

~1-2 days implementation + testing

---

Status: ✅ Ready for implementation (after #1689 is merged)