This template helps you build and publish custom components for Strands Agents. Whether you're creating a new tool, model provider, or session manager, this directory gives you a starting point with the right structure and conventions.

This is the Python half of the extension-template monorepo. For the TypeScript equivalent, see ../typescript/.

Getting started

1. Create your repository

Click "Use this template" on GitHub to create your own repository. Then clone it locally and switch into this directory:

git clone https://github.com/yourusername/your-repo-name
cd your-repo-name/python

2. Run the setup script

The setup script customizes the template for your project. It renames files, updates imports, configures pyproject.toml, and removes components you don't need.

python setup_template.py

You'll be prompted for:

• Package name — A short identifier like amazon, slack, or redis. This becomes your module name (strands_amazon) and PyPI package name (strands-amazon).
• Components — Which extension points you want to include (tool, model, etc.)
• Author info — Your name, email, and GitHub username for pyproject.toml.
• Description — A one-line description of your package.

3. Install dependencies

pip install -e ".[dev]"

What's in this template

The template includes skeleton implementations for all major Strands extension points.

File	Component	Purpose
tool.py	Tool	Add capabilities to agents using the @tool decorator
model.py	Model provider	Integrate custom LLM APIs
plugin.py	Plugin	Extend agent behavior with hooks and tools in a composable package
intervention.py	Intervention	Add composable control handlers for authorization, guardrails, and steering
session_manager.py	Session manager	Persist conversations across restarts
conversation_manager.py	Conversation manager	Control context window and message history
memory_store.py	Memory store	Give agents cross-session knowledge via a search backend

The setup script will remove components you don't select, so you only keep what you need.

Implementing your components

Each file contains a minimal skeleton. Here's what to implement:

Tools

Tools let agents interact with external systems and perform actions. Implement your logic inside the decorated function and return a result dict.

• Creating custom tools — Documentation
• sleep — Simple tool with error handling
• browser — Multi-tool package example

Plugins

Plugins provide a composable way to extend agent behavior by bundling hooks and tools into a single package. Use @hook to react to agent lifecycle events and @tool to add capabilities, all auto-discovered and registered when the plugin is attached to an agent.

• Plugins — Documentation
• AgentSkills — Plugin example with hooks and tools
• Steering — Advanced plugin example

Interventions

Intervention handlers provide composable control layers for agents. Override lifecycle methods (like before_tool_call) to intercept events and return typed decisions: Proceed, Deny, Guide, Confirm, or Transform. Use them for authorization checks, guardrails, and human-in-the-loop approval.

• Interventions — Documentation
• Vended interventions — Cedar authorization, HITL, and steering examples

Model providers

Model providers connect agents to LLM APIs. Implement the stream() method to receive messages and yield streaming events.

• Custom providers — Documentation
• strands-clova — Community model provider example

Session managers

Session managers persist conversations to external storage, enabling conversations to resume after restarts or be shared across instances.

• Session management — Documentation
• File session manager — Implementation example

Conversation managers

Conversation managers control the context window and how message history grows over time. They handle trimming old messages or summarizing context to stay within model limits.

• Conversation management — Documentation
• Sliding window manager — Implementation example

Memory stores

Memory stores give agents cross-session knowledge. A MemoryManager searches one or more stores to recall facts and, for writable stores, writes new ones. Implement search() to back memory with your own store — a vector database, a managed search service, or any system that retrieves entries by relevance. For writes, implement whichever sinks fit your backend. add() for adding an extracted memory. For discrete-entry backend (e.g. a vector DB), only implement this method. add_messages() for ingesting raw conversation turns to extract server-side. Only implement this for backends that support server side extraction. Store identity and behavior (name, description, max_search_results, writable, extraction) come from config via MemoryStoreConfig, matching the SDK's own stores; extend TemplateMemoryStoreConfig with any backend-specific fields.

• Memory — Documentation
• Bedrock Knowledge Base store — Implementation example

Testing

Run all checks (format, lint, typecheck, test):

hatch run prepare

Or run them individually:

hatch run test        # Run tests
hatch run lint        # Run linter
hatch run typecheck   # Run type checker
hatch run format      # Format code

Publishing to PyPI

You can publish manually or through GitHub Actions.

Option 1: GitHub release (recommended)

The included workflow automatically publishes to PyPI when you create a GitHub release. Version is derived from the git tag automatically.

1. Configure PyPI trusted publishing first (see below)
2. Create a release on GitHub with a tag prefixed python-v, e.g. python-v0.1.0. The prefix lets the monorepo distinguish python and typescript releases; hatch-vcs strips it so the package version is just 0.1.0.
3. The workflow runs checks, builds, and publishes

To configure PyPI trusted publishing:

1. Go to PyPI → Your projects → Publishing
2. Add a new pending publisher with your GitHub repo details
3. Set environment name to pypi

Note: If you create a release without configuring trusted publishing, the workflow will fail. Set this up before your first release.

Option 2: Manual publish

hatch build
pip install twine
twine upload dist/*

Naming conventions

Follow these conventions so your package fits the Strands ecosystem:

Item	Convention	Example
PyPI package	strands-{name}	strands-amazon
Python module	strands_{name}	strands_amazon
Model class	{Name}Model	AmazonModel
Plugin class	{Name}Plugin	AmazonPlugin
Intervention class	{Name}Intervention	CedarIntervention
Session manager	{Name}SessionManager	RedisSessionManager
Conversation manager	{Name}ConversationManager	SummarizingConversationManager
Memory store	{Name}MemoryStore	RedisMemoryStore
Tool function	{descriptive_name}	search_web, send_email

Get featured

Help others discover your package by adding the strands-agents topic to your GitHub repository. This makes it easier for the community to find Strands extensions.

To add topics: go to your repo → click the ⚙️ gear next to "About" → add strands-agents and other relevant topics.

You can also submit your package to be featured on the Strands website. See Get Featured for details.

Resources

• Strands Agents documentation
• SDK Python repository
• Official tools repository
• Community packages

Security

See CONTRIBUTING for more information.

License

Apache 2.0 — see LICENSE for details.