[DOCS] Plugin System Documentation

[github-actions]

Overview

Create comprehensive documentation for the new Plugin system and update existing Hooks documentation with deprecation notices.

Parent Issue: #1636

---

Problem Statement

The new Plugin system needs clear documentation for users to understand how to create plugins, use them with agents, and migrate from the deprecated HookProvider pattern.

Proposed Solution

Create new docs/PLUGINS.md documentation and update docs/HOOKS.md with deprecation notices.

Implementation Requirements

New File: docs/PLUGINS.md

Suggested Structure

# Plugins System

Plugins provide a mechanism for customers to apply behavior changes to an agent 
in a way that is extensible, composable, and shareable.

## Overview

### What is a Plugin?
- High-level abstraction for extending agent functionality
- Composable - multiple plugins can be applied to a single agent
- Extensible - create your own plugins
- Shareable - distribute via PyPI, GitHub, etc.

### Plugin vs Hooks
- **Hooks** (low-level): Execute code at specific lifecycle events
- **Plugins** (high-level): Encapsulate behavior changes using hooks and other primitives

## Quick Start

```python
from strands import Agent
from strands.hooks import BeforeModelCallEvent

class LoggingPlugin:
    name = "logging"
    
    def init_plugin(self, agent):
        agent.add_hook(BeforeModelCallEvent, self.log_call)
    
    def log_call(self, event):
        print(f"Model call for: {event.agent.name}")

agent = Agent(plugins=[LoggingPlugin()])

Creating Plugins

Plugin Protocol

...

Sync vs Async init_plugin

...

Using agent.add_hook()

...

Using Plugins

Single Plugin

...

Multiple Plugins

...

Plugin Ordering

(Note: Reference issue #1593 for future ordering support)

Migration from HookProvider

Before (Deprecated)

class MyFeature(HookProvider):
    def register_hooks(self, registry):
        registry.add_callback(Event, self.handler)

After

class MyFeature:
    name = "my-feature"
    
    def init_plugin(self, agent):
        agent.add_hook(Event, self.handler)

Step-by-Step Migration Guide

1. Remove HookProvider inheritance
2. Add name attribute
3. Rename register_hooks to init_plugin
4. Change parameter from registry to agent
5. Use agent.add_hook() instead of registry.add_callback()
6. Update Agent initialization from hooks= to plugins=

Examples

Logging Plugin

...

Request Tracking Plugin

...

Best Practices

• Keep plugins focused on single responsibility
• Use descriptive names
• Document plugin behavior
• Handle cleanup if needed

### Update File: docs/HOOKS.md

Add deprecation notice at the top:
```markdown
> ⚠️ **Deprecation Notice**: The `HookProvider` abstraction is deprecated in favor 
> of [Plugins](./PLUGINS.md). The underlying hooks system (events and callbacks) 
> remains unchanged. See the [migration guide](./PLUGINS.md#migration-from-hookprovider).

Update content to:

• Clarify that hooks (low-level primitive) still exist
• Explain that HookProvider abstraction is deprecated
• Link to PLUGINS.md for the new pattern

Update AGENTS.md

Update the Directory Structure section to include:

├── docs/
│   ├── HOOKS.md                          # Hooks system guide (low-level)
│   ├── PLUGINS.md                        # Plugins system guide (high-level)

Files to Create/Modify

• docs/PLUGINS.md - Create new comprehensive documentation
• docs/HOOKS.md - Update with deprecation notice and links
• AGENTS.md - Update directory structure section

Acceptance Criteria

• docs/PLUGINS.md created with comprehensive guide
• Quick start example is clear and runnable
• Migration guide covers all common patterns
• docs/HOOKS.md updated with deprecation notice
• Clear distinction between hooks (low-level) and plugins (high-level)
• AGENTS.md directory structure updated
• All code examples are correct and tested
• Documentation follows existing style conventions

Dependencies

• Should be completed before: Deprecation (1636.4) - so deprecation warning links work
• Can reference: Plugin Protocol (1636.1), plugins parameter (1636.2), add_hook (1636.3)