Strands Template

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 repo gives you a starting point with the right structure and conventions.

Getting started

1. Create your repository

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

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

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, hooks, 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
hook_provider.py	Hooks	Extend agent behavior and react to lifecycle events
session_manager.py	Session manager	Persist conversations across restarts
conversation_manager.py	Conversation manager	Control context window and message history

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

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

Hooks

Hooks let you extend the agent loop and alter behavior during lifecycle events like invocations, tool calls, and model calls. You can observe events, modify data, or change execution flow.

• Hooks — Documentation

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

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 like v0.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
Session manager	{Name}SessionManager	RedisSessionManager
Conversation manager	{Name}ConversationManager	SummarizingConversationManager
Hooks	{Name}Hooks	TelemetryHooks, LoggingHooks
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

License

Apache 2.0 — see LICENSE for details.