Skip to content

typescript

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

typescript

README.md

Strands Agents Extension Template — TypeScript

Build and publish custom TypeScript components for Strands Agents.

Documentation ◆ TypeScript SDK ◆ Community Packages

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

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

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/typescript

2. Run the setup script

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

npm install
npm run setup

You'll be prompted for:

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

3. Install dependencies

After the setup script finishes, install peer + dev dependencies:

npm install

What's in this template

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

File Component Purpose
src/tool.ts Tool Add capabilities to agents using the tool factory
src/model.ts Model provider Integrate custom LLM APIs
src/plugin.ts Plugin Extend agent behavior with hooks and tools in a composable package
src/session-manager.ts Snapshot storage Persist conversations across restarts (a SnapshotStorage impl plugged into the SDK's SessionManager)
src/conversation-manager.ts Conversation manager Control context window and message history
src/memory-store.ts 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 callback inside src/tool.ts. Use a Zod schema for typed/validated input or a JSON schema for untyped input.

  • Custom tools — Documentation
  • See the tool factory in @strands-agents/sdk for full options.

Plugins

Plugins provide a composable way to extend agent behavior by bundling hooks and tools into a single package. Implement initAgent to register hooks and getTools to contribute tools.

  • Plugins — Documentation
  • The SDK's SessionManager and vended-plugins/skills are good worked examples.

Model providers

Model providers connect agents to LLM APIs by extending the Model base class. Implement stream() to translate between Strands stream events and your provider's wire protocol.

  • The SDK's BedrockModel (@strands-agents/sdk/models/bedrock) is the canonical reference implementation.

Session storage

Session persistence lives behind the SnapshotStorage interface — implement it to add new backends (S3, Redis, custom DB). The SDK's FileStorage is a worked example.

Conversation managers

Conversation managers control the context window and how message history grows over time. Override reduce() to mutate agent.messages in place when the context window is at risk.

  • The SDK ships SlidingWindowConversationManager and SummarizingConversationManager as references.

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. addMessages() 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, maxSearchResults, writable, extraction) come from config via MemoryStoreConfig, matching the SDK's own stores; extend TemplateMemoryStoreConfig with any backend-specific fields.

  • The SDK's BedrockKnowledgeBaseStore is a worked MemoryStore implementation.

Testing

Run all checks (format, lint, type-check, test):

npm run check

Or run them individually:

npm test            # Run tests with vitest
npm run lint        # Run ESLint
npm run type-check  # Run tsc --noEmit
npm run format      # Format with Prettier

Publishing to npm

You can publish manually or through GitHub Actions.

Option 1: GitHub release (recommended)

The included workflow automatically publishes to npm when you create a GitHub release with a tag prefixed typescript-v (e.g. typescript-v0.1.0). The prefix lets the monorepo distinguish python and typescript releases.

  1. Configure an NPM_TOKEN secret in your GitHub repository (Account Settings → Access Tokens on npm, scope: Automation).
  2. Bump the version in package.json (or use npm version) — the workflow publishes the version that's currently in package.json.
  3. Create a release on GitHub with a tag like typescript-v0.1.0.
  4. The workflow runs checks, builds, and publishes.

Option 2: Manual publish

npm run check         # format, lint, type-check, test
npm run build         # tsc -> dist/
npm publish --access public

Naming conventions

Follow these conventions so your package fits the Strands ecosystem:

Item Convention Example
npm package strands-{name} strands-amazon
Model class {Name}Model AmazonModel
Plugin class {Name}Plugin AmazonPlugin
Snapshot storage {Name}SnapshotStorage RedisSnapshotStorage
Conversation manager {Name}ConversationManager SummarizingConversationManager
Memory store {Name}MemoryStore RedisMemoryStore
Tool factory output {descriptiveName} (camelCase) searchWeb, sendEmail

Get featured

Help others discover your package by adding the strands-agents topic to your GitHub repository. You can also submit your package to be featured on the Strands website. See Get Featured for details.

Resources

License

Apache 2.0 — see LICENSE for details.