docs: add plugins documentation by Unshure · Pull Request #573 · strands-agents/docs

Unshure · 2026-02-20T20:46:40Z

Summary

This PR adds comprehensive documentation for Plugins, a new composable mechanism for extending agent functionality in the Strands SDK.

Changes

New Documentation

docs/user-guide/concepts/plugins/index.md: Comprehensive plugin documentation covering:
- Overview of plugins and their relationship to hooks
- Basic usage with Agent(plugins=[...])
- @hook decorator for declarative hook registration with event type inference
- Union types for handling multiple event types with a single callback
- Auto-discovery of @hook and @tool decorated methods
- Creating custom plugins by extending the Plugin base class
- Manual vs declarative hook registration patterns
- Async plugin initialization
- Advanced patterns (composition, conditional registration, error handling, multi-agent)
- Best practices for naming, design, and hook registration
- Reference to the existing Steering plugin as an example
- Guidance on sharing plugins with the community

Navigation Updates

Added Plugins as a top-level section under Concepts in mkdocs.yml

Technical Notes

Plugins are Python-only; TypeScript tabs use {{ ts_not_supported_code() }} macros
Documentation references the existing Steering plugin as an example of a working plugin
Page structure is designed to accommodate additional official plugins in the future
Documents the @hook decorator feature from [FEATURE] Create @hook decorator for Plugins sdk-python#1739

Resolves #568

- Add new docs/user-guide/concepts/plugins/index.md with comprehensive plugin documentation covering overview, basic usage, creating custom plugins, async initialization, advanced patterns, and best practices - Update mkdocs.yml navigation to include Plugins under Concepts - Update docs/community/get-featured.md to add Plugins category type - Update docs/user-guide/concepts/agents/hooks.md with: - Plugin recommendation tip at the top - Simplified agent.add_hook() API with type inference documentation - HookProvider vs Plugin comparison note - Add plugin recommendation tips to guardrails.md and retry-strategies.md - Update AGENTS.md directory structure to include plugins directory Resolves #568

github-actions · 2026-02-20T20:49:49Z

docs/user-guide/concepts/plugins/index.md

+        async def init_plugin(self, agent: "Agent") -> None:
+            # Perform async setup
+            self.config = await self.load_remote_config()
+            agent.add_hook(self.handler, BeforeToolCallEvent)


Issue: BeforeToolCallEvent is referenced on line 158 but not imported in this code example.

Suggestion: Add the import statement to the example:

import asyncio from strands.plugins import Plugin from strands.hooks import BeforeToolCallEvent # Add this import

✅ This issue has been resolved. The async plugin example now properly imports BeforeToolCallEvent on line 269.

github-actions · 2026-02-20T20:49:51Z

Assessment: Request Changes

This PR adds comprehensive documentation for the Plugins feature. The documentation is well-structured with good use of diagrams, code examples, and cross-references. However, there are two issues that need attention before merging.

Review Summary

Accidental File: build_output.log (264 lines of build logs) needs to be removed
Missing Import: The async plugin example references BeforeToolCallEvent without importing it

The overall documentation quality is excellent - the plugins concept is clearly explained with practical examples and good guidance on when to use plugins vs hooks. 👍

github-actions · 2026-02-20T20:49:51Z

build_output.log

@@ -0,0 +1,264 @@
+


Issue: This file appears to be accidentally committed build output.

Suggestion: Remove this file from the PR. It contains 264 lines of build logs that shouldn't be in the repository.

⚠️ This file is still present in the PR. Please remove it before merging.

✅ Confirmed - this file has been removed in commit 246ff5f.

strands-agent · 2026-02-20T20:52:10Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-573/

Unshure · 2026-03-02T14:27:17Z

/strands can you update the docs to include the changes in this pull request: strands-agents/sdk-python#1739

@hook

Update plugins documentation to include: - @hook decorator for declarative hook registration - Event type inference from type hints - Union types for multiple event handlers - Auto-discovery of @tool decorated methods in plugins - Updated examples showing declarative approach - Guidance on when to use @hook vs manual registration - Multiple agents with same plugin instance pattern References strands-agents/sdk-python#1739

github-actions · 2026-03-04T15:21:38Z

Assessment: Request Changes

The documentation has been significantly improved with the addition of @hook decorator documentation, union types, and auto-discovery features. The previous import issue has been resolved.

Remaining Issue

build_output.log: This accidentally committed file (264 lines of build logs) still needs to be removed before merging.

Once this file is removed, the PR should be ready to merge. The documentation is comprehensive and well-organized. 👍

github-actions · 2026-03-04T19:26:23Z

Assessment: Request Changes (No changes since last review)

The build_output.log file (264 lines of build logs) still needs to be removed before this PR can be merged.

To remove it:

git rm build_output.log
git commit -m "chore: remove accidentally committed build output"
git push

The documentation content itself is ready to merge once this file is removed.

strands-agent · 2026-03-04T19:28:45Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-573/

Unshure · 2026-03-05T15:01:46Z

build_output.log

Remove this

Done - removed the file in commit 246ff5f.

Unshure · 2026-03-05T15:02:35Z

docs/user-guide/concepts/agents/hooks.md

    agent = Agent()

-    # Register individual callbacks
+    # Register individual callbacks using the simplified API


Suggested change

# Register individual callbacks using the simplified API

# Register individual callbacks

Done - simplified the comment.

Unshure · 2026-03-05T15:02:50Z

docs/user-guide/concepts/agents/hooks.md

+You can also use the `agent.hooks.add_callback()` method for explicit event type specification:
+
+=== "Python"
+
+    ```python
+    agent = Agent()
+
+    def my_callback(event: BeforeInvocationEvent) -> None:
+        print("Custom callback triggered")
+
+    agent.hooks.add_callback(BeforeInvocationEvent, my_callback)
+    ```
+
+{{ ts_not_supported_code("This syntax is not yet available in TypeScript SDK") }}
+


Lets just not mention this

Done - removed this section.

Unshure · 2026-03-05T15:03:41Z

docs/user-guide/concepts/agents/retry-strategies.md

+!!! tip "Package as a Plugin"
+    If you want to share custom retry logic with others or reuse it across projects, consider packaging it as a [Plugin](../plugins/index.md). Plugins provide a clean interface for configuration and make your extensions easier to distribute.
+


Lets remove this tip

Done - removed the tip.

Unshure · 2026-03-05T15:03:56Z

docs/user-guide/safety-security/guardrails.md

+!!! tip "Consider Creating a Plugin"
+    If you plan to reuse this guardrails pattern across multiple agents or share it with your team, consider packaging it as a [Plugin](../concepts/plugins/index.md) for easier distribution and configuration.
+


Lets remove this tip

Done - removed the tip.

Unshure · 2026-03-05T15:05:51Z

docs/user-guide/concepts/agents/hooks.md

    --8<-- "user-guide/concepts/agents/hooks.ts:hook_provider_class"
    ```

+!!! note "HookProvider vs Plugin"


Lets remove this tip, and move mention of Hook Provider to the bottom of the page. You can replace this with a section that mentions that Plugins are a great way to provide multiple hooks to an agent. You can include a short code sample, and then point to the plugin page for more info.

Done - removed the note, moved HookProvider to bottom of page, and added "Using Plugins for Multiple Hooks" section with code sample linking to plugins page.

Unshure · 2026-03-05T15:06:48Z

docs/user-guide/concepts/agents/hooks.md


 Hooks are a composable extensibility mechanism for extending agent functionality by subscribing to events throughout the agent lifecycle. The hook system enables both built-in components and user code to react to or modify agent behavior through strongly-typed event callbacks.

+!!! tip "Consider Plugins for High-Level Behavior Changes"


Lets remove this top level tip. We mention it below.

Done - removed the top-level tip.

Unshure · 2026-03-05T15:10:39Z

docs/user-guide/concepts/plugins/index.md

@@ -0,0 +1,503 @@
+# Plugins
+
+Plugins are a composable mechanism for extending agent functionality by encapsulating related hooks, configuration, and initialization logic into reusable packages. While [hooks](../agents/hooks.md) provide fine-grained control over agent lifecycle events, plugins offer a higher-level abstraction for packaging behavior changes that can be easily shared and reused.


Lets reword this to something like:
"Plugins allow you to change the typical behavior of an agent. They allow you to introduce concepts like Skills (https://agentskills.io/specification), steering, or other concepts into the agentic loop. Plugins work by taking advantage of the low-level primitives exposed by the agnet class: model, system_prompt, messages, tools, and hooks; and executing some logic to improve an agents behavior.

Done - rewrote intro to mention Skills, steering, and how plugins work with agent primitives (model, system_prompt, messages, tools, hooks).

Unshure · 2026-03-05T15:11:52Z

docs/user-guide/concepts/plugins/index.md

+
+Plugins are a composable mechanism for extending agent functionality by encapsulating related hooks, configuration, and initialization logic into reusable packages. While [hooks](../agents/hooks.md) provide fine-grained control over agent lifecycle events, plugins offer a higher-level abstraction for packaging behavior changes that can be easily shared and reused.
+
+## Overview


Lets link out to the sdk supported plugins here. Today its just steering, but more will come.

Done - added Overview section with link to Steering as the current SDK-supported plugin.

Unshure · 2026-03-05T15:14:25Z

docs/user-guide/concepts/plugins/index.md

+
+## Overview
+
+Plugins build on the hooks system to provide:


Lets create a section thats called something like "Building Plugins" that goes into the specifics of building an agent plugin. We can start with a short code example of what it looks like to add a logging plugin to an agent, then we can go step by step through how it works under the hood. This logging plugin can have two hook decorated methods, and a tool decorated method that will be attached to the agent. This can also show manual registration of these hooks and tools in the init_agent class.

Sections about saving state, and vending will also be useful.

Done - created "Building Plugins" section with step-by-step guide including:

Basic plugin structure with logging example showing @hook and @tool methods

How it works under the hood (discovery, registration, initialization)

@hook decorator details

Manual registration in init_plugin

Managing plugin state

Async initialization

Distributing plugins section

Unshure · 2026-03-05T15:14:43Z

/strands

Address review comments from Unshure: - Remove build_output.log accidentally committed file - Remove top-level plugin tip from hooks.md - Simplify hooks.md comment (remove 'simplified API') - Remove agent.hooks.add_callback() section from hooks.md - Remove plugin tips from guardrails.md and retry-strategies.md - Move HookProvider documentation to bottom of hooks.md - Add 'Using Plugins for Multiple Hooks' section to hooks.md - Rewrite plugins/index.md intro to mention Skills, steering, primitives - Add link to SDK supported plugins (Steering) in overview - Create 'Building Plugins' section with step-by-step guide - Add sections for state management and distributing plugins

strands-agent · 2026-03-05T20:45:10Z

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-573/

github-actions · 2026-03-05T20:55:28Z

Assessment: Approve ✅

All previous issues have been addressed and the author's feedback has been incorporated.

Changes Verified

✅ build_output.log removed
✅ Plugins intro rewritten with Skills, steering, and agent primitives
✅ "Building Plugins" section with step-by-step guide
✅ Overview section with SDK-supported plugins
✅ Tips removed from retry-strategies.md and guardrails.md
✅ hooks.md restructured with "Using Plugins for Multiple Hooks" section
✅ HookProvider content reorganized

The documentation is well-organized with clear examples and good coverage of the plugin system. Ready to merge! 🚀

strands-agent added 2 commits February 20, 2026 20:44

Additional changes from write operations

b86e218

Unshure temporarily deployed to auto-approve February 20, 2026 20:46 — with GitHub Actions Inactive

github-actions bot added the strands-running label Feb 20, 2026

github-actions bot reviewed Feb 20, 2026

View reviewed changes

github-actions bot removed the strands-running label Feb 20, 2026

Unshure self-assigned this Feb 26, 2026

github-actions bot added the strands-running label Mar 2, 2026

github-actions bot removed the strands-running label Mar 2, 2026

Unshure marked this pull request as ready for review March 4, 2026 15:18

Unshure temporarily deployed to auto-approve March 4, 2026 15:18 — with GitHub Actions Inactive

github-actions bot added the strands-running label Mar 4, 2026

github-actions bot removed the strands-running label Mar 4, 2026

Unshure marked this pull request as draft March 4, 2026 17:38

Unshure closed this Mar 4, 2026

Unshure reopened this Mar 4, 2026

Unshure temporarily deployed to auto-approve March 4, 2026 19:24 — with GitHub Actions Inactive

github-actions bot added the strands-running label Mar 4, 2026

github-actions bot removed the strands-running label Mar 4, 2026

Unshure commented Mar 5, 2026

View reviewed changes

github-actions bot added the strands-running label Mar 5, 2026

github-actions bot removed the strands-running label Mar 5, 2026

Unshure closed this Mar 5, 2026

Unshure reopened this Mar 5, 2026

Unshure temporarily deployed to auto-approve March 5, 2026 20:37 — with GitHub Actions Inactive

Unshure temporarily deployed to auto-approve March 5, 2026 20:39 — with GitHub Actions Inactive

github-actions bot added the strands-running label Mar 5, 2026

github-actions bot removed the strands-running label Mar 5, 2026

	# Register individual callbacks using the simplified API
	# Register individual callbacks

		!!! tip "Package as a Plugin"
		If you want to share custom retry logic with others or reuse it across projects, consider packaging it as a [Plugin](../plugins/index.md). Plugins provide a clean interface for configuration and make your extensions easier to distribute.

		!!! tip "Consider Creating a Plugin"
		If you plan to reuse this guardrails pattern across multiple agents or share it with your team, consider packaging it as a [Plugin](../concepts/plugins/index.md) for easier distribution and configuration.


		Hooks are a composable extensibility mechanism for extending agent functionality by subscribing to events throughout the agent lifecycle. The hook system enables both built-in components and user code to react to or modify agent behavior through strongly-typed event callbacks.

		!!! tip "Consider Plugins for High-Level Behavior Changes"

		@@ -0,0 +1,503 @@
		# Plugins

		Plugins are a composable mechanism for extending agent functionality by encapsulating related hooks, configuration, and initialization logic into reusable packages. While [hooks](../agents/hooks.md) provide fine-grained control over agent lifecycle events, plugins offer a higher-level abstraction for packaging behavior changes that can be easily shared and reused.


		Plugins are a composable mechanism for extending agent functionality by encapsulating related hooks, configuration, and initialization logic into reusable packages. While [hooks](../agents/hooks.md) provide fine-grained control over agent lifecycle events, plugins offer a higher-level abstraction for packaging behavior changes that can be easily shared and reused.

		## Overview

Conversation

Unshure commented Feb 20, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New Documentation

Navigation Updates

Related Documentation Updates

Technical Notes

Uh oh!

github-actions bot Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 20, 2026

Uh oh!

github-actions bot Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

strands-agent commented Feb 20, 2026

Documentation Deployment Complete

Uh oh!

Unshure commented Mar 2, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

strands-agent commented Mar 4, 2026

Documentation Deployment Complete

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Unshure commented Feb 20, 2026 •

edited by github-actions bot

Loading