From 459bb0a667e45f763d980feafc4fcc8f3a3ebb24 Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Wed, 7 Jan 2026 00:17:26 -0500 Subject: [PATCH 01/11] docs: add community contributor guide and extensions docs - Add community index page with contribution router - Add contributing guides: core-sdk, documentation, feature-proposals - Add extensions docs: ecosystem overview, publishing guide, best practices - Update community-packages.md to be the catalog page --- docs/community/community-packages.md | 81 +++++----- docs/community/contributing/core-sdk.md | 95 +++++++++++ docs/community/contributing/documentation.md | 81 ++++++++++ .../contributing/feature-proposals.md | 45 ++++++ docs/community/extensions/best-practices.md | 149 ++++++++++++++++++ docs/community/extensions/index.md | 43 +++++ docs/community/extensions/publishing.md | 120 ++++++++++++++ docs/community/index.md | 38 +++++ 8 files changed, 611 insertions(+), 41 deletions(-) create mode 100644 docs/community/contributing/core-sdk.md create mode 100644 docs/community/contributing/documentation.md create mode 100644 docs/community/contributing/feature-proposals.md create mode 100644 docs/community/extensions/best-practices.md create mode 100644 docs/community/extensions/index.md create mode 100644 docs/community/extensions/publishing.md create mode 100644 docs/community/index.md diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index 2afd734c..f45e9533 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -1,60 +1,59 @@ -# Community Packages +# Community catalog -The Strands Agents SDK is built on community contributions that extend agent capabilities through custom tools and integrations. If you've built a useful extension for Strands Agents that solves a common problem or integrates with popular services, packaging it for distribution allows other developers to benefit from your work. +The Strands community has built tools and integrations for a variety of use cases. This catalog helps you discover what's available. -## Creating A Package +!!! info "Community maintained" + These packages are maintained by their authors, not the Strands team. Review packages before using them in production. Quality and support may vary. -The first step to sharing your Strands component with the community is creating a Python package. Follow the [official Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) for complete packaging guidance. The key steps are: +## Tools -- **Create a GitHub repository** - use the naming convention `strands-{thing}` for consistency with the ecosystem. -- **Add detailed documentation** - add a README with usage examples and API references. -- **Include thorough tests** - use unit tests to verify business logic and integration tests to validate the components works against one or more providers. Ensure proper code coverage. +The following tools extend Strands with integrations to popular services. -[strands-clova](https://github.com/aidendef/strands-clova) is a community package that can serve as a good example. +| Package | Description | +|---------|-------------| +| [strands-deepgram](./tools/strands-deepgram.md) | Deepgram speech-to-text | +| [strands-hubspot](./tools/strands-hubspot.md) | HubSpot CRM integration | +| [strands-teams](./tools/strands-teams.md) | Microsoft Teams | +| [strands-telegram](./tools/strands-telegram.md) | Telegram bot | +| [strands-telegram-listener](./tools/strands-telegram-listener.md) | Telegram listener | +| [UTCP](./tools/utcp.md) | Universal Tool Calling Protocol | -## Publishing to PyPI +## Model providers -Once you have a package, you can then publish to PyPI to make it consumable to others. Publishing to PyPI allows users to install your package with pip. +These packages add support for additional LLM providers. -Best practices for publishing include: +| Package | Description | +|---------|-------------| +| [Cohere](./model-providers/cohere.md) | Cohere LLM | +| [CLOVA Studio](./model-providers/clova-studio.md) | Naver CLOVA Studio | +| [Fireworks AI](./model-providers/fireworksai.md) | Fireworks AI | +| [Nebius](./model-providers/nebius-token-factory.md) | Nebius Token Factory | -- **Configure GitHub workflows** - set up CI/CD to automatically publish releases to PyPI when you create new releases. -- **Follow semantic versioning** - use semver.org conventions for version numbering to help users understand the impact of updates. +## Session managers -## Getting Featured in Documentation +These packages provide alternative session storage backends. -Once your package is published to PyPI, you can request to have it featured in the Strands Agents documentation. Featured packages should provide clear utility to the community and meet high quality standards including comprehensive documentation, thorough testing, and reliable functionality. +| Package | Description | +|---------|-------------| +| [AgentCore Memory](./session-managers/agentcore-memory.md) | Amazon AgentCore | +| [Valkey](./session-managers/strands-valkey-session-manager.md) | Valkey session manager | -Submit your package for consideration by creating an issue in the [Strands Agents documentation repository](https://github.com/strands-agents/docs/issues). Include: +## Integrations - - Package Name: the name your package name and PyPI link - - Description: a brief description of functionality including why it benefits the community. - - Usage examples: how strands customers would wire up and use the components +These packages provide integrations with external platforms. -Accepted packages will be featured in the Community Package documentation with package descriptions and installation instructions, usage examples showing integration with Strands Agents, and links to the project repository and documentation. +| Package | Description | +|---------|-------------| +| [AG-UI](./integrations/ag-ui.md) | AG-UI integration | -## Best Practices and Examples +--- -### Model Providers +## Add your package -Model providers enable integration with third-party LLM services by implementing the Strands Agents `Model` interface. Each provider should focus on a single service or platform, exposing configuration parameters through structured config objects that users can customize for their specific needs. +Built something useful? We'd love to list it here. -For detailed implementation guidance including the `ModelConfig` pattern, `stream` method requirements, and `StreamEvent` formatting, see the [Custom Model Provider documentation](../user-guide/concepts/model-providers/custom_model_provider.md). - -A good example of a community model provider is [strands-clova](https://github.com/aidendef/strands-clova). - -### Tools - -Each tool should have a clear, focused purpose following the single responsibility principle. Use descriptive naming with clear, intuitive names for tools and parameters that make their function obvious to users. Docstrings should include detailed descriptions, parameter explanations, and usage examples to help developers understand how to use your tools effectively. - -The [strands-agents-tools](https://github.com/strands-agents/tools) repository serves as an example community tools package and provides example tools to follow for other tool packages. Good example tools include: - - - [sleep](https://github.com/strands-agents/tools/blob/main/src/strands_tools/sleep.py) - includes explicit error checking with messages that guide the caller on how to correct errors - - [browser](https://github.com/strands-agents/tools/blob/main/src/strands_tools/browser/__init__.py) - detailing how to support multiple tools that share a common core. - -## Support & Resources - -Building community packages extends the Strands Agents ecosystem and helps other developers solve complex problems with AI agents. Your contributions make the entire community more capable and productive. - -If you need help or support building community packages, start a discussion in the [Strands Agents SDK repository](https://github.com/strands-agents/sdk-python/discussions). +1. Publish your package to PyPI — See our [publishing guide](./extensions/publishing.md) +2. Add the `strands-tool` topic to your GitHub repository +3. [Submit a request](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with your package name, PyPI link, description, and usage examples +We review submissions and add packages that provide clear value to the community. diff --git a/docs/community/contributing/core-sdk.md b/docs/community/contributing/core-sdk.md new file mode 100644 index 00000000..d6b2d3de --- /dev/null +++ b/docs/community/contributing/core-sdk.md @@ -0,0 +1,95 @@ +# Contributing to core SDK + +The core SDK powers every Strands agent—the agent loop, model integrations, tool execution, and streaming. When you fix a bug or improve performance here, you're helping every developer who uses Strands. + +This guide walks you through contributing to sdk-python and sdk-typescript. + +## What we accept + +We welcome contributions that improve the SDK for everyone. + +- Bug fixes with tests that verify the fix +- Performance improvements with benchmarks showing the improvement +- Documentation improvements including docstrings and examples +- Features that align with our [roadmap](https://github.com/orgs/strands-agents/projects/1) +- Small, focused changes that solve a specific problem + +## What we don't accept + +Some contributions don't fit the core SDK. Understanding this upfront saves you time. + +- Large refactors without prior discussion and approval +- Breaking changes without RFC approval +- External tools to the core tools repository — [publish your own](../extensions/publishing.md) instead +- Changes without tests, except documentation + +If you're unsure whether your contribution fits, [open a discussion](https://github.com/strands-agents/sdk-python/discussions) first. + +## Set up your development environment + +Let's get your local environment ready for development. + +=== "Python" + + First, we'll clone the repository and set up the virtual environment. + + ```bash + git clone https://github.com/strands-agents/sdk-python.git + cd sdk-python + ``` + + We use hatch for Python development. Enter the virtual environment and install pre-commit hooks. + + ```bash + hatch shell + pre-commit install -t pre-commit -t commit-msg + ``` + + Now let's verify everything works by running the tests. + + ```bash + hatch test + ``` + + You can also run linters and formatters. + + ```bash + hatch fmt --linter # Check for issues + hatch fmt --formatter # Auto-format code + ``` + +=== "TypeScript" + + First, we'll clone the repository and install dependencies. + + ```bash + git clone https://github.com/strands-agents/sdk-typescript.git + cd sdk-typescript + npm install + ``` + + Now let's verify everything works. + + ```bash + npm test + npm run lint + npm run format + ``` + +## Submit your contribution + +Once you've made your changes, here's how to submit them. + +1. **Check existing issues** to see if your bug or feature is already tracked +2. **Open an issue first** for non-trivial changes to discuss your approach +3. **Fork and create a branch** with a descriptive name like `fix/session-memory-leak` +4. **Write tests** for your changes +5. **Run formatters** before committing to ensure consistent style +6. **Use conventional commits** like `fix: resolve memory leak in session manager` +7. **Submit a pull request** referencing the issue number +8. **Respond to feedback** — we'll review within 3 days + +## Related guides + +- [Feature proposals](./feature-proposals.md) — For significant features requiring discussion +- [Design principles](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) — What guides our decisions diff --git a/docs/community/contributing/documentation.md b/docs/community/contributing/documentation.md new file mode 100644 index 00000000..6cb8e497 --- /dev/null +++ b/docs/community/contributing/documentation.md @@ -0,0 +1,81 @@ +# Contributing to Documentation + +Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. + +Documentation lives in the [docs repository](https://github.com/strands-agents/docs). + +## What we accept + +We're looking for contributions that improve the developer experience. + +| Type | Description | +|------|-------------| +| Typo fixes | Spelling, grammar, and formatting corrections | +| Clarifications | Rewording confusing sections | +| New examples | Code samples and tutorials | +| API reference | Improvements to reference documentation | +| Translations | Contact us first to coordinate | + +## Setup + +Let's get the docs running locally so you can preview your changes. + +```bash +git clone https://github.com/strands-agents/docs.git +cd docs + +pip install -r requirements.txt +mkdocs serve + +# Preview at http://localhost:8000 +``` + +## Submission process + +1. Fork the docs repository +2. Make your changes +3. Preview locally with `mkdocs serve` +4. Submit a pull request + +Small typo fixes can skip preview and go straight to PR. + +## Style guidelines + +We aim for documentation that teaches, not just describes. A reader should finish understanding the "why" before the "how." + +### Voice and tone + +| Principle | Example | +|-----------|---------| +| Use "you" for the reader | "You create an agent by..." not "An agent is created by..." | +| Use "we" collaboratively | "Let's install the SDK" not "Install the SDK" | +| Active voice, present tense | "The agent returns a response" not "A response will be returned" | +| Explain why before how | Start with the problem, then the solution | + +### Writing style + +| Do | Don't | +|----|-------| +| Keep sentences under 25 words | Write long, complex sentences | +| Use "to create an agent, call..." | Use "in order to create an agent, you should call..." | +| Include code examples | Describe without showing | +| Use tables for comparisons | Use long bullet lists | + +### Code examples + +Always test code examples before submitting. Include both Python and TypeScript when both are supported. Start with the simplest example, then add complexity. + +```python +# Start simple +from strands import Agent +agent = Agent() + +# Then show configuration +from strands import Agent +from strands.models import BedrockModel + +agent = Agent( + model=BedrockModel(model_id="anthropic.claude-3-sonnet"), + system_prompt="You are a helpful assistant." +) +``` diff --git a/docs/community/contributing/feature-proposals.md b/docs/community/contributing/feature-proposals.md new file mode 100644 index 00000000..449ff26b --- /dev/null +++ b/docs/community/contributing/feature-proposals.md @@ -0,0 +1,45 @@ +# Feature Proposals + +Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. That's why we use an RFC (Request for Comments) process for larger contributions. + +This isn't bureaucracy for its own sake—it's about making sure your work has the best chance of being merged. + +## When to use an RFC + +Not every contribution needs an RFC. Use this process for changes that have broad impact. + +| Use RFC for | Skip RFC for | +|-------------|--------------| +| New major features affecting multiple parts of the SDK | Bug fixes | +| Breaking changes to existing APIs | Small improvements | +| Architectural changes | Documentation updates | +| Large contributions (> 1 week of work) | New tools in your own repo | + +## Process + +1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/1)** — See if your idea aligns with our direction +2. **Open a GitHub Discussion** — Use the [Proposals](https://github.com/strands-agents/sdk-python/discussions/categories/proposals) category +3. **Use the template** — Describe the problem, your solution, and alternatives +4. **Gather feedback** — We'll discuss with you and the community +5. **Get approval** — Wait for maintainer approval before implementing +6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) + +## Proposal template + +When you open a discussion, use this structure. + +```markdown +## Problem +What problem are you trying to solve? + +## Proposed Solution +How would you solve it? + +## Alternatives Considered +What other approaches did you consider? + +## Willingness to Implement +Are you willing to implement this if approved? +``` + +This process helps us avoid situations where someone builds a feature for weeks, only to find it doesn't fit the project direction. We'd rather have that conversation early. diff --git a/docs/community/extensions/best-practices.md b/docs/community/extensions/best-practices.md new file mode 100644 index 00000000..faaec50d --- /dev/null +++ b/docs/community/extensions/best-practices.md @@ -0,0 +1,149 @@ +# Extension Best Practices + +When you build an extension, you're creating something other developers will rely on. A well-designed extension is easy to understand, predictable in behavior, and helpful when things go wrong. + +This guide covers patterns we've seen work well across the Strands ecosystem. + +## General principles + +These apply to all extension types. + +| Principle | Why it matters | +|-----------|----------------| +| Clear naming | Descriptive names help agents understand what tools do | +| Single responsibility | Each tool does one thing well | +| Detailed docstrings | Include parameter explanations and examples | +| Error handling | Clear messages guide users to solutions | +| Type hints | Better IDE support and agent understanding | + +--- + +## Tools + +Tools are functions agents can call. The `@tool` decorator handles the integration. + +The most important thing is your docstring—it's what the agent reads to understand when and how to use your tool. + +=== "Python" + + ```python + from strands import tool + + @tool + def search_database(query: str, limit: int = 10) -> list[dict]: + """ + Search the database for matching records. + + Args: + query: Search query string + limit: Maximum results to return (default: 10) + + Returns: + List of matching records + + Example: + >>> search_database("customer orders", limit=5) + [{"id": 1, "name": "Order #123"}, ...] + """ + # Implementation + return results + ``` + +=== "TypeScript" + + ```typescript + import { tool } from "@strands-agents/sdk"; + + const searchDatabase = tool({ + name: "search_database", + description: "Search the database for matching records", + parameters: { + query: { type: "string", description: "Search query string" }, + limit: { type: "number", description: "Maximum results (default: 10)" } + }, + handler: async ({ query, limit = 10 }) => { + // Implementation + return results; + } + }); + ``` + +We recommend studying these examples from the official tools repo. + +| Example | What it demonstrates | +|---------|---------------------| +| [sleep](https://github.com/strands-agents/tools/blob/main/src/strands_tools/sleep.py) | Error handling patterns | +| [browser](https://github.com/strands-agents/tools/blob/main/src/strands_tools/browser/__init__.py) | Multiple related tools | + +--- + +## Model providers + +Model providers let you integrate new LLMs with Strands. You implement the `Model` interface. + +Key requirements for a model provider. + +| Requirement | Description | +|-------------|-------------| +| `ModelConfig` pattern | Configuration via a config class | +| `stream` method | Streaming response support | +| `StreamEvent` formatting | Proper event structure | + +→ [Custom Model Provider docs](../../user-guide/concepts/model-providers/custom_model_provider.md) + +For a real-world example, see [strands-clova](https://github.com/aidendef/strands-clova). + +--- + +## Hooks + +Hooks let you inject custom logic at agent lifecycle points. Common use cases include logging, validation, and modifying tool behavior. + +| Hook point | When it runs | +|------------|--------------| +| `before_tool_call` | Before a tool executes | +| `after_tool_call` | After a tool completes | +| `on_tool_error` | When a tool raises an exception | + +```python +from strands import Agent + +def log_tool_calls(tool_name, tool_input): + print(f"Calling {tool_name} with {tool_input}") + return tool_input # Return modified input or original + +agent = Agent( + hooks={ + "before_tool_call": log_tool_calls + } +) +``` + +→ [Hooks documentation](../../user-guide/concepts/agents/hooks.md) + +--- + +## Session managers + +Session managers handle conversation persistence. By default, Strands keeps history in memory. For production, you'll want to persist sessions to a database. + +| Backend | Use case | +|---------|----------| +| Redis | Fast, ephemeral sessions | +| DynamoDB | Serverless, scalable persistence | +| Custom | Your own storage backend | + +```python +from strands import Agent +from strands_redis import RedisSessionManager + +session = RedisSessionManager( + host="localhost", + port=6379, + session_id="user-123" +) + +agent = Agent(session_manager=session) +``` + +→ [Session Management docs](../../user-guide/concepts/agents/session-management.md) diff --git a/docs/community/extensions/index.md b/docs/community/extensions/index.md new file mode 100644 index 00000000..c396bfe0 --- /dev/null +++ b/docs/community/extensions/index.md @@ -0,0 +1,43 @@ +# Extensions and ecosystem + +Developers building agents often need integrations with external services—databases, APIs, messaging platforms. Writing these integrations from scratch takes time away from building your actual application. And once you've built something useful, sharing it with others requires navigating package publishing, CI/CD setup, and documentation. + +Strands addresses this through an extensible architecture and community ecosystem. You can extend Strands with custom tools, model providers, hooks, and session managers. And we provide templates and infrastructure to make publishing your extensions as simple as possible. + +## The tiered ecosystem + +We organize extensions into three tiers based on who maintains them and what level of support you can expect. + +### Tier 1: Core + +Core extensions live in official Strands repositories like [strands-agents/tools](https://github.com/strands-agents/tools). The Strands team maintains, tests, and supports these packages. They're battle-tested and safe to use in production. + +We accept bug fixes and improvements to existing core tools. However, we don't accept new external tools to core repositories—see below for why. + +### Tier 2: Partner (coming soon) + +Partner extensions are high-quality integrations with major services, maintained by service providers or trusted partners. We highlight these in our documentation with a "Partner" label. If you maintain a service and want to provide an official Strands integration, [start a discussion](https://github.com/strands-agents/sdk-python/discussions) to explore partnership. + +### Tier 3: Community + +Community extensions are published and maintained by individual developers like you. Anyone can publish a community package—we provide templates to make it easy, and list packages in our [community catalog](../community-packages.md) for discoverability. + +This is where most contributions belong. You maintain full ownership and control over your package. + +## Why we don't accept external tools + +You might wonder why we don't just accept community tools directly into the core repository. We've thought carefully about this, and here's our reasoning. + +**Security responsibility.** When we publish code under the `strands-agents` organization, we take responsibility for its security. We need to audit the code, understand every API it integrates with, and respond to security issues promptly. We can't do this for tools that integrate with services we don't use. A recent CVE in a community-contributed tool illustrated this risk. + +**Maintenance burden.** Core packages require ongoing maintenance—testing against API changes, updating for SDK changes, fixing bugs, reviewing improvements. With a small team, we can't maintain tools for hundreds of services. You know your use case better than we do, and you can iterate faster. + +**Quality expectations.** Mixing core and community code in one repository makes it hard to set expectations. Users don't know which tools are battle-tested and which are experimental. The tiered approach makes this clear. + +## The better path + +Publishing your own package gives you ownership, speed, credit, and discoverability. You control releases and updates. You don't wait for maintainer reviews. Your name is on the package. And we list you in our community catalog. + +We provide templates and infrastructure to make publishing as easy as possible. + +→ [How to publish your extension](./publishing.md) diff --git a/docs/community/extensions/publishing.md b/docs/community/extensions/publishing.md new file mode 100644 index 00000000..2d3a6823 --- /dev/null +++ b/docs/community/extensions/publishing.md @@ -0,0 +1,120 @@ +# Publishing extensions + +You've built a useful tool or integration for Strands. Now you want to share it with others. This guide walks you through publishing your extension to PyPI so anyone can install it with `pip install`. + +We'll use our GitHub template to handle the boilerplate—package structure, CI/CD, testing setup—so you can focus on your code. + +## Before you start + +You'll need a GitHub account and a PyPI account. If you don't have a PyPI account, create one at [pypi.org/account/register](https://pypi.org/account/register/). + +## Create your package + +We provide GitHub templates with everything pre-configured. Let's start by creating your repository. + +### Step 1: Use the template + +=== "Python" + + Go to [github.com/strands-agents/strands-tool-template](https://github.com/strands-agents/strands-tool-template) and click "Use this template" to create your repository. + + Name it following the convention `strands-tool-{name}`, for example `strands-tool-slack` or `strands-tool-postgres`. + +=== "TypeScript" + + TypeScript templates are coming soon. For now, you can use the Python template as a reference for structure and CI/CD configuration. + +### Step 2: Clone and customize + +Clone your new repository and open it in your editor. + +```bash +git clone https://github.com/YOUR_USERNAME/strands-tool-example.git +cd strands-tool-example +``` + +The template includes placeholder code showing the structure. Let's look at the key files. + +### Step 3: Add your tool code + +Open `src/strands_tool_example/your_tool.py` and replace the placeholder with your implementation. + +```python +from strands import tool + +@tool +def search_database(query: str, limit: int = 10) -> list[dict]: + """ + Search the database for matching records. + + Args: + query: Search query string + limit: Maximum results to return + + Returns: + List of matching records + """ + # Your implementation here + return results +``` + +Update the package name in `pyproject.toml` to match your tool name. Change `strands-tool-example` to `strands-tool-yourname`. + +### Step 4: Write tests + +Add tests in the `tests/` directory. The template includes pytest configuration and example tests to get you started. + +```bash +# Run tests locally +hatch test +``` + +## Configure publishing + +Now we'll set up automatic publishing to PyPI when you create a release. + +### Step 1: Create a PyPI API token + +Go to [pypi.org/manage/account/token](https://pypi.org/manage/account/token/) and create a new API token. Give it a descriptive name like "strands-tool-example GitHub Actions". + +### Step 2: Add the secret to GitHub + +In your GitHub repository, go to Settings → Secrets and variables → Actions. Click "New repository secret" and add: + +- Name: `PYPI_API_TOKEN` +- Value: Your PyPI token (starts with `pypi-`) + +The template's GitHub Actions workflow will use this token to publish automatically. + +## Publish your package + +With everything configured, publishing is simple. + +### Step 1: Create a release + +Go to your repository on GitHub and click "Releases" → "Create a new release". + +Create a new tag following semantic versioning, like `v0.1.0`. Add release notes describing what your tool does. + +### Step 2: Watch it publish + +GitHub Actions automatically builds and publishes your package to PyPI. Check the Actions tab to see the workflow run. + +Once complete, anyone can install your tool: + +```bash +pip install strands-tool-yourname +``` + +And that's it! Your tool is now available to the entire Strands community 🥳 + +## Get discovered + +To help others find your tool, add the `strands-tool` topic to your GitHub repository. Go to your repository's main page, click the gear icon next to "About", and add `strands-tool` to the topics. + +You can also submit your tool to be featured in our [community catalog](../community-packages.md). Create an issue in the [docs repository](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with your package name, description, and usage examples. + +## Next steps + +- [Extension best practices](./best-practices.md) — Guidelines for building high-quality extensions +- [Community catalog](../community-packages.md) — See what others have built diff --git a/docs/community/index.md b/docs/community/index.md new file mode 100644 index 00000000..3f3fb249 --- /dev/null +++ b/docs/community/index.md @@ -0,0 +1,38 @@ +# Community + +The Strands community extends the SDK's capabilities through bug fixes, new tools, and improved documentation. Whether you're scratching your own itch or helping others, we're glad you're here. + +## Contributing + +| I want to... | Guide | +|--------------|-------| +| Fix a bug or improve the SDK | [Contributing to Core SDK](./contributing/core-sdk.md) | +| Build and publish a tool or extension | [Publishing Extensions](./extensions/publishing.md) | +| Improve documentation | [Contributing to Documentation](./contributing/documentation.md) | +| Propose a significant feature | [Feature Proposals](./contributing/feature-proposals.md) | + +## Extensions + +| Topic | Guide | +|-------|-------| +| Understanding the tiered ecosystem | [Extensions Overview](./extensions/index.md) | +| Publishing your own extension | [Publishing Guide](./extensions/publishing.md) | +| Building high-quality extensions | [Best Practices](./extensions/best-practices.md) | +| Finding community packages | [Community Catalog](./community-packages.md) | + +## Response times + +We aim to respond to contributions within these timeframes. + +| Type | Target | +|------|--------| +| First response | < 3 days | +| Follow-up responses | < 3 days between review rounds | +| Security issues | < 24 hours | + +## Quick links + +- [GitHub Discussions](https://github.com/strands-agents/sdk-python/discussions) — Ask questions, share ideas +- [Roadmap](https://github.com/orgs/strands-agents/projects/1) — See what we're working on +- [Design Principles](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) — What guides our decisions +- [Code of Conduct](https://github.com/strands-agents/.github/blob/main/CODE_OF_CONDUCT.md) From c5bc12aa768a3e184fbb89d33c62f013cbd75300 Mon Sep 17 00:00:00 2001 From: Containerized Agent Date: Wed, 7 Jan 2026 17:14:21 +0000 Subject: [PATCH 02/11] docs: enhance community docs with more context and guidance Updates documentation for comprehensive community contribution support - Add introductory context to each major section explaining purpose and navigation - Expand core-sdk.md with detailed development workflow, pre-commit hooks explanation, and quality requirements - Enhance documentation.md with comprehensive style guidelines and code example requirements - Improve feature-proposals.md with detailed RFC process timeline and template guidance - Expand extensions/index.md with characteristics of each tier and partnership process details - Enhance publishing.md with step-by-step guidance, semantic versioning examples, and discoverability tips - Improve best-practices.md with detailed tables showing why principles matter and implementation guides - Add lead-in sentences to all tables and lists throughout for better context - Include cross-references to related documentation and reference materials - Match collaborative 'we' style consistent with existing user-guide documentation --- docs/community/community-packages.md | 28 +-- docs/community/contributing/core-sdk.md | 99 +++++++---- docs/community/contributing/documentation.md | 81 ++++++--- .../contributing/feature-proposals.md | 73 ++++++-- docs/community/extensions/best-practices.md | 137 +++++++++----- docs/community/extensions/index.md | 66 ++++++- docs/community/extensions/publishing.md | 167 +++++++++++++++--- docs/community/index.md | 8 +- 8 files changed, 497 insertions(+), 162 deletions(-) diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index f45e9533..a9885cd2 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -1,13 +1,15 @@ # Community catalog -The Strands community has built tools and integrations for a variety of use cases. This catalog helps you discover what's available. +The Strands community has built tools and integrations for a variety of use cases. This catalog helps you discover what's available and find packages that solve your specific needs. + +Browse by category below to find tools, model providers, session managers, and platform integrations built by the community. !!! info "Community maintained" These packages are maintained by their authors, not the Strands team. Review packages before using them in production. Quality and support may vary. ## Tools -The following tools extend Strands with integrations to popular services. +Tools extend your agents with capabilities for specific services and platforms. Each package provides one or more tools you can add to your agents. | Package | Description | |---------|-------------| @@ -20,7 +22,7 @@ The following tools extend Strands with integrations to popular services. ## Model providers -These packages add support for additional LLM providers. +Model providers add support for additional LLM services beyond the built-in providers. Use these to integrate with specialized or regional LLM platforms. | Package | Description | |---------|-------------| @@ -31,7 +33,7 @@ These packages add support for additional LLM providers. ## Session managers -These packages provide alternative session storage backends. +Session managers provide alternative storage backends for conversation history. Use these when you need persistent, scalable, or distributed session storage. | Package | Description | |---------|-------------| @@ -40,7 +42,7 @@ These packages provide alternative session storage backends. ## Integrations -These packages provide integrations with external platforms. +Platform integrations help you connect Strands agents with external services and user interfaces. | Package | Description | |---------|-------------| @@ -50,10 +52,16 @@ These packages provide integrations with external platforms. ## Add your package -Built something useful? We'd love to list it here. +Built something useful? We'd love to list it here. Publishing your package to the catalog makes it discoverable to thousands of developers. + +**Requirements:** -1. Publish your package to PyPI — See our [publishing guide](./extensions/publishing.md) -2. Add the `strands-tool` topic to your GitHub repository -3. [Submit a request](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with your package name, PyPI link, description, and usage examples +1. **Publish your package to PyPI** — See our [publishing guide](./extensions/publishing.md) for step-by-step instructions +2. **Add the `strands-tool` topic** to your GitHub repository so developers can find you +3. **Submit a request** using our [content addition template](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with: + - Package name and PyPI link + - Clear description of what it does + - Usage examples showing basic integration + - Documentation link (README or dedicated docs) -We review submissions and add packages that provide clear value to the community. +We review submissions within 3 days and add packages that provide clear value to the community. Well-documented packages with tests and examples get priority. diff --git a/docs/community/contributing/core-sdk.md b/docs/community/contributing/core-sdk.md index d6b2d3de..07104532 100644 --- a/docs/community/contributing/core-sdk.md +++ b/docs/community/contributing/core-sdk.md @@ -2,32 +2,33 @@ The core SDK powers every Strands agent—the agent loop, model integrations, tool execution, and streaming. When you fix a bug or improve performance here, you're helping every developer who uses Strands. -This guide walks you through contributing to sdk-python and sdk-typescript. +This guide walks you through contributing to sdk-python and sdk-typescript. We'll cover what types of contributions we accept, how to set up your development environment, and how to submit your changes for review. ## What we accept -We welcome contributions that improve the SDK for everyone. +We welcome contributions that improve the SDK for everyone. Focus on changes that benefit the entire community rather than solving niche use cases. -- Bug fixes with tests that verify the fix -- Performance improvements with benchmarks showing the improvement -- Documentation improvements including docstrings and examples -- Features that align with our [roadmap](https://github.com/orgs/strands-agents/projects/1) -- Small, focused changes that solve a specific problem +- **Bug fixes with tests** that verify the fix and prevent regression +- **Performance improvements with benchmarks** showing measurable gains +- **Documentation improvements** including docstrings, code examples, and guides +- **Features that align with our [roadmap](https://github.com/orgs/strands-agents/projects/1)** and development tenets +- **Small, focused changes** that solve a specific problem clearly ## What we don't accept -Some contributions don't fit the core SDK. Understanding this upfront saves you time. +Some contributions don't fit the core SDK. Understanding this upfront saves you time and helps us maintain focus on what matters most. -- Large refactors without prior discussion and approval -- Breaking changes without RFC approval -- External tools to the core tools repository — [publish your own](../extensions/publishing.md) instead -- Changes without tests, except documentation +- **Large refactors without prior discussion** — Major architectural changes require RFC approval +- **Breaking changes without RFC approval** — We maintain backward compatibility carefully +- **External tools** — [Publish your own package](../extensions/publishing.md) instead for full ownership +- **Changes without tests** — Tests ensure quality and prevent regressions (documentation changes excepted) +- **Niche features** — Features serving narrow use cases belong in extensions -If you're unsure whether your contribution fits, [open a discussion](https://github.com/strands-agents/sdk-python/discussions) first. +If you're unsure whether your contribution fits, [open a discussion](https://github.com/strands-agents/sdk-python/discussions) first. We're happy to help you find the right path. ## Set up your development environment -Let's get your local environment ready for development. +Let's get your local environment ready for development. This process differs slightly between Python and TypeScript. === "Python" @@ -38,26 +39,35 @@ Let's get your local environment ready for development. cd sdk-python ``` - We use hatch for Python development. Enter the virtual environment and install pre-commit hooks. + We use [hatch](https://hatch.pypa.io/) for Python development. Hatch manages virtual environments, dependencies, testing, and formatting. Enter the virtual environment and install pre-commit hooks. ```bash hatch shell pre-commit install -t pre-commit -t commit-msg ``` + The pre-commit hooks automatically run code formatters, linters, tests, and commit message validation before each commit. This ensures code quality and catches issues early. + Now let's verify everything works by running the tests. ```bash - hatch test + hatch test # Run unit tests + hatch test -c # Run with coverage report ``` - You can also run linters and formatters. + You can also run linters and formatters manually. ```bash - hatch fmt --linter # Check for issues - hatch fmt --formatter # Auto-format code + hatch fmt --linter # Check for code quality issues + hatch fmt --formatter # Auto-format code with ruff ``` + **Development tips:** + + - Use `hatch run test-integ` to run integration tests with real model providers + - Run `hatch test --all` to test across Python 3.10-3.13 + - Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md) for detailed development workflow + === "TypeScript" First, we'll clone the repository and install dependencies. @@ -68,26 +78,53 @@ Let's get your local environment ready for development. npm install ``` + The TypeScript SDK uses npm for dependency management and includes automated quality checks through git hooks. + + Install the git hooks for automatic quality checks. + + ```bash + npm run prepare + ``` + Now let's verify everything works. ```bash - npm test - npm run lint - npm run format + npm test # Run unit tests + npm run test:coverage # Run with coverage (80%+ required) + npm run lint # Run ESLint + npm run format # Format code with Prettier ``` + **Development tips:** + + - Use `npm run test:integ` to run integration tests + - Run `npm run test:all` to test in both Node.js and browser environments + - Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-typescript/blob/main/CONTRIBUTING.md) for detailed requirements + ## Submit your contribution -Once you've made your changes, here's how to submit them. +Once you've made your changes, here's how to submit them for review. Following these steps helps us review your contribution quickly. + +1. **Check existing issues** to see if your bug or feature is already tracked or being worked on +2. **Open an issue first** for non-trivial changes to discuss your approach and get feedback +3. **Fork and create a branch** with a descriptive name like `fix/session-memory-leak` or `feat/add-hooks-support` +4. **Write tests** for your changes—tests are required for all code changes +5. **Run quality checks** before committing to ensure everything passes: + - Python: `hatch fmt --formatter && hatch fmt --linter && hatch test` + - TypeScript: `npm run format && npm run lint && npm test` +6. **Use [conventional commits](https://www.conventionalcommits.org/)** like `fix: resolve memory leak in session manager` or `feat: add streaming support to tools` +7. **Submit a pull request** referencing the issue number in the description +8. **Respond to feedback** — we'll review within 3 days and may request changes + +**Quality requirements:** + +- All tests must pass (unit and integration tests where applicable) +- Code coverage must meet minimums (Python: varies by module, TypeScript: 80%+) +- Linting and formatting must pass without errors +- Conventional commit format required +- PR description must explain the change clearly (see our [PR guidelines](https://github.com/strands-agents/sdk-python/blob/main/docs/PR.md)) -1. **Check existing issues** to see if your bug or feature is already tracked -2. **Open an issue first** for non-trivial changes to discuss your approach -3. **Fork and create a branch** with a descriptive name like `fix/session-memory-leak` -4. **Write tests** for your changes -5. **Run formatters** before committing to ensure consistent style -6. **Use conventional commits** like `fix: resolve memory leak in session manager` -7. **Submit a pull request** referencing the issue number -8. **Respond to feedback** — we'll review within 3 days +The pre-commit hooks help catch issues before you push, but you can also run checks manually anytime. ## Related guides diff --git a/docs/community/contributing/documentation.md b/docs/community/contributing/documentation.md index 6cb8e497..2606b137 100644 --- a/docs/community/contributing/documentation.md +++ b/docs/community/contributing/documentation.md @@ -2,73 +2,101 @@ Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. +When documentation is missing, unclear, or outdated, developers struggle. Your contributions—whether fixing a typo, clarifying a concept, or adding a new guide—directly improve the experience for thousands of developers. + Documentation lives in the [docs repository](https://github.com/strands-agents/docs). ## What we accept -We're looking for contributions that improve the developer experience. +We're looking for contributions that improve the developer experience. Documentation changes can range from small typo fixes to complete new guides. -| Type | Description | -|------|-------------| -| Typo fixes | Spelling, grammar, and formatting corrections | -| Clarifications | Rewording confusing sections | -| New examples | Code samples and tutorials | -| API reference | Improvements to reference documentation | -| Translations | Contact us first to coordinate | +| Type | Description | Examples | +|------|-------------|----------| +| Typo fixes | Spelling, grammar, and formatting corrections | Fix misspelled function names, correct punctuation | +| Clarifications | Rewording confusing sections | Simplify complex explanations, add missing context | +| New examples | Code samples and tutorials | Working code showing real-world usage | +| API reference | Improvements to reference documentation | Better parameter descriptions, return value docs | +| New guides | Complete tutorials or concept pages | Step-by-step workflows, architecture explanations | +| Translations | Contact us first to coordinate | Non-English documentation (requires coordination) | ## Setup -Let's get the docs running locally so you can preview your changes. +Let's get the docs running locally so you can preview your changes as you work. The docs are built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). ```bash +# Clone the docs repository git clone https://github.com/strands-agents/docs.git cd docs +# Install dependencies pip install -r requirements.txt + +# Start the local development server mkdocs serve # Preview at http://localhost:8000 ``` +The development server automatically reloads when you save changes, so you can see your edits immediately. + ## Submission process -1. Fork the docs repository -2. Make your changes -3. Preview locally with `mkdocs serve` -4. Submit a pull request +The submission process varies based on the size of your change. Small fixes can go straight to PR, while larger changes benefit from discussion first. + +1. **Fork the docs repository** on GitHub +2. **Create a branch** with a descriptive name like `docs/clarify-tools-usage` or `docs/fix-typo-agent-loop` +3. **Make your changes** in your favorite editor +4. **Preview locally** with `mkdocs serve` to verify formatting and links work correctly +5. **Submit a pull request** with a clear description of what you changed and why + +**For small changes** (typos, grammar fixes, minor clarifications), you can skip local preview and go straight to PR. We'll catch any issues in review. -Small typo fixes can skip preview and go straight to PR. +**For larger changes** (new guides, significant rewrites), we recommend opening a GitHub Discussion first to align on approach and scope. ## Style guidelines -We aim for documentation that teaches, not just describes. A reader should finish understanding the "why" before the "how." +We aim for documentation that teaches, not just describes. A reader should finish understanding the "why" before the "how." This section covers our voice, writing style, and code example conventions. ### Voice and tone -| Principle | Example | -|-----------|---------| -| Use "you" for the reader | "You create an agent by..." not "An agent is created by..." | -| Use "we" collaboratively | "Let's install the SDK" not "Install the SDK" | -| Active voice, present tense | "The agent returns a response" not "A response will be returned" | -| Explain why before how | Start with the problem, then the solution | +Our documentation uses a collaborative, developer-peer voice. We write as knowledgeable colleagues helping you succeed. + +| Principle | Example | Why | +|-----------|---------|-----| +| Use "you" for the reader | "You create an agent by..." not "An agent is created by..." | Direct and personal | +| Use "we" collaboratively | "Let's install the SDK" not "Install the SDK" | Creates partnership | +| Active voice, present tense | "The agent returns a response" not "A response will be returned" | Clear and immediate | +| Explain why before how | Start with the problem, then the solution | Builds understanding | ### Writing style +Keep prose tight and focused. Readers scan documentation looking for answers. + | Do | Don't | |----|-------| -| Keep sentences under 25 words | Write long, complex sentences | +| Keep sentences under 25 words | Write long, complex sentences with multiple clauses | | Use "to create an agent, call..." | Use "in order to create an agent, you should call..." | | Include code examples | Describe without showing | -| Use tables for comparisons | Use long bullet lists | +| Use tables for comparisons | Use long bullet lists for structured data | +| Add lead-in sentences before lists | Jump directly into bulleted lists | ### Code examples -Always test code examples before submitting. Include both Python and TypeScript when both are supported. Start with the simplest example, then add complexity. +Code examples are critical—they show developers exactly what to do. Always test your examples before submitting. + +**Requirements:** + +- **Test all code** — Every example must actually work +- **Include both languages** — Provide Python and TypeScript when both are supported +- **Start simple** — Show the minimal example first, then add complexity +- **Add comments** — Explain non-obvious parts +- **Use realistic names** — Avoid foo/bar, use descriptive names ```python -# Start simple +# Good: Start simple from strands import Agent agent = Agent() +agent("Hello, world!") # Then show configuration from strands import Agent @@ -78,4 +106,7 @@ agent = Agent( model=BedrockModel(model_id="anthropic.claude-3-sonnet"), system_prompt="You are a helpful assistant." ) +agent("What's the weather like?") ``` + +For more detailed style guidance, see the [complete documentation style guide](https://github.com/strands-agents/docs/blob/main/STYLE_GUIDE.md) in the docs repository. diff --git a/docs/community/contributing/feature-proposals.md b/docs/community/contributing/feature-proposals.md index 449ff26b..393d7fbd 100644 --- a/docs/community/contributing/feature-proposals.md +++ b/docs/community/contributing/feature-proposals.md @@ -2,44 +2,85 @@ Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. That's why we use an RFC (Request for Comments) process for larger contributions. -This isn't bureaucracy for its own sake—it's about making sure your work has the best chance of being merged. +This isn't bureaucracy for its own sake—it's about making sure your work has the best chance of being merged. We'd rather discuss approach early than ask you to rewrite after weeks of work. ## When to use an RFC -Not every contribution needs an RFC. Use this process for changes that have broad impact. +Not every contribution needs an RFC. Use this process for changes that have broad impact or require significant time investment. | Use RFC for | Skip RFC for | |-------------|--------------| -| New major features affecting multiple parts of the SDK | Bug fixes | -| Breaking changes to existing APIs | Small improvements | -| Architectural changes | Documentation updates | -| Large contributions (> 1 week of work) | New tools in your own repo | +| New major features affecting multiple parts of the SDK | Bug fixes with clear solutions | +| Breaking changes to existing APIs | Small improvements and enhancements | +| Architectural changes requiring design discussion | Documentation updates | +| Large contributions (> 1 week of work) | New tools in your own repository | +| Features that introduce new concepts | Performance optimizations | + +When in doubt, start with a GitHub Discussion. We'll tell you if an RFC is needed. ## Process -1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/1)** — See if your idea aligns with our direction -2. **Open a GitHub Discussion** — Use the [Proposals](https://github.com/strands-agents/sdk-python/discussions/categories/proposals) category -3. **Use the template** — Describe the problem, your solution, and alternatives -4. **Gather feedback** — We'll discuss with you and the community -5. **Get approval** — Wait for maintainer approval before implementing -6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) +The RFC process helps align on requirements, explore alternatives, and identify edge cases before implementation begins. + +1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/1)** — See if your idea aligns with our direction and isn't already planned +2. **Open a GitHub Discussion** — Use the [Proposals](https://github.com/strands-agents/sdk-python/discussions/categories/proposals) category in the appropriate repository +3. **Use the template below** — Describe the problem, your solution, and alternatives you considered +4. **Gather feedback** — We'll discuss with you and the community, asking clarifying questions +5. **Get approval** — Wait for maintainer approval before implementing—approval means we commit to reviewing and likely merging your contribution +6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) once approved +7. **Reference the RFC** — Link to the approved discussion in your pull request + +**Timeline expectations:** + +- Initial response: Within 3 days +- Discussion period: 1-2 weeks for most proposals +- Decision: We'll clearly approve or decline with reasoning ## Proposal template -When you open a discussion, use this structure. +When you open a discussion, use this structure. Clear proposals get faster, more helpful feedback. ```markdown ## Problem -What problem are you trying to solve? + +What problem are you trying to solve? Describe the pain point or limitation you're addressing. + +Be specific about: +- What task are you trying to accomplish? +- What makes it difficult or impossible today? +- Who experiences this problem? ## Proposed Solution -How would you solve it? + +How would you solve it? Describe your approach at a high level. + +Include: +- Changes to the API (with code examples) +- How it integrates with existing features +- Expected behavior and usage patterns ## Alternatives Considered -What other approaches did you consider? + +What other approaches did you consider? Why did you choose this one? + +This helps us understand your reasoning and might surface better approaches. + +## Implementation Plan (optional) + +If you have thoughts on implementation, share them. Not required, but helpful. ## Willingness to Implement + Are you willing to implement this if approved? + +Yes / No / Maybe with guidance ``` +**Tips for effective proposals:** + +- Focus on the problem first—solution comes second +- Include concrete examples showing current pain and proposed improvement +- Be open to feedback—the best solution might differ from your initial idea +- Align with our [development tenets](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) + This process helps us avoid situations where someone builds a feature for weeks, only to find it doesn't fit the project direction. We'd rather have that conversation early. diff --git a/docs/community/extensions/best-practices.md b/docs/community/extensions/best-practices.md index faaec50d..6074833c 100644 --- a/docs/community/extensions/best-practices.md +++ b/docs/community/extensions/best-practices.md @@ -2,27 +2,32 @@ When you build an extension, you're creating something other developers will rely on. A well-designed extension is easy to understand, predictable in behavior, and helpful when things go wrong. -This guide covers patterns we've seen work well across the Strands ecosystem. +This guide covers patterns we've seen work well across the Strands ecosystem. Following these practices helps your extension integrate smoothly, makes it easier for others to contribute, and reduces support burden. ## General principles -These apply to all extension types. +These principles apply to all extension types. They're the foundation of quality extensions. -| Principle | Why it matters | -|-----------|----------------| -| Clear naming | Descriptive names help agents understand what tools do | -| Single responsibility | Each tool does one thing well | -| Detailed docstrings | Include parameter explanations and examples | -| Error handling | Clear messages guide users to solutions | -| Type hints | Better IDE support and agent understanding | +| Principle | Why it matters | How to apply | +|-----------|----------------|--------------| +| Clear naming | Descriptive names help agents and developers understand what tools do | Use verb-noun pairs like `search_database`, not ambiguous names like `query` | +| Single responsibility | Each tool does one thing well | Split complex operations into multiple focused tools | +| Detailed docstrings | Agents rely on docstrings to understand when and how to use tools | Include parameter explanations, examples, and edge cases | +| Error handling | Clear messages guide users to solutions | Catch specific exceptions and provide actionable error messages | +| Type hints | Better IDE support and agent understanding | Use type annotations on all parameters and returns | ---- +**Additional guidance:** + +- **Make defaults sensible** — Choose default values that work for 80% of use cases +- **Document requirements** — Specify API keys, credentials, or dependencies upfront +- **Version your API carefully** — Breaking changes require major version bumps +- **Test edge cases** — Cover error conditions, empty inputs, and boundary values ## Tools -Tools are functions agents can call. The `@tool` decorator handles the integration. +Tools are functions agents can call to perform actions or retrieve information. The `@tool` decorator handles integration with the agent system. -The most important thing is your docstring—it's what the agent reads to understand when and how to use your tool. +**The most important thing is your docstring**—it's what the agent reads to understand when and how to use your tool. A well-written docstring dramatically improves tool usage accuracy. === "Python" @@ -68,82 +73,118 @@ The most important thing is your docstring—it's what the agent reads to unders }); ``` -We recommend studying these examples from the official tools repo. - -| Example | What it demonstrates | -|---------|---------------------| -| [sleep](https://github.com/strands-agents/tools/blob/main/src/strands_tools/sleep.py) | Error handling patterns | -| [browser](https://github.com/strands-agents/tools/blob/main/src/strands_tools/browser/__init__.py) | Multiple related tools | +We recommend studying these examples from the official tools repo. They demonstrate patterns you can apply to your own tools. ---- +| Example | What it demonstrates | Key takeaway | +|---------|---------------------|--------------| +| [sleep](https://github.com/strands-agents/tools/blob/main/src/strands_tools/sleep.py) | Error handling patterns | How to validate inputs and provide helpful error messages | +| [browser](https://github.com/strands-agents/tools/blob/main/src/strands_tools/browser/__init__.py) | Multiple related tools | Organizing related functionality into tool collections | ## Model providers -Model providers let you integrate new LLMs with Strands. You implement the `Model` interface. +Model providers let you integrate new LLMs with Strands. You implement the `Model` interface to wrap your model's API and translate between its format and Strands' standard format. + +**Key requirements for a model provider:** -Key requirements for a model provider. +| Requirement | Description | Why it matters | +|-------------|-------------|----------------| +| `ModelConfig` pattern | Configuration via a config class | Consistent configuration across all model providers | +| `stream` method | Streaming response support | Users expect real-time responses | +| `StreamEvent` formatting | Proper event structure | Ensures compatibility with Strands event loop | +| Error handling | Translate provider errors to Strands exceptions | Consistent error experience across providers | +| Type annotations | Full typing for all methods | Better IDE support and error catching | -| Requirement | Description | -|-------------|-------------| -| `ModelConfig` pattern | Configuration via a config class | -| `stream` method | Streaming response support | -| `StreamEvent` formatting | Proper event structure | +**Implementation guide:** -→ [Custom Model Provider docs](../../user-guide/concepts/model-providers/custom_model_provider.md) +1. **Create a config class** extending `ModelConfig` +2. **Implement the `Model` interface** with `generate()` and `stream()` methods +3. **Handle streaming properly** by yielding `StreamEvent` objects +4. **Test with real API calls** to verify behavior +5. **Document configuration options** including required credentials -For a real-world example, see [strands-clova](https://github.com/aidendef/strands-clova). +For detailed implementation guidance, see [Custom Model Provider documentation](../../user-guide/concepts/model-providers/custom_model_provider.md). ---- +For a real-world example, study [strands-clova](https://github.com/aidendef/strands-clova)—it shows how to properly implement the interface and handle edge cases. ## Hooks -Hooks let you inject custom logic at agent lifecycle points. Common use cases include logging, validation, and modifying tool behavior. +Hooks let you inject custom logic at agent lifecycle points. Common use cases include logging tool calls, validating inputs, modifying behavior, and collecting metrics. + +**Available hook points:** + +| Hook point | When it runs | Common uses | +|------------|--------------|-------------| +| `before_tool_call` | Before a tool executes | Logging, validation, input transformation | +| `after_tool_call` | After a tool completes | Logging results, metrics collection | +| `on_tool_error` | When a tool raises an exception | Error tracking, retry logic, fallbacks | -| Hook point | When it runs | -|------------|--------------| -| `before_tool_call` | Before a tool executes | -| `after_tool_call` | After a tool completes | -| `on_tool_error` | When a tool raises an exception | +**Implementation example:** ```python from strands import Agent def log_tool_calls(tool_name, tool_input): + """Log tool calls for debugging and auditing.""" print(f"Calling {tool_name} with {tool_input}") - return tool_input # Return modified input or original + + # You can modify the input here + # Return the (possibly modified) input + return tool_input + +def handle_tool_errors(tool_name, error): + """Handle tool errors with custom logic.""" + print(f"Tool {tool_name} failed: {error}") + + # You can implement retry logic or fallbacks here + # Raise to propagate the error, return a value to recover + raise error agent = Agent( hooks={ - "before_tool_call": log_tool_calls + "before_tool_call": log_tool_calls, + "on_tool_error": handle_tool_errors } ) ``` -→ [Hooks documentation](../../user-guide/concepts/agents/hooks.md) - ---- +For complete documentation, see [Hooks documentation](../../user-guide/concepts/agents/hooks.md). ## Session managers -Session managers handle conversation persistence. By default, Strands keeps history in memory. For production, you'll want to persist sessions to a database. +Session managers handle conversation persistence. By default, Strands keeps conversation history in memory, which works for development but doesn't persist across restarts. For production, you'll want to persist sessions to a database or cache. + +**When to build a custom session manager:** + +| Use case | Backend | Why | +|----------|---------|-----| +| Fast, ephemeral sessions | Redis, Memcached | Low latency for short-lived conversations | +| Serverless, scalable persistence | DynamoDB, Firestore | Automatic scaling and pay-per-use | +| Custom storage | Your database | Integration with existing infrastructure | +| Compliance requirements | Encrypted storage | Meet regulatory requirements | + +**Implementation requirements:** + +1. **Implement the `SessionManager` interface** with `load()`, `save()`, and `delete()` methods +2. **Handle serialization** — Convert conversation history to/from storage format +3. **Manage session IDs** — Generate unique, stable identifiers +4. **Handle errors gracefully** — Fall back to empty history on corruption +5. **Consider performance** — Use connection pooling and caching where appropriate -| Backend | Use case | -|---------|----------| -| Redis | Fast, ephemeral sessions | -| DynamoDB | Serverless, scalable persistence | -| Custom | Your own storage backend | +**Example implementation:** ```python from strands import Agent from strands_redis import RedisSessionManager +# Use a custom Redis session manager session = RedisSessionManager( host="localhost", port=6379, - session_id="user-123" + session_id="user-123", + ttl=3600 # 1 hour expiration ) agent = Agent(session_manager=session) ``` -→ [Session Management docs](../../user-guide/concepts/agents/session-management.md) +For more details, see [Session Management documentation](../../user-guide/concepts/agents/session-management.md). diff --git a/docs/community/extensions/index.md b/docs/community/extensions/index.md index c396bfe0..5cb2ef1e 100644 --- a/docs/community/extensions/index.md +++ b/docs/community/extensions/index.md @@ -4,40 +4,92 @@ Developers building agents often need integrations with external services—data Strands addresses this through an extensible architecture and community ecosystem. You can extend Strands with custom tools, model providers, hooks, and session managers. And we provide templates and infrastructure to make publishing your extensions as simple as possible. +This page explains how the Strands ecosystem works, why we organize it into tiers, and how you can contribute your own extensions. + ## The tiered ecosystem -We organize extensions into three tiers based on who maintains them and what level of support you can expect. +We organize extensions into three tiers based on who maintains them and what level of support you can expect. Understanding these tiers helps you make informed decisions about which packages to use and where your contributions belong. ### Tier 1: Core Core extensions live in official Strands repositories like [strands-agents/tools](https://github.com/strands-agents/tools). The Strands team maintains, tests, and supports these packages. They're battle-tested and safe to use in production. -We accept bug fixes and improvements to existing core tools. However, we don't accept new external tools to core repositories—see below for why. +**Characteristics:** + +- Maintained by the Strands core team +- Comprehensive test coverage and CI/CD +- Security patches and updates guaranteed +- Breaking changes follow semantic versioning +- Full integration with SDK features + +**Examples:** `strands_tools` package (calculator, file_read, shell, etc.) + +We accept bug fixes and improvements to existing core tools through pull requests. However, we don't accept new external tools to core repositories—see the section below for why. ### Tier 2: Partner (coming soon) Partner extensions are high-quality integrations with major services, maintained by service providers or trusted partners. We highlight these in our documentation with a "Partner" label. If you maintain a service and want to provide an official Strands integration, [start a discussion](https://github.com/strands-agents/sdk-python/discussions) to explore partnership. +**Characteristics:** + +- Maintained by service providers or approved partners +- Meet quality and documentation standards +- Listed in docs with "Partner" designation +- Subject to periodic review + +**Process for partnership:** + +1. Build a high-quality integration with comprehensive docs and tests +2. Publish to PyPI with established maintenance track record +3. Start a discussion to propose partnership +4. Work with us to meet partner standards +5. Get featured in docs with partner designation + ### Tier 3: Community Community extensions are published and maintained by individual developers like you. Anyone can publish a community package—we provide templates to make it easy, and list packages in our [community catalog](../community-packages.md) for discoverability. -This is where most contributions belong. You maintain full ownership and control over your package. +**Characteristics:** + +- Maintained by community members +- Variable quality and support levels +- Full ownership and control by author +- Fast iteration and updates +- Listed in community catalog + +**This is where most contributions belong.** You maintain full ownership and control over your package, iterate at your own pace, and get full credit for your work. + +To get started, see [Publishing Extensions](./publishing.md). ## Why we don't accept external tools You might wonder why we don't just accept community tools directly into the core repository. We've thought carefully about this, and here's our reasoning. -**Security responsibility.** When we publish code under the `strands-agents` organization, we take responsibility for its security. We need to audit the code, understand every API it integrates with, and respond to security issues promptly. We can't do this for tools that integrate with services we don't use. A recent CVE in a community-contributed tool illustrated this risk. +**Security responsibility.** When we publish code under the `strands-agents` organization, we take responsibility for its security. We need to audit the code, understand every API it integrates with, and respond to security issues promptly. We can't do this for tools that integrate with services we don't use or understand deeply. A recent CVE in a community-contributed tool illustrated this risk—we couldn't assess the severity or fix it quickly because we lacked expertise with that service. + +**Maintenance burden.** Core packages require ongoing maintenance—testing against API changes, updating for SDK changes, fixing bugs, reviewing improvements. With a small team, we can't maintain tools for hundreds of services. You know your use case and the service you're integrating better than we do, and you can iterate faster when you control the package. -**Maintenance burden.** Core packages require ongoing maintenance—testing against API changes, updating for SDK changes, fixing bugs, reviewing improvements. With a small team, we can't maintain tools for hundreds of services. You know your use case better than we do, and you can iterate faster. +**Quality expectations.** Mixing core and community code in one repository makes it hard to set clear expectations. Users don't know which tools are battle-tested and which are experimental. The tiered approach makes quality expectations transparent—core means Strands-maintained, community means author-maintained. -**Quality expectations.** Mixing core and community code in one repository makes it hard to set expectations. Users don't know which tools are battle-tested and which are experimental. The tiered approach makes this clear. +**Dependency management.** External tools often require service-specific dependencies. Adding these to the core package increases installation size and complexity for everyone, even users who don't need those integrations. + +**Iteration speed.** External tool updates require core SDK releases. When you own the package, you can release updates immediately when the service's API changes. ## The better path Publishing your own package gives you ownership, speed, credit, and discoverability. You control releases and updates. You don't wait for maintainer reviews. Your name is on the package. And we list you in our community catalog. -We provide templates and infrastructure to make publishing as easy as possible. +**Benefits of publishing your own extension:** + +| Benefit | Description | +|---------|-------------| +| **Ownership** | You control the roadmap, features, and release schedule | +| **Speed** | Release updates immediately without waiting for core SDK releases | +| **Credit** | Your name and contribution are front and center | +| **Learning** | Gain experience with package publishing and maintenance | +| **Discoverability** | Listed in our community catalog for thousands of developers to find | +| **Flexibility** | Experiment and iterate without core SDK constraints | + +We provide templates and infrastructure to make publishing as easy as possible. The [strands-tool-template](https://github.com/strands-agents/strands-tool-template) includes pre-configured CI/CD, testing setup, and packaging configuration—you just add your tool code. → [How to publish your extension](./publishing.md) diff --git a/docs/community/extensions/publishing.md b/docs/community/extensions/publishing.md index 2d3a6823..518c2c3f 100644 --- a/docs/community/extensions/publishing.md +++ b/docs/community/extensions/publishing.md @@ -1,24 +1,40 @@ # Publishing extensions -You've built a useful tool or integration for Strands. Now you want to share it with others. This guide walks you through publishing your extension to PyPI so anyone can install it with `pip install`. +You've built a useful tool or integration for Strands. Now you want to share it with others so they can benefit from your work. This guide walks you through publishing your extension to PyPI so anyone can install it with `pip install`. -We'll use our GitHub template to handle the boilerplate—package structure, CI/CD, testing setup—so you can focus on your code. +We'll use our GitHub template to handle the boilerplate—package structure, CI/CD, testing setup, dependency management—so you can focus on your tool code. By the end, you'll have a published package and know how to release updates. ## Before you start -You'll need a GitHub account and a PyPI account. If you don't have a PyPI account, create one at [pypi.org/account/register](https://pypi.org/account/register/). +You'll need a GitHub account and a PyPI account. Publishing to PyPI makes your package installable via `pip` and discoverable through PyPI search. + +**Prerequisites:** + +- **GitHub account** — For hosting your repository and CI/CD +- **PyPI account** — Create one at [pypi.org/account/register](https://pypi.org/account/register/) +- **Your tool code** — A working Strands tool or integration you want to share + +If you don't have a PyPI account yet, creating one takes just a minute and is completely free. ## Create your package -We provide GitHub templates with everything pre-configured. Let's start by creating your repository. +We provide GitHub templates with everything pre-configured. Let's start by creating your repository from the template. ### Step 1: Use the template +The template repository includes all the packaging boilerplate you need—no need to figure out `setup.py`, CI/CD workflows, or testing configuration. + === "Python" Go to [github.com/strands-agents/strands-tool-template](https://github.com/strands-agents/strands-tool-template) and click "Use this template" to create your repository. - Name it following the convention `strands-tool-{name}`, for example `strands-tool-slack` or `strands-tool-postgres`. + Name it following the convention `strands-tool-{name}`, for example: + + - `strands-tool-slack` for a Slack integration + - `strands-tool-postgres` for PostgreSQL tools + - `strands-tool-weather` for weather APIs + + This naming convention helps developers discover your package and understand what it does at a glance. === "TypeScript" @@ -26,18 +42,24 @@ We provide GitHub templates with everything pre-configured. Let's start by creat ### Step 2: Clone and customize -Clone your new repository and open it in your editor. +Clone your new repository and open it in your editor. We'll customize it with your tool code and package details. ```bash git clone https://github.com/YOUR_USERNAME/strands-tool-example.git cd strands-tool-example ``` -The template includes placeholder code showing the structure. Let's look at the key files. +The template includes placeholder code showing the structure. Take a moment to explore the key files: + +- `src/strands_tool_example/` — Your tool code goes here +- `tests/` — Test files for your tools +- `pyproject.toml` — Package configuration and dependencies +- `.github/workflows/` — CI/CD automation for testing and publishing +- `README.md` — Package documentation ### Step 3: Add your tool code -Open `src/strands_tool_example/your_tool.py` and replace the placeholder with your implementation. +Open `src/strands_tool_example/your_tool.py` and replace the placeholder with your implementation. Use the `@tool` decorator to define your tools. ```python from strands import tool @@ -47,60 +69,131 @@ def search_database(query: str, limit: int = 10) -> list[dict]: """ Search the database for matching records. + Use this tool when you need to find records based on a search query. + The search is case-insensitive and supports fuzzy matching. + Args: query: Search query string - limit: Maximum results to return + limit: Maximum results to return (default: 10) Returns: - List of matching records + List of matching records with id, name, and metadata + + Example: + >>> search_database("customer orders", limit=5) + [{"id": 1, "name": "Order #123", ...}, ...] """ # Your implementation here + results = perform_database_search(query, limit) return results ``` -Update the package name in `pyproject.toml` to match your tool name. Change `strands-tool-example` to `strands-tool-yourname`. +**Writing good docstrings is critical**—the docstring is what the AI agent reads to understand when and how to use your tool. Include clear descriptions, parameter explanations, and examples. + +Update the package name in `pyproject.toml` to match your tool name. Change all instances of `strands-tool-example` and `strands_tool_example` to your chosen name. ### Step 4: Write tests -Add tests in the `tests/` directory. The template includes pytest configuration and example tests to get you started. +Add tests in the `tests/` directory. The template includes pytest configuration and example tests to get you started. Good tests give users confidence in your package and help you catch bugs before they ship. + +```python +# tests/test_your_tool.py +from strands_tool_yourname import search_database + +def test_search_database_basic(): + """Test basic search functionality.""" + results = search_database("test query", limit=5) + + assert isinstance(results, list) + assert len(results) <= 5 + +def test_search_database_empty(): + """Test search with no results.""" + results = search_database("nonexistent query") + + assert results == [] +``` + +Run tests locally to verify everything works. ```bash -# Run tests locally +# Set up development environment +hatch shell + +# Run tests hatch test + +# Run with coverage +hatch test -c ``` +The template's CI/CD will automatically run these tests on every pull request and before publishing. + ## Configure publishing -Now we'll set up automatic publishing to PyPI when you create a release. +Now we'll set up automatic publishing to PyPI when you create a release. The template handles the mechanics—you just need to provide credentials. ### Step 1: Create a PyPI API token -Go to [pypi.org/manage/account/token](https://pypi.org/manage/account/token/) and create a new API token. Give it a descriptive name like "strands-tool-example GitHub Actions". +PyPI uses API tokens for secure authentication. These tokens are safer than passwords because you can scope them to specific packages and revoke them if needed. + +Go to [pypi.org/manage/account/token](https://pypi.org/manage/account/token/) and create a new API token. Give it a descriptive name like "strands-tool-example GitHub Actions" so you can identify it later. + +**Important:** Copy the token immediately—PyPI only shows it once. It starts with `pypi-`. ### Step 2: Add the secret to GitHub In your GitHub repository, go to Settings → Secrets and variables → Actions. Click "New repository secret" and add: -- Name: `PYPI_API_TOKEN` -- Value: Your PyPI token (starts with `pypi-`) +- **Name:** `PYPI_API_TOKEN` +- **Value:** Your PyPI token (the full string starting with `pypi-`) -The template's GitHub Actions workflow will use this token to publish automatically. +The template's GitHub Actions workflow is already configured to use this secret. It will automatically build and publish your package to PyPI whenever you create a release. ## Publish your package -With everything configured, publishing is simple. +With everything configured, publishing is simple. Creating a GitHub release triggers automatic publishing to PyPI. ### Step 1: Create a release Go to your repository on GitHub and click "Releases" → "Create a new release". -Create a new tag following semantic versioning, like `v0.1.0`. Add release notes describing what your tool does. +**Create a new tag** following [semantic versioning](https://semver.org/): + +- `v0.1.0` for your first release +- `v0.2.0` for new features +- `v0.1.1` for bug fixes +- `v1.0.0` when you're ready for production + +**Add release notes** describing what your tool does and any changes in this version. Good release notes help users understand what they're getting. + +**Example release notes:** + +```markdown +## Features + +- Added search_database tool for PostgreSQL integration +- Support for fuzzy search and pagination +- Configurable connection pooling + +## Installation + +pip install strands-tool-postgres + +## Usage + +from strands import Agent +from strands_tool_postgres import search_database + +agent = Agent(tools=[search_database]) +agent("Find all customers from last week") +``` ### Step 2: Watch it publish -GitHub Actions automatically builds and publishes your package to PyPI. Check the Actions tab to see the workflow run. +GitHub Actions automatically builds and publishes your package to PyPI. You can watch the progress in the Actions tab of your repository. -Once complete, anyone can install your tool: +Once complete (usually 1-2 minutes), anyone can install your tool: ```bash pip install strands-tool-yourname @@ -110,9 +203,35 @@ And that's it! Your tool is now available to the entire Strands community 🥳 ## Get discovered -To help others find your tool, add the `strands-tool` topic to your GitHub repository. Go to your repository's main page, click the gear icon next to "About", and add `strands-tool` to the topics. +To help others find your tool, take these steps to increase visibility. + +### Add GitHub topics + +Add the `strands-tool` topic to your GitHub repository. Go to your repository's main page, click the gear icon next to "About", and add `strands-tool` to the topics list. This makes your tool discoverable through GitHub topic searches. + +### Submit to the community catalog + +Submit your tool to be featured in our [community catalog](../community-packages.md). Create an issue in the [docs repository](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with: + +- Package name and PyPI link +- Clear description of what it does +- Usage examples showing basic integration +- Link to documentation + +We review submissions within 3 days. Well-documented packages with tests get priority for listing. + +### Write good documentation + +Your `README.md` is the first thing users see. Make it count. + +**Essential sections:** -You can also submit your tool to be featured in our [community catalog](../community-packages.md). Create an issue in the [docs repository](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with your package name, description, and usage examples. +- **Installation** — Simple pip install command +- **Quick start** — Minimal example showing basic usage +- **Features** — What your tool can do +- **Configuration** — Any required setup or credentials +- **Examples** — Real-world usage scenarios +- **Contributing** — How others can help improve your tool ## Next steps diff --git a/docs/community/index.md b/docs/community/index.md index 3f3fb249..583cf54d 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -2,8 +2,12 @@ The Strands community extends the SDK's capabilities through bug fixes, new tools, and improved documentation. Whether you're scratching your own itch or helping others, we're glad you're here. +Every contribution makes Strands better—from fixing a typo in the docs to building a new integration that helps thousands of developers. This section guides you through the different ways to contribute and helps you find the right path for your contribution. + ## Contributing +Start here to find the right contribution guide for your needs. Each guide walks you through the specific process, requirements, and best practices for that contribution type. + | I want to... | Guide | |--------------|-------| | Fix a bug or improve the SDK | [Contributing to Core SDK](./contributing/core-sdk.md) | @@ -13,6 +17,8 @@ The Strands community extends the SDK's capabilities through bug fixes, new tool ## Extensions +The Strands ecosystem includes three tiers of extensions—core, partner, and community. Understanding how this works helps you decide where your contribution belongs and sets the right expectations for support and maintenance. + | Topic | Guide | |-------|-------| | Understanding the tiered ecosystem | [Extensions Overview](./extensions/index.md) | @@ -22,7 +28,7 @@ The Strands community extends the SDK's capabilities through bug fixes, new tool ## Response times -We aim to respond to contributions within these timeframes. +We aim to respond to contributions within these timeframes. These are goals, not guarantees—complex contributions might take longer to review thoroughly. | Type | Target | |------|--------| From a049a8de151331128874260563d88339282976bd Mon Sep 17 00:00:00 2001 From: Containerized Agent Date: Wed, 7 Jan 2026 17:51:50 +0000 Subject: [PATCH 03/11] docs: restructure community docs based on feedback Refactor community documentation to be more action-oriented - Rename 'extensions' to 'publishing' to be more concrete and actionable - Rewrite index.md with clear 'I want to...' sections instead of tables - De-emphasize tier system - move to brief context section - Add strands.my reference to community catalog - Update all internal links from extensions/ to publishing/ - Simplify 'Why we don't accept tools' section to be more concise - Retitle files: 'Publishing your component' instead of 'extensions' - Add 'Community resources' section with catalog link --- docs/community/community-packages.md | 4 +- docs/community/contributing/core-sdk.md | 2 +- docs/community/extensions/index.md | 95 ------------------- docs/community/index.md | 37 ++++---- .../best-practices.md | 8 +- docs/community/publishing/index.md | 48 ++++++++++ .../{extensions => publishing}/publishing.md | 6 +- 7 files changed, 77 insertions(+), 123 deletions(-) delete mode 100644 docs/community/extensions/index.md rename docs/community/{extensions => publishing}/best-practices.md (95%) create mode 100644 docs/community/publishing/index.md rename docs/community/{extensions => publishing}/publishing.md (97%) diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index a9885cd2..c28d0ab2 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -2,7 +2,7 @@ The Strands community has built tools and integrations for a variety of use cases. This catalog helps you discover what's available and find packages that solve your specific needs. -Browse by category below to find tools, model providers, session managers, and platform integrations built by the community. +Browse by category below to find tools, model providers, session managers, and platform integrations built by the community. You can also browse community projects dynamically at [strands.my](https://strands.my/). !!! info "Community maintained" These packages are maintained by their authors, not the Strands team. Review packages before using them in production. Quality and support may vary. @@ -56,7 +56,7 @@ Built something useful? We'd love to list it here. Publishing your package to th **Requirements:** -1. **Publish your package to PyPI** — See our [publishing guide](./extensions/publishing.md) for step-by-step instructions +1. **Publish your package to PyPI** — See our [publishing guide](./publishing/publishing.md) for step-by-step instructions 2. **Add the `strands-tool` topic** to your GitHub repository so developers can find you 3. **Submit a request** using our [content addition template](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with: - Package name and PyPI link diff --git a/docs/community/contributing/core-sdk.md b/docs/community/contributing/core-sdk.md index 07104532..8dd96e45 100644 --- a/docs/community/contributing/core-sdk.md +++ b/docs/community/contributing/core-sdk.md @@ -20,7 +20,7 @@ Some contributions don't fit the core SDK. Understanding this upfront saves you - **Large refactors without prior discussion** — Major architectural changes require RFC approval - **Breaking changes without RFC approval** — We maintain backward compatibility carefully -- **External tools** — [Publish your own package](../extensions/publishing.md) instead for full ownership +- **External tools** — [Publish your own package](../publishing/publishing.md) instead for full ownership - **Changes without tests** — Tests ensure quality and prevent regressions (documentation changes excepted) - **Niche features** — Features serving narrow use cases belong in extensions diff --git a/docs/community/extensions/index.md b/docs/community/extensions/index.md deleted file mode 100644 index 5cb2ef1e..00000000 --- a/docs/community/extensions/index.md +++ /dev/null @@ -1,95 +0,0 @@ -# Extensions and ecosystem - -Developers building agents often need integrations with external services—databases, APIs, messaging platforms. Writing these integrations from scratch takes time away from building your actual application. And once you've built something useful, sharing it with others requires navigating package publishing, CI/CD setup, and documentation. - -Strands addresses this through an extensible architecture and community ecosystem. You can extend Strands with custom tools, model providers, hooks, and session managers. And we provide templates and infrastructure to make publishing your extensions as simple as possible. - -This page explains how the Strands ecosystem works, why we organize it into tiers, and how you can contribute your own extensions. - -## The tiered ecosystem - -We organize extensions into three tiers based on who maintains them and what level of support you can expect. Understanding these tiers helps you make informed decisions about which packages to use and where your contributions belong. - -### Tier 1: Core - -Core extensions live in official Strands repositories like [strands-agents/tools](https://github.com/strands-agents/tools). The Strands team maintains, tests, and supports these packages. They're battle-tested and safe to use in production. - -**Characteristics:** - -- Maintained by the Strands core team -- Comprehensive test coverage and CI/CD -- Security patches and updates guaranteed -- Breaking changes follow semantic versioning -- Full integration with SDK features - -**Examples:** `strands_tools` package (calculator, file_read, shell, etc.) - -We accept bug fixes and improvements to existing core tools through pull requests. However, we don't accept new external tools to core repositories—see the section below for why. - -### Tier 2: Partner (coming soon) - -Partner extensions are high-quality integrations with major services, maintained by service providers or trusted partners. We highlight these in our documentation with a "Partner" label. If you maintain a service and want to provide an official Strands integration, [start a discussion](https://github.com/strands-agents/sdk-python/discussions) to explore partnership. - -**Characteristics:** - -- Maintained by service providers or approved partners -- Meet quality and documentation standards -- Listed in docs with "Partner" designation -- Subject to periodic review - -**Process for partnership:** - -1. Build a high-quality integration with comprehensive docs and tests -2. Publish to PyPI with established maintenance track record -3. Start a discussion to propose partnership -4. Work with us to meet partner standards -5. Get featured in docs with partner designation - -### Tier 3: Community - -Community extensions are published and maintained by individual developers like you. Anyone can publish a community package—we provide templates to make it easy, and list packages in our [community catalog](../community-packages.md) for discoverability. - -**Characteristics:** - -- Maintained by community members -- Variable quality and support levels -- Full ownership and control by author -- Fast iteration and updates -- Listed in community catalog - -**This is where most contributions belong.** You maintain full ownership and control over your package, iterate at your own pace, and get full credit for your work. - -To get started, see [Publishing Extensions](./publishing.md). - -## Why we don't accept external tools - -You might wonder why we don't just accept community tools directly into the core repository. We've thought carefully about this, and here's our reasoning. - -**Security responsibility.** When we publish code under the `strands-agents` organization, we take responsibility for its security. We need to audit the code, understand every API it integrates with, and respond to security issues promptly. We can't do this for tools that integrate with services we don't use or understand deeply. A recent CVE in a community-contributed tool illustrated this risk—we couldn't assess the severity or fix it quickly because we lacked expertise with that service. - -**Maintenance burden.** Core packages require ongoing maintenance—testing against API changes, updating for SDK changes, fixing bugs, reviewing improvements. With a small team, we can't maintain tools for hundreds of services. You know your use case and the service you're integrating better than we do, and you can iterate faster when you control the package. - -**Quality expectations.** Mixing core and community code in one repository makes it hard to set clear expectations. Users don't know which tools are battle-tested and which are experimental. The tiered approach makes quality expectations transparent—core means Strands-maintained, community means author-maintained. - -**Dependency management.** External tools often require service-specific dependencies. Adding these to the core package increases installation size and complexity for everyone, even users who don't need those integrations. - -**Iteration speed.** External tool updates require core SDK releases. When you own the package, you can release updates immediately when the service's API changes. - -## The better path - -Publishing your own package gives you ownership, speed, credit, and discoverability. You control releases and updates. You don't wait for maintainer reviews. Your name is on the package. And we list you in our community catalog. - -**Benefits of publishing your own extension:** - -| Benefit | Description | -|---------|-------------| -| **Ownership** | You control the roadmap, features, and release schedule | -| **Speed** | Release updates immediately without waiting for core SDK releases | -| **Credit** | Your name and contribution are front and center | -| **Learning** | Gain experience with package publishing and maintenance | -| **Discoverability** | Listed in our community catalog for thousands of developers to find | -| **Flexibility** | Experiment and iterate without core SDK constraints | - -We provide templates and infrastructure to make publishing as easy as possible. The [strands-tool-template](https://github.com/strands-agents/strands-tool-template) includes pre-configured CI/CD, testing setup, and packaging configuration—you just add your tool code. - -→ [How to publish your extension](./publishing.md) diff --git a/docs/community/index.md b/docs/community/index.md index 583cf54d..4f60d532 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -2,29 +2,29 @@ The Strands community extends the SDK's capabilities through bug fixes, new tools, and improved documentation. Whether you're scratching your own itch or helping others, we're glad you're here. -Every contribution makes Strands better—from fixing a typo in the docs to building a new integration that helps thousands of developers. This section guides you through the different ways to contribute and helps you find the right path for your contribution. +## I want to fix a bug -## Contributing +Found something broken in the SDK? Bug fixes are always welcome. Check if there's an existing issue first, then submit a PR with a test that verifies your fix. -Start here to find the right contribution guide for your needs. Each guide walks you through the specific process, requirements, and best practices for that contribution type. +→ [Contributing to Core SDK](./contributing/core-sdk.md) -| I want to... | Guide | -|--------------|-------| -| Fix a bug or improve the SDK | [Contributing to Core SDK](./contributing/core-sdk.md) | -| Build and publish a tool or extension | [Publishing Extensions](./extensions/publishing.md) | -| Improve documentation | [Contributing to Documentation](./contributing/documentation.md) | -| Propose a significant feature | [Feature Proposals](./contributing/feature-proposals.md) | +## I want to add a new feature -## Extensions +Have an idea for improving the SDK? For small changes, open an issue to discuss your approach. For larger features, we use an RFC process to align on direction before you invest significant time. -The Strands ecosystem includes three tiers of extensions—core, partner, and community. Understanding how this works helps you decide where your contribution belongs and sets the right expectations for support and maintenance. +→ [Feature Proposals](./contributing/feature-proposals.md) -| Topic | Guide | -|-------|-------| -| Understanding the tiered ecosystem | [Extensions Overview](./extensions/index.md) | -| Publishing your own extension | [Publishing Guide](./extensions/publishing.md) | -| Building high-quality extensions | [Best Practices](./extensions/best-practices.md) | -| Finding community packages | [Community Catalog](./community-packages.md) | +## I want to build a tool or integration + +Built something useful? Publish it as your own package on PyPI. We provide templates to make this easy, and list community packages in our catalog so others can discover your work. + +→ [Publishing Your Component](./publishing/index.md) + +## I want to improve the docs + +Spotted a typo, unclear explanation, or missing example? Documentation improvements help everyone learn faster. From fixing typos to adding new guides, all improvements are welcome. + +→ [Contributing to Documentation](./contributing/documentation.md) ## Response times @@ -36,8 +36,9 @@ We aim to respond to contributions within these timeframes. These are goals, not | Follow-up responses | < 3 days between review rounds | | Security issues | < 24 hours | -## Quick links +## Community resources +- [Community Catalog](./community-packages.md) — Discover community-built tools and integrations - [GitHub Discussions](https://github.com/strands-agents/sdk-python/discussions) — Ask questions, share ideas - [Roadmap](https://github.com/orgs/strands-agents/projects/1) — See what we're working on - [Design Principles](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) — What guides our decisions diff --git a/docs/community/extensions/best-practices.md b/docs/community/publishing/best-practices.md similarity index 95% rename from docs/community/extensions/best-practices.md rename to docs/community/publishing/best-practices.md index 6074833c..de850a65 100644 --- a/docs/community/extensions/best-practices.md +++ b/docs/community/publishing/best-practices.md @@ -1,12 +1,12 @@ -# Extension Best Practices +# Component best practices -When you build an extension, you're creating something other developers will rely on. A well-designed extension is easy to understand, predictable in behavior, and helpful when things go wrong. +When you build a component, you're creating something other developers will rely on. A well-designed component is easy to understand, predictable in behavior, and helpful when things go wrong. -This guide covers patterns we've seen work well across the Strands ecosystem. Following these practices helps your extension integrate smoothly, makes it easier for others to contribute, and reduces support burden. +This guide covers patterns we've seen work well across the Strands ecosystem. Following these practices helps your component integrate smoothly, makes it easier for others to contribute, and reduces support burden. ## General principles -These principles apply to all extension types. They're the foundation of quality extensions. +These principles apply to all component types. They're the foundation of quality components. | Principle | Why it matters | How to apply | |-----------|----------------|--------------| diff --git a/docs/community/publishing/index.md b/docs/community/publishing/index.md new file mode 100644 index 00000000..df8535b0 --- /dev/null +++ b/docs/community/publishing/index.md @@ -0,0 +1,48 @@ +# Publishing your component + +Developers building agents often need integrations with external services—databases, APIs, messaging platforms. Writing these integrations from scratch takes time away from building your actual application. And once you've built something useful, sharing it with others requires navigating package publishing, CI/CD setup, and documentation. + +Strands makes this simple. You can extend Strands with custom tools, model providers, hooks, and session managers. And we provide templates and infrastructure to make publishing your components as easy as possible. + +This guide shows you how to publish your own tool, model provider, or other component, making it available to the entire Strands community. + +## Why publish your own component + +When you build something useful, publishing it as your own package gives you control and visibility. + +**Benefits of publishing your own component:** + +| Benefit | Description | +|---------|-------------| +| **Ownership** | You control the roadmap, features, and release schedule | +| **Speed** | Release updates immediately without waiting for core SDK releases | +| **Credit** | Your name and contribution are front and center | +| **Learning** | Gain experience with package publishing and maintenance | +| **Discoverability** | Listed in our community catalog for thousands of developers to find | +| **Flexibility** | Experiment and iterate without core SDK constraints | + +We provide templates and infrastructure to make publishing straightforward. The [strands-tool-template](https://github.com/strands-agents/strands-tool-template) includes pre-configured CI/CD, testing setup, and packaging configuration—you just add your component code. + +→ [How to publish your component](./publishing.md) + +## Understanding the ecosystem + +The Strands ecosystem has three tiers based on who maintains packages and what level of support you can expect. + +**Core packages** live in official Strands repositories like [strands-agents/tools](https://github.com/strands-agents/tools). The Strands team maintains, tests, and supports these packages. We accept bug fixes and improvements to existing core tools, but new tools and integrations should be published as community packages. + +**Partner packages** (coming soon) are high-quality integrations maintained by service providers or trusted partners. If you maintain a service and want to provide an official Strands integration, [start a discussion](https://github.com/strands-agents/sdk-python/discussions) to explore partnership. + +**Community packages** are published and maintained by developers like you. Anyone can publish a community package. This is where most contributions belong—you maintain full ownership and control, iterate at your own pace, and get full credit for your work. + +## Why we don't accept new tools to core + +You might wonder why we don't accept community tools directly into the core repository. Here's our reasoning: + +**Security responsibility.** When we publish code under the `strands-agents` organization, we take responsibility for its security. We need to audit the code, understand every API it integrates with, and respond to security issues promptly. We can't do this for tools that integrate with services we don't use or understand deeply. + +**Maintenance burden.** Core packages require ongoing maintenance—testing against API changes, updating for SDK changes, fixing bugs, reviewing improvements. With a small team, we can't maintain tools for hundreds of services. You know your use case better and can iterate faster when you control the package. + +**Quality expectations.** Mixing core and community code makes it hard to set clear expectations. The tiered approach makes it transparent—core means Strands-maintained, community means author-maintained. + +Publishing your own package gives you ownership, speed, and credit. You control releases, don't wait for reviews, and your name is on the package. diff --git a/docs/community/extensions/publishing.md b/docs/community/publishing/publishing.md similarity index 97% rename from docs/community/extensions/publishing.md rename to docs/community/publishing/publishing.md index 518c2c3f..87f5dbd4 100644 --- a/docs/community/extensions/publishing.md +++ b/docs/community/publishing/publishing.md @@ -1,6 +1,6 @@ -# Publishing extensions +# Publishing your component -You've built a useful tool or integration for Strands. Now you want to share it with others so they can benefit from your work. This guide walks you through publishing your extension to PyPI so anyone can install it with `pip install`. +You've built a useful tool or integration for Strands. Now you want to share it with others so they can benefit from your work. This guide walks you through publishing your component to PyPI so anyone can install it with `pip install`. We'll use our GitHub template to handle the boilerplate—package structure, CI/CD, testing setup, dependency management—so you can focus on your tool code. By the end, you'll have a published package and know how to release updates. @@ -235,5 +235,5 @@ Your `README.md` is the first thing users see. Make it count. ## Next steps -- [Extension best practices](./best-practices.md) — Guidelines for building high-quality extensions +- [Component best practices](./best-practices.md) — Guidelines for building high-quality components - [Community catalog](../community-packages.md) — See what others have built From 0a75cef745fc1d54b1306fa9d3e5bcc766efed32 Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Mon, 26 Jan 2026 18:30:23 -0500 Subject: [PATCH 04/11] docs: reorganize contribute and community sections - Separate Community (catalog/ecosystem) from Contribute (how to help) - Add new contribute section with core-sdk, documentation, feature-proposals, extensions guides - Create ADR process in adrs/ folder with template - Add team docs (TENETS, DECISIONS, API_BAR_RAISING) to root team/ folder - Add extensibility and community health strategy as ADRs - Update feature proposals to require issue first, ADR merge = go-ahead - Fix broken links and naming conventions (strands-agents topic) - Remove timeline commitments from ADR process - Delete old community/contributing and community/publishing folders --- adrs/0001-extensibility-ecosystem-strategy.md | 302 +++++++++++ adrs/0002-community-health-strategy.md | 475 ++++++++++++++++++ adrs/README.md | 88 ++++ docs/community/community-packages.md | 4 +- .../contributing/feature-proposals.md | 86 ---- docs/community/index.md | 45 -- docs/community/publishing/best-practices.md | 190 ------- docs/community/publishing/index.md | 48 -- docs/community/publishing/publishing.md | 239 --------- .../contributing/core-sdk.md | 14 +- .../contributing/documentation.md | 4 +- docs/contribute/contributing/extensions.md | 120 +++++ .../contributing/feature-proposals.md | 40 ++ docs/contribute/index.md | 29 ++ mkdocs.yml | 8 +- team/API_BAR_RAISING.md | 12 +- team/README.md | 21 + team/TENETS.md | 4 +- 18 files changed, 1098 insertions(+), 631 deletions(-) create mode 100644 adrs/0001-extensibility-ecosystem-strategy.md create mode 100644 adrs/0002-community-health-strategy.md create mode 100644 adrs/README.md delete mode 100644 docs/community/contributing/feature-proposals.md delete mode 100644 docs/community/index.md delete mode 100644 docs/community/publishing/best-practices.md delete mode 100644 docs/community/publishing/index.md delete mode 100644 docs/community/publishing/publishing.md rename docs/{community => contribute}/contributing/core-sdk.md (88%) rename docs/{community => contribute}/contributing/documentation.md (98%) create mode 100644 docs/contribute/contributing/extensions.md create mode 100644 docs/contribute/contributing/feature-proposals.md create mode 100644 docs/contribute/index.md create mode 100644 team/README.md diff --git a/adrs/0001-extensibility-ecosystem-strategy.md b/adrs/0001-extensibility-ecosystem-strategy.md new file mode 100644 index 00000000..e76a5ace --- /dev/null +++ b/adrs/0001-extensibility-ecosystem-strategy.md @@ -0,0 +1,302 @@ +# Strands Agents: Extensibility & Ecosystem Strategy + +> This document is a part of community/contributor management series. See [Strands Agents: Contributor Experience Analysis](./contributor-story.md), [Strands Agents: Community Health Strategy & Playbook](./community-health.md), [Strands Agents: Extensibility & Ecosystem Strategy](./extensibility.md), and [Strands Agents: Task Backlog [Community & Ecosystem]](./task-backlog.md) + +## Introduction + +This document defines our strategy for growing the Strands ecosystem—tools, integrations, and extensions built by the community. It builds on the [Contributor Story Analysis](./contributor-story.md) which identified tool publishing friction as a major problem, and the [Community Health Strategy](./community-health.md) which established our overall open source goals. + +**The problem:** The diversity of extensions is one of the most critical factors when choosing an agentic SDK. If we have tools for your use case vs a competitor where you need to write everything, the choice is clear. But today: +- Our tools repo has 94% external PRs that we're not accepting +- Publishing your own package requires hours of setup +- Even after publishing, there's no way for users to discover your tool + +**The goal:** Make it easy for developers to extend Strands and for users to discover those extensions—without taking on maintenance burden we can't sustain. + +--- + +## Part 1: Extension Points in Strands + +Before discussing strategy, let's be clear about what can be extended. Every idea here (templates, catalog, etc) applies to all extension types. + +**Tools** are the most common extension point. A tool is a function the agent can call—search the web, query a database, send an email. Tools are where most community interest lies. + +**Model Providers** let you connect Strands to different LLMs. We support Bedrock, Anthropic, OpenAI, Ollama, and others. Community members might want to add providers for other services. + +**Hook Providers** allow custom logic at various points in the agent lifecycle—before/after tool calls, on errors, etc. These are useful for logging, monitoring, or custom behaviors. + +**Session Managers** handle conversation state persistence. The default is in-memory, but you might want Redis, DynamoDB, or something else. + +For this document, we'll focus primarily on tools since that's where the demand is. The same patterns apply to other extension types. + +--- + +## Part 2: Current State + +### The Tools Repository Problem + +The tools repo tells a clear story: +- **94% of open PRs are from contributors** +- **Oldest open PR is 190+ days old** +- **Only 40.5% of issues get a maintainer response** + +Contributors want to add tools. We're not accepting them. The PRs sit open for months, contributors get frustrated, and our metrics look terrible. + +**Why we don't accept external tools:** + +We had a CVE for a MongoDB tool that a community member submitted. The team doesn't have enough expertise to fully understand and test it. We can't take security responsibility for code we can't verify. + +This isn't about gatekeeping—it's about honesty. We can't maintain tools for services we don't use, APIs we don't have keys for, and domains we don't understand. + +### The Publishing Friction Problem + +The alternative we offer—publish your own package—requires: +1. Create a GitHub repository +2. Set up a PyPI account +3. Configure GitHub Actions for CI/CD +4. Set up package structure (pyproject.toml, src layout) +5. Write documentation +6. Configure secrets for publishing + +For a 20-line tool, this is absurd. The overhead kills contribution. + +### The Discoverability Problem + +Even if someone publishes a tool, **no one can find it**. There's no catalog, no registry, no search. A developer looking for a Slack tool has no way to know one exists unless they happen to find it on PyPI or GitHub. + +This is the worst outcome: we've pushed contribution outside our repos, but we haven't solved the discovery problem that made being in our repos valuable in the first place. + +--- + +## Part 3: Strategy Options + +We considered several approaches before landing on our recommendation. + +### Option A: "Bring Your Code, We Vend It" (Rejected) + +The idea: create a repo where people dump their code, we publish whatever passes CI. + +**Pros:** +- Lowest friction for contributors +- Tools get the "strands" stamp +- Easy distribution via strands-tools package + +**Cons:** +- AppSec and leadership will push back—we'd be publishing code we haven't reviewed +- Even with explicit disclaimers ("we take no responsibility"), this requires leadership buy-in +- We become responsible for security issues in code we don't understand +- Maintenance burden scales with contributions +- One bad tool damages the whole package's reputation + +**Decision:** Rejected. The security and maintenance risks are too high, and getting leadership approval would be difficult. + +### Option B: GitHub Template + Self-Publish + +The idea: provide a template repository with everything pre-configured. Contributors clone it, add their code, configure secrets, and publish to their own PyPI namespace. + +**Pros:** +- Dramatically reduces publishing friction +- We don't maintain the code—authors do +- Clear ownership and responsibility +- Authors can iterate at their own pace + +**Cons:** +- Tools don't get "strands" branding +- Requires solving discoverability separately +- Some friction remains (PyPI account, secrets) + +**Decision:** This is our primary approach. + +### Option C: Tiered Approach (Recommended) + +This is the recommended approach. We need a set of tools we provide—this is critical for people to get started and test their use cases. + +**Why a separate tools repo?** Dependency management. Each tool is essentially another client/dependency. Keeping them separate from the core SDK keeps the SDK lean. + +**Tier 1 - Core:** We maintain, we test, we support. Tools critical for getting started with the SDK. Lives in `strands-agents/tools`. + +**Tier 2 - Partner:** Third parties maintain, we highlight in catalog with a "Partner" label. For major integrations (AWS services, popular APIs). + +**Tier 3 - Community:** Catalog listing only. We display their README as-is (similar to strands.my). We don't maintain or endorse, just make discoverable. + +**Pros:** +- Allows us to highlight important integrations +- Clear expectations at each tier +- Scales with ecosystem growth + +**Cons:** +- More complex to manage +- Tier 2 requires partnership agreements + +**Decision:** This is our target state. Start with Template + Catalog (Option B) to unblock contributors now, then build toward tiered approach. + +--- + +## Part 4: Template Implementation + +We need to provide scaffolding so contributors can publish extensions without hours of setup. + +### Recommendation: Template CLI + +CLI tool that generates projects from parameters: + +```bash +uvx strands-create tool --name slack --author "Your Name" +``` + +**Pros:** Best DX, handles naming automatically, no cleanup +**Cons:** Need to build and maintain CLI + +**Existing work:** Tool template already exists at [mkmeral/strands-tool-template](https://github.com/mkmeral/strands-tool-template). CLI can use this as the underlying template for tools. + +**Rollout:** +1. Phase 1: CLI generates tool projects (covers 90% of demand) +2. Phase 2: Add model providers, hook providers, session managers +3. Phase 3: Interactive mode, optional features + +### Naming Convention + +- Package: `strands-tool-{name}` +- Import: `strands_tool_{name}` +- GitHub topic: `strands-tool` (for catalog discovery) + +--- + +## Part 5: Tools Catalog Strategy + +The template solves publishing friction. The catalog solves discoverability. + +### What It Is + +A page on strandsagents.com listing community tools. Users can browse, search, and find tools for their use cases. + +### Implementation Phases + +We have a parallel workstream to migrate our website to Astro/Starlight (see CMS Migration), which will enable dynamic content loading. We don't want to block discoverability on that migration. + +**Phase 1: Manual Catalog (Now - Stop-gap)** + +Manually populate a static list while CMS migration is in progress. + +Actions: +1. Search GitHub for repos with strands-tool topic or naming convention +2. Search PyPI for strands- packages +3. Curate results into a static markdown page in current MkDocs docs +4. Link from docs navigation + +Optional: Link to strands.my as an additional discovery option (community-built dashboard that auto-discovers strands- packages from PyPI). + +**Phase 2: Dynamic Catalog (Post-CMS Migration)** + +Once Astro/Starlight is live, leverage its remote content capabilities to: +- Query GitHub API for repos with strands-tool topic +- Query PyPI API for strands-* packages +- Auto-generate catalog entries +- Add tier labels (Core/Partner/Community) + +TODO: have some curation + +### Catalog Information + +For each tool, show: +- Name and description +- Author/maintainer +- GitHub repo link +- PyPI/npm link +- Install command +- Category/tags +- Tier label (Core/Partner/Community) + +--- + +## Part 6: Communication and Migration + +We need to clearly communicate the new path and update existing guidance. + +### Contributor Guidance + +We need a unified contributor guide in docs. For extensibility specifically: + +- How to use the template +- How to get listed in the catalog +- What we DO accept in core tools repo (bug fixes to existing tools, documentation) + +### Tools Repository Updates + +**README.md** - Add prominent notice: + +> **Note:** We don't accept external tools to this repository. To publish your own tool, use our [GitHub template](link) and publish to PyPI. Your tool can be listed in our [community catalog](link). + +**CONTRIBUTING.md** - Update to explain: +- Why we don't accept external tools (security, maintenance) +- How to use the template +- How to get listed in the catalog +- What we DO accept (bug fixes to existing tools, documentation) + +### Existing PRs + +For the 34 open PRs from contributors in tools: +1. Post a comment explaining the new path +2. Link to the template +3. Offer to help them migrate their code +4. Close PRs after reasonable time (2 weeks?) + +### Website Updates + +- Add "Ecosystem" or "Community Tools" section to docs +- Link from main navigation +- Include in "Getting Started" guides + +--- + +## Part 7: Implementation Roadmap + +| Phase | Goal | Tasks | +|-------|------|-------| +| **1: CLI** | Reduce publishing friction | Build `strands-create` CLI with tool template, Publish to PyPI, Write documentation for CLI usage, Test end-to-end flow | +| **2: Communication** | Redirect contributors to new path | Update tools repo README and CONTRIBUTING.md, Comment on open external PRs with new path, Close stale PRs with explanation | +| **3: Basic Catalog** | Solve discoverability | Create static catalog page on docs site, Add initial tools, Document how to request catalog listing | +| **4: Dynamic Catalog** | Scale discoverability | Define GitHub topic convention (`strands-tool`), Build GitHub API integration, Add search/filter functionality | +| **5: Ecosystem Growth** | Grow the flywheel | Promote community tools in docs, Highlight tools in release notes, Evaluate need for tiered approach | + +--- + +## Part 8: Contributor Guide + +We need a unified contributor guide in docs that explains how to develop and publish extensions. The guide should cover both Python and TypeScript (TypeScript SDK is experimental but growing). + +**For Tool Contributors (Python):** +1. Run `strands-create tool --name yourname --author "Your Name"` +2. Add your tool code +3. Push to GitHub +4. Add `PYPI_API_TOKEN` to repo secrets +5. Create a GitHub release → automatically publishes to PyPI +6. Add `strands-tool` topic to your repo for catalog visibility + +**For Tool Contributors (TypeScript):** +- Similar flow with npm instead of PyPI +- CLI support TBD (TypeScript SDK is experimental) + +**For Other Extension Types:** +- Model providers: `strands-create model-provider --name yourname` +- Hook providers: `strands-create hook-provider --name yourname` +- Session managers: `strands-create session-manager --name yourname` + +The guide should link to: +- The `strands-create` CLI (PyPI) +- The community catalog +- Example implementations +- Strands SDK documentation for extension interfaces + +--- + +## Open Questions + +1. **Partner tier:** How do we identify and label partners? Probably a "Partner" label in the catalog for major integration providers (Slack, databases, etc.). + +--- + +## TODO: + +- open source the docs, and refer there +- check GH wiki pages diff --git a/adrs/0002-community-health-strategy.md b/adrs/0002-community-health-strategy.md new file mode 100644 index 00000000..2e41c58b --- /dev/null +++ b/adrs/0002-community-health-strategy.md @@ -0,0 +1,475 @@ +# Strands Agents: Community Health Strategy & Playbook + +> This document is a part of community/contributor management series. See [Strands Agents: Contributor Experience Analysis](./contributor-story.md), [Strands Agents: Community Health Strategy & Playbook](./community-health.md), [Strands Agents: Extensibility & Ecosystem Strategy](./extensibility.md), and [Strands Agents: Task Backlog [Community & Ecosystem]](./task-backlog.md) + +## Terminology + +| Term | Definition | +|------|------------| +| **Maintainers** | AWS team that owns Strands Agents SDK | +| **Contributors** | Anyone who contributes to the Strands ecosystem (e.g., publishing tools on PyPI) | +| **Core Contributors** | Contributors to core Strands packages (sdk-python, sdk-typescript, tools, docs) | +| **Customers** | End users of Strands — may overlap with contributors if they publish components | +| **Community** | Everyone: contributors, customers, etc. | + +--- + +## Introduction + +This document defines what we want from being open source and how we operationalize community health. It builds on the [Contributor Story Analysis](./contributor-story.md) which identified friction points in our contributor experience. While that document focused on understanding problems, this one focuses on strategy and solutions. + +The goal is to get team and leadership alignment on our open source goals, then provide an operational playbook for achieving them. + +### Where We Are Today + +Strands Agents is an open source AI agent SDK. We're growing fast (~5K stars) but our contributor experience metrics need improvement: + +- **External PRs take 10.6 days to merge** (industry benchmark: < 7 days) +- **Only 52% of external PRs get merged** (industry benchmark: > 60%) +- **Issue response time averages 13 days** (industry benchmark: < 2 days) +- **Only 4 repeat contributors** in sdk-python (we're not retaining core contributors) + +Before we can fix these problems, we need to answer a fundamental question: **What do we actually want from being open source?** The answer determines how much we invest and where. + +--- + +## Part 1: What We Want From Open Source + +We're already open source. The question isn't "should we be open source?" but "how do we make the best of it?" This section defines what we're optimizing for and the trade-offs we're making. + +### The Core Trade-off + +Being open source gives us: + +- **Adoption:** Zero friction. Developers pip install and start building. +- **Community Contributions:** We're a small team. Community extends our reach with bug fixes, docs, and specialized features. +- **Community Signals:** Direct feedback on what to prioritize. Users tell us about critical bugs, missing features, and emerging use cases. +- **Ecosystem:** Third parties build tools, integrations, content. Network effects make the platform stickier. +- **Trust:** Enterprises can audit our code. Transparency builds confidence. + +But it costs us: + +- **Opportunity Cost:** PR review, issue triage, documentation, support. Every hour on community is an hour not on features. +- **Community Trust Risk:** With a small team, slow responses damage reputation. If we're not reacting to community, we lose trust—and contributors. +- **Control:** Communities can fork if they disagree with direction. + +**The key question: How do we balance community investment with feature development?** + +### Goals (Prioritized) + +**P0: Adoption** + +Downloads, usage, stars. This is always the north star—everything else serves this goal. We can't directly move these numbers with community work alone, but it's what we're ultimately optimizing for. + +**P1: Ecosystem Growth** + +Tools, integrations, and extensions make the SDK sticky. A developer will choose the SDK that has tools for their use case. This is the flywheel—once kickstarted, it grows without us. We need both quality AND quantity here. + +**P2: Community Health & Contributor Experience** + +Community contributions scale our velocity. Bug fixes, docs, specialized features — work we couldn't prioritize ourselves. But this only works if contributors stick around. Fast responses, clear processes, good experience. If contributors have a bad experience, they don't come back—and they tell others. + +**P3: Community Signals** + +The community tells us what matters. Bug reports, feature requests, and discussions help us prioritize. This is a two-way relationship—we need to listen, not just broadcast. + +**P4: Trust and Brand** + +Enterprise adoption requires transparency. Being open source signals trustworthiness. This is table stakes, not a differentiator. + +### What We're NOT Optimizing For + +To be explicit about trade-offs: + +- **Not maximizing community size at any cost.** Quality matters. +- **Not accepting every PR.** We'll reject PRs that don't align with project direction. +- **Not providing 24/7 support.** We're not a support organization. + +### Success Metrics + +**Adoption Metrics (P0)** — The north star + +| Metric | Current | Notes | +|--------|---------|-------| +| GitHub Stars (sdk-python) | ~5K | Track trend | +| PyPI Downloads/month | 419,400 (weekly) | Track trend | +| npm Downloads/month | 11,084 (weekly) | Track trend | + +**Ecosystem Metrics (P1)** — The flywheel + +| Metric | Current | 6-Month Target | 12-Month Target | +|--------|---------|----------------|-----------------| +| Community Tools (listed on website) | 5 | 30 | 100 | +| Model Providers | 4 | 10 | 20 | +| Session Managers | 1 | 5 | 20 | + +**Community Health Metrics (P2)** — What we operationalize + +| Metric | Current | 6-Month Target | 12-Month Target | +|--------|---------|----------------|-----------------| +| PR First Response | 2.4 days | < 3 days | < 48h | +| PR Merge Time (core contributors) | 10.6 days | < 7 days | < 5 days | +| Issue First Response | 13 days | < 3 days | < 48h | +| Repeat Core Contributors | 4 | 10 | 20 | + +See [Extensibility & Ecosystem doc](./extensibility.md) for detailed ecosystem metrics (community tools, integrations, etc.). + +--- + +## Part 2: Competitor Learnings + +We can learn from how other AI agent SDKs handle community. Let's take what works. + +| Project | Stars | Community Channel | What We Can Learn | +|---------|-------|-------------------|-------------------| +| LangChain | ~120K | Slack + Forum | 400+ integrations, comprehensive contributor docs, "good first issue" labeling | +| CrewAI | ~42K | Forum | Fast issue closure (97%+), 100K+ certified developers community | +| AutoGen | ~53K | Discord | Human-in-the-loop focus, research-oriented community | +| **Strands** | ~5K | None | — | + +*Star counts verified January 2026.* + +**Key observations:** +- All competitors have real-time community channels. We don't. +- CrewAI and LangChain close 97%+ of issues. We close 54%. +- Fast response time correlates with contributor retention. + +**Practices worth adopting:** +- **Clear contribution docs:** LangChain has detailed contributor documentation covering setup, PR process, code standards, and testing requirements. They redirect CONTRIBUTING.md to comprehensive docs site. +- **Issue labeling:** LangChain uses `good first issue` and `help wanted` labels to guide new contributors. They also have a pinned "Looking to Contribute? Start Here!" issue. +- **Design discussion before implementation:** LangChain requires design discussion for large features before implementation—prevents wasted effort on both sides. + +--- + +## Part 3: Key Decisions + +Based on the analysis, here are the strategic decisions we need to make: + +### Decision 1: Response Time SLA + +**Decision:** Commit to < 3 day first response SLA (aligned with twice-weekly triage meetings). + +**Rationale:** Research shows response time is a key predictor of contributor retention. Fast initial responses signal that contributions are valued and encourage repeat engagement. + +Currently we do internal triage, but we don't have public priority labels and we don't respond to contributors. From their perspective, they see no engagement. Same applies to PRs. + +The cost of slow response (lost contributors, bad reputation) exceeds the cost of interruption. First response doesn't mean full review—just acknowledgment and initial triage. + +**Implementation:** Triage happens in twice-weekly "Community PR and Issue Review" meetings (Tue/Thu). This requires: +- Oncall dashboard so they can see what needs response +- Clear guidelines on what "first response" means +- Processes documented in oncall runbook + +### Decision 2: PR Acceptance Rate Target + +**Decision:** Target 65-70% acceptance rate (up from 52%). + +**Rationale:** Current 52% rate means contributors have coin-flip odds. This discourages contribution. But we shouldn't accept everything—quality matters. + +The gap is likely due to unclear expectations, not bad contributions. Better guidelines and early feedback should improve the rate without lowering standards. + +**Implementation:** +- Clear contribution guidelines documenting what we accept/reject +- Early feedback on direction before significant investment +- Add a proposal/RFC process for contributors to propose new features before implementation using GitHub Discussions with a proposal template—lower friction, signals we want conversation not just task tracking, and keeps proposals separate from bugs/feature requests. + +### Decision 3: Tools Repository Policy + +**Decision:** Don't accept external tools to core repo. Provide template + catalog instead. + +**Rationale:** We can't test, maintain, or take security responsibility for tools we don't understand. The MongoDB CVE incident showed the risk. But we should make it easy to publish and discover community tools. + +**Implementation:** See [Extensibility & Ecosystem doc](./extensibility.md) for details on: +- GitHub template for tool packages +- Community tools catalog/registry +- Clear communication in tools repo +- Contributor guide in docs explaining how to develop and publish tools (use template → update PyPI secrets → update tool code → publish, use tags for visibility) + +### Decision 4: Community Channel + +**Proposal:** Adopt Discord as our real-time community channel. + +**Rationale:** All competitors have real-time community channels. Internal contributors have Slack access which gives them a significant advantage over external contributors. A real-time channel bridges this gap. + +**Moderation:** We may take over an existing Discord from the AgentCore team, which reduces cold-start and provides existing moderation infrastructure. + +**Trade-off:** Requires ongoing moderation investment, but the cost of not having a community channel (slower communication, contributor disadvantage) is higher. + +--- + +## Part 4: Observability + +We can't improve what we don't measure. Currently, we have no visibility into contributor health metrics. We need to build these dashboards to operationalize community health. + +### SLAs + +| Item Type | First Response | Cycle Time | Notes | +|-----------|---------------|------------|-------| +| PRs | < 3 days | < 3 days between responses | Oncall acknowledges, owner assigned in twice-weekly meeting | +| Issues | < 3 days | < 3 days | Triage and label in twice-weekly meeting | +| Discussions | < 72h | Best effort | Lower priority | +| Security Issues | < 24h | ASAP | Escalate immediately | + +### Metrics We Track + +**P0 Metrics (Review Weekly)** + +These directly measure core contributor experience: + +- **Core Contributor PR Success Rate:** % of core contributor PRs merged. Target: > 65% +- **PR First Response Time:** Median time to first maintainer response. Target: < 3 days +- **PR Merge Time (core contributors):** Median time from open to merge. Target: < 7 days +- **Issue First Response Time:** Median time to first response. Target: < 3 days +- **Issue Response Rate:** % of issues with maintainer response. Target: > 80% + +**P1 Metrics (Review Monthly)** + +These measure overall health: + +- **Stars:** GitHub stars across all repos. Target: Growing +- **Downloads:** PyPI + npm downloads. Target: Growing +- **New Core Contributors:** First-time core contributors per month. Target: > 10 +- **Repeat Core Contributors:** Core contributors with 2+ PRs. Target: Growing +- **BMI (Backlog Management Index):** Closed issues / Opened issues. Target: > 1.0 + +### Dashboards + +**Health & Trends Dashboard** + +For team review meetings. Shows trends over time: +- PR/Issue response times (trend) +- Success rates (trend) +- Open items count (trend) +- Contributor growth (trend) +- Stars/downloads (trend) + +**Oncall Operations Dashboard** + +For oncall to find items needing attention. Prioritized lists: +1. Items awaiting maintainer response (last comment from community member) +2. SLA breaches (> 3 days without response) +3. First-time core contributor PRs (need extra care) +4. Oldest open items +5. High-priority labeled items + +### Alerting + +**Phase 1 (Now):** Manual review of metrics in weekly oncall handover. + +**Phase 2 (Near-term):** Slack alert when items exceed 3 days without response. + +**Phase 3 (Future):** SLA breach creates internal Sev2.5 ticket for stale items. + +--- + +## Part 5: Visibility + +Observability (Part 4) is about us seeing community health. Visibility is about the community seeing our plans and thinking. + +### Why It Matters + +Contributors need context to contribute effectively. If they don't know our roadmap, they might spend a week on a PR we'll reject because it doesn't align with direction. If they don't understand our design principles, their code won't match our patterns. + +Visibility also builds trust. When we explain why we make decisions, the community understands we're not arbitrary gatekeepers. + +### What We Publish + +**Public Roadmap** + +What we're working on and what's coming. This helps contributors: +- Avoid duplicating work we're already doing +- Understand if their feature idea aligns with direction +- Find areas where contributions are welcome + +The roadmap should be high-level (themes, not tickets) and updated quarterly. + +**Design Principles** + +Our mental models for how Strands should work. We already have a Decision Record in the SDK repo that documents design decisions with rationale. We should expand this pattern: +- Model-first approach (let the LLM decide, not hardcoded logic) +- Keep the core SDK lean (tools/providers live separately) +- Hooks as low-level primitives, high-level abstractions built on top +- Prefer composition over inheritance + +These help contributors write code that fits our patterns. + +**Decision Rationale** + +When we make significant decisions (like not accepting external tools), we should explain why. This prevents frustration and helps the community understand our constraints. + +--- + +## Part 6: Processes and Mechanisms + +### Oncall Responsibilities + +Oncall is responsible for community management for the week. + +**Daily Tasks:** +- Check oncall dashboard for urgent items (security issues, SLA breaches) +- Handle security issues immediately (< 24h SLA) + +**Twice-Weekly Tasks (Tue/Thu meetings):** +- Triage new issues (label, prioritize, respond) +- Review new PRs (check alignment, assign owners) +- Follow up on items awaiting response + +**Weekly Tasks:** +- Review metrics in handover meeting +- Hand off in-progress items to next oncall +- Flag systemic issues to team + +**What Oncall is NOT Responsible For:** +- Full code review of all PRs (assign to appropriate maintainer) +- Fixing all bugs (triage and assign) +- 24/7 availability + +### PR Ownership Model + +**Problem:** PRs fall through cracks. No one owns them end-to-end. + +**Solution:** Assign a maintainer to own each core contributor PR during twice-weekly "Community PR and Issue Review" meetings (Tue/Thu). This reduces oncall load and distributes work across the team. + +**Process:** +1. During twice-weekly meeting, team reviews new PRs, checks alignment, assigns owners +2. Owner shepherds PR from first review to merge/close +3. Target: ~2 PRs per maintainer per week +4. If contributor doesn't respond in 1 week, owner can drop assignment +5. If we're getting more PRs than we can assign, discuss capacity in the meeting + +**Guidelines for Owners:** +- Engineers self-balance based on current load +- Big PRs count as multiple +- Dead PRs (no response > 2 weeks) can be closed or taken over +- When in doubt, ask in team channel or bring up during meetings + +### Trusted Contributors (Strands Champions) + +Internal engineers and solution architects want to contribute to Strands and be more involved. We can leverage these folks to scale our community management capacity. They're more reliable than random contributors because they have internal accountability and context. + +We can later extend this program to outside contributors, but for now this document is focused on internal engineers. + +**What they can do:** +- Triage and respond to issues +- Participate in discussions and RFCs +- Review PRs — their approval counts same as maintainers, but they can't merge +- Flag issues/discussions to maintainers via internal channel + +**What this enables:** +- Faster response times without adding maintainer headcount +- More eyes on PRs (smaller PRs can be reviewed and approved by trusted contributors, reducing maintainer load) +- Better coverage of community channels + +**Status:** We have an initial group of internal SAs interested. Details (commitment, onboarding, recognition) to be figured out as we go. + +### Triage Process + +**For New Issues:** +1. Review in twice-weekly meeting +2. Add type label: `bug`, `feature`, `question`, `documentation` +3. Add priority: `priority:critical`, `priority:high`, `priority:medium`, `priority:low` +4. Add area: `area:core`, `area:tools`, `area:models`, etc. +5. If good for external contribution: add `ready-for-contribution` +6. Respond to author with acknowledgment + +**For New PRs:** +1. Review in twice-weekly meeting +2. Check: Does this align with project direction? +3. If yes: Assign maintainer owner, add `awaiting-review` +4. If no: Provide feedback, close if appropriate +5. If unclear: Ask clarifying questions + +### Contribution Guidelines + +We need a unified contributor entry point in docs that covers: +- How to contribute to core SDK (core contributors) +- How to contribute new components like tools, model providers (contributors) +- Our decisions and internal thinking (roadmap, design principles) + +**What PRs We Accept:** +- Bug fixes with tests +- Documentation improvements +- Performance improvements with benchmarks +- Features that align with roadmap +- Features discussed and approved in issue first + +**What PRs We Don't Accept:** +- Features that don't align with project direction +- Breaking changes without prior discussion +- Code without tests +- Large refactors without prior discussion +- Tools to core tools repo (use template instead) + +**When to Close PRs:** +- No response from author > 2 weeks after feedback +- Doesn't align with project direction (after discussion) +- Duplicate of existing PR +- Author requests closure + +**When to Take Over PRs:** +- Author explicitly allows it +- PR is 90% done, just needs minor fixes +- Critical bug fix that's stalled + +--- + +## Part 7: Automation + +We have several agent projects in progress that can help: + +- Aaron's bot that generates responses to issues (helps oncall understand issues faster) +- Extend to replicate bugs and generate reproducible code +- Use internal Slack channel to generate draft responses +- Containerized agents for more direct tooling + +The idea is to use GitHub and local agents to generate responses and accelerate the team. We optimize these agents internally, then move the same configuration to GitHub Actions for automation. This creates a pipeline for agents to go from internal → GitHub. Along the way we'll need to solve agent permission problems (likely through specialized PAT tokens). + +**Use cases:** +- Write/update docs +- Review PRs (enabled by maintainer after alignment check) +- Replicate (and later solve) bugs +- Prioritize items +- SLA breach notifications +- Removing stale items + +**Dev tooling approach:** We should build shared dev tools (CLI, containerized agents) that we optimize together as a team. The progression: local tools → Slack notifications based on GitHub events → GitHub Actions responding directly. This lets us iterate quickly internally before exposing to community. + +### Agent-Assisted Review + +**Goal:** Reduce maintainer burden on mechanical review tasks. + +**Concerns:** Avoid Hadoop-style noise where every PR has pages of auto-generated boilerplate. It's demoralizing for contributors. + +**Approach:** +- Start with opt-in, not default +- Focus on actionable feedback only +- Summarize issues, don't list every lint error +- Human always makes final decision + +**Status:** We have a review agent in progress. Need to invest time to complete and iterate on these projects before broader rollout. + +--- + +## Part 8: Implementation Roadmap + +See the complete roadmap at [Task Backlog](./task-backlog.md) + +--- + +## Open Questions + +- **Oncall capacity:** Oncall is also responsible for bugs and critical issues. Is adding community management too much? Need to monitor and adjust. +- **Discord moderation:** We may take over an existing Discord from the AgentCore team. Need to confirm feasibility. + +--- + +## TODO: + +- Going public from internal discussions +- Define what first response is + guidelines +- in SLAs, maybe split to time to triage, time to resolution + - Avg First response < 3d + - Avg Triage < 1w + - Avg Resolution < 2w +- making triaging public +- note: ready to contribute → pr → review (we should prioritize this) diff --git a/adrs/README.md b/adrs/README.md new file mode 100644 index 00000000..73f4901e --- /dev/null +++ b/adrs/README.md @@ -0,0 +1,88 @@ +# Architecture Decision Records (ADRs) + +This folder contains Architecture Decision Records for significant features and changes to Strands Agents. ADRs document the context, decision, and consequences of architectural choices. + +## What is an ADR? + +An ADR is a design document that captures an important architectural decision along with its context and consequences. Once approved and merged, it becomes part of the project's decision history. + +## When to write an ADR + +Write an ADR for: + +- New major features affecting multiple parts of the SDK +- Breaking changes to existing APIs +- Architectural changes requiring design discussion +- Large contributions (> 1 week of work) +- Features that introduce new concepts + +Skip the ADR process for bug fixes, small improvements, documentation updates, and new extensions in your own repository. + +## How to submit an ADR + +1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)** — See if your idea aligns with our direction +2. **Fork the [docs repository](https://github.com/strands-agents/docs)** +3. **Create your ADR** — Add a new file: `adrs/NNNN-feature-name.md` using the template below +4. **Submit a pull request** — We'll review and discuss +5. **Iterate based on feedback** — Address comments and questions +6. **Get approval** — Once approved and merged, implement the feature +7. **Reference the ADR** — Link to it in your implementation PR + +## ADR template + +```markdown +# ADR: [Feature Name] + +**Status**: Proposed | Accepted | Deprecated | Superseded + +**Date**: YYYY-MM-DD + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +- What task are you trying to accomplish? +- What makes it difficult or impossible today? +- Who experiences this problem? + +## Decision + +What is the change that we're proposing and/or doing? + +- Changes to the API (with code examples) +- How it integrates with existing features +- Expected behavior and usage patterns + +## Developer Experience + +Show what the developer experience looks like: + +- Code examples showing typical usage +- Configuration or setup required +- Error messages and edge cases + +## Alternatives Considered + +What other approaches did you consider? Why did you choose this one? + +## Consequences + +What becomes easier or more difficult to do because of this change? + +## Willingness to Implement + +Are you willing to implement this if approved? + +Yes / No / Maybe with guidance +``` + +## ADR naming + +Use the format `NNNN-short-description.md` where NNNN is the next available number: + +- `0001-streaming-hooks.md` +- `0002-retry-strategies.md` + +## Accepted ADRs + +*No ADRs have been accepted yet.* diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index ac3344c5..d7a14efd 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -56,8 +56,8 @@ Built something useful? We'd love to list it here. Publishing your package to th **Requirements:** -1. **Publish your package to PyPI** — See our [publishing guide](./publishing/publishing.md) for step-by-step instructions -2. **Add the `strands-tool` topic** to your GitHub repository so developers can find you +1. **Publish your package to PyPI** — See our [extensions guide](../contribute/contributing/extensions.md) for step-by-step instructions +2. **Add the `strands-agents` topic** to your GitHub repository so developers can find you 3. **Submit a request** using our [content addition template](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with: - Package name and PyPI link - Clear description of what it does diff --git a/docs/community/contributing/feature-proposals.md b/docs/community/contributing/feature-proposals.md deleted file mode 100644 index 393d7fbd..00000000 --- a/docs/community/contributing/feature-proposals.md +++ /dev/null @@ -1,86 +0,0 @@ -# Feature Proposals - -Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. That's why we use an RFC (Request for Comments) process for larger contributions. - -This isn't bureaucracy for its own sake—it's about making sure your work has the best chance of being merged. We'd rather discuss approach early than ask you to rewrite after weeks of work. - -## When to use an RFC - -Not every contribution needs an RFC. Use this process for changes that have broad impact or require significant time investment. - -| Use RFC for | Skip RFC for | -|-------------|--------------| -| New major features affecting multiple parts of the SDK | Bug fixes with clear solutions | -| Breaking changes to existing APIs | Small improvements and enhancements | -| Architectural changes requiring design discussion | Documentation updates | -| Large contributions (> 1 week of work) | New tools in your own repository | -| Features that introduce new concepts | Performance optimizations | - -When in doubt, start with a GitHub Discussion. We'll tell you if an RFC is needed. - -## Process - -The RFC process helps align on requirements, explore alternatives, and identify edge cases before implementation begins. - -1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/1)** — See if your idea aligns with our direction and isn't already planned -2. **Open a GitHub Discussion** — Use the [Proposals](https://github.com/strands-agents/sdk-python/discussions/categories/proposals) category in the appropriate repository -3. **Use the template below** — Describe the problem, your solution, and alternatives you considered -4. **Gather feedback** — We'll discuss with you and the community, asking clarifying questions -5. **Get approval** — Wait for maintainer approval before implementing—approval means we commit to reviewing and likely merging your contribution -6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) once approved -7. **Reference the RFC** — Link to the approved discussion in your pull request - -**Timeline expectations:** - -- Initial response: Within 3 days -- Discussion period: 1-2 weeks for most proposals -- Decision: We'll clearly approve or decline with reasoning - -## Proposal template - -When you open a discussion, use this structure. Clear proposals get faster, more helpful feedback. - -```markdown -## Problem - -What problem are you trying to solve? Describe the pain point or limitation you're addressing. - -Be specific about: -- What task are you trying to accomplish? -- What makes it difficult or impossible today? -- Who experiences this problem? - -## Proposed Solution - -How would you solve it? Describe your approach at a high level. - -Include: -- Changes to the API (with code examples) -- How it integrates with existing features -- Expected behavior and usage patterns - -## Alternatives Considered - -What other approaches did you consider? Why did you choose this one? - -This helps us understand your reasoning and might surface better approaches. - -## Implementation Plan (optional) - -If you have thoughts on implementation, share them. Not required, but helpful. - -## Willingness to Implement - -Are you willing to implement this if approved? - -Yes / No / Maybe with guidance -``` - -**Tips for effective proposals:** - -- Focus on the problem first—solution comes second -- Include concrete examples showing current pain and proposed improvement -- Be open to feedback—the best solution might differ from your initial idea -- Align with our [development tenets](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) - -This process helps us avoid situations where someone builds a feature for weeks, only to find it doesn't fit the project direction. We'd rather have that conversation early. diff --git a/docs/community/index.md b/docs/community/index.md deleted file mode 100644 index 4f60d532..00000000 --- a/docs/community/index.md +++ /dev/null @@ -1,45 +0,0 @@ -# Community - -The Strands community extends the SDK's capabilities through bug fixes, new tools, and improved documentation. Whether you're scratching your own itch or helping others, we're glad you're here. - -## I want to fix a bug - -Found something broken in the SDK? Bug fixes are always welcome. Check if there's an existing issue first, then submit a PR with a test that verifies your fix. - -→ [Contributing to Core SDK](./contributing/core-sdk.md) - -## I want to add a new feature - -Have an idea for improving the SDK? For small changes, open an issue to discuss your approach. For larger features, we use an RFC process to align on direction before you invest significant time. - -→ [Feature Proposals](./contributing/feature-proposals.md) - -## I want to build a tool or integration - -Built something useful? Publish it as your own package on PyPI. We provide templates to make this easy, and list community packages in our catalog so others can discover your work. - -→ [Publishing Your Component](./publishing/index.md) - -## I want to improve the docs - -Spotted a typo, unclear explanation, or missing example? Documentation improvements help everyone learn faster. From fixing typos to adding new guides, all improvements are welcome. - -→ [Contributing to Documentation](./contributing/documentation.md) - -## Response times - -We aim to respond to contributions within these timeframes. These are goals, not guarantees—complex contributions might take longer to review thoroughly. - -| Type | Target | -|------|--------| -| First response | < 3 days | -| Follow-up responses | < 3 days between review rounds | -| Security issues | < 24 hours | - -## Community resources - -- [Community Catalog](./community-packages.md) — Discover community-built tools and integrations -- [GitHub Discussions](https://github.com/strands-agents/sdk-python/discussions) — Ask questions, share ideas -- [Roadmap](https://github.com/orgs/strands-agents/projects/1) — See what we're working on -- [Design Principles](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) — What guides our decisions -- [Code of Conduct](https://github.com/strands-agents/.github/blob/main/CODE_OF_CONDUCT.md) diff --git a/docs/community/publishing/best-practices.md b/docs/community/publishing/best-practices.md deleted file mode 100644 index de850a65..00000000 --- a/docs/community/publishing/best-practices.md +++ /dev/null @@ -1,190 +0,0 @@ -# Component best practices - -When you build a component, you're creating something other developers will rely on. A well-designed component is easy to understand, predictable in behavior, and helpful when things go wrong. - -This guide covers patterns we've seen work well across the Strands ecosystem. Following these practices helps your component integrate smoothly, makes it easier for others to contribute, and reduces support burden. - -## General principles - -These principles apply to all component types. They're the foundation of quality components. - -| Principle | Why it matters | How to apply | -|-----------|----------------|--------------| -| Clear naming | Descriptive names help agents and developers understand what tools do | Use verb-noun pairs like `search_database`, not ambiguous names like `query` | -| Single responsibility | Each tool does one thing well | Split complex operations into multiple focused tools | -| Detailed docstrings | Agents rely on docstrings to understand when and how to use tools | Include parameter explanations, examples, and edge cases | -| Error handling | Clear messages guide users to solutions | Catch specific exceptions and provide actionable error messages | -| Type hints | Better IDE support and agent understanding | Use type annotations on all parameters and returns | - -**Additional guidance:** - -- **Make defaults sensible** — Choose default values that work for 80% of use cases -- **Document requirements** — Specify API keys, credentials, or dependencies upfront -- **Version your API carefully** — Breaking changes require major version bumps -- **Test edge cases** — Cover error conditions, empty inputs, and boundary values - -## Tools - -Tools are functions agents can call to perform actions or retrieve information. The `@tool` decorator handles integration with the agent system. - -**The most important thing is your docstring**—it's what the agent reads to understand when and how to use your tool. A well-written docstring dramatically improves tool usage accuracy. - -=== "Python" - - ```python - from strands import tool - - @tool - def search_database(query: str, limit: int = 10) -> list[dict]: - """ - Search the database for matching records. - - Args: - query: Search query string - limit: Maximum results to return (default: 10) - - Returns: - List of matching records - - Example: - >>> search_database("customer orders", limit=5) - [{"id": 1, "name": "Order #123"}, ...] - """ - # Implementation - return results - ``` - -=== "TypeScript" - - ```typescript - import { tool } from "@strands-agents/sdk"; - - const searchDatabase = tool({ - name: "search_database", - description: "Search the database for matching records", - parameters: { - query: { type: "string", description: "Search query string" }, - limit: { type: "number", description: "Maximum results (default: 10)" } - }, - handler: async ({ query, limit = 10 }) => { - // Implementation - return results; - } - }); - ``` - -We recommend studying these examples from the official tools repo. They demonstrate patterns you can apply to your own tools. - -| Example | What it demonstrates | Key takeaway | -|---------|---------------------|--------------| -| [sleep](https://github.com/strands-agents/tools/blob/main/src/strands_tools/sleep.py) | Error handling patterns | How to validate inputs and provide helpful error messages | -| [browser](https://github.com/strands-agents/tools/blob/main/src/strands_tools/browser/__init__.py) | Multiple related tools | Organizing related functionality into tool collections | - -## Model providers - -Model providers let you integrate new LLMs with Strands. You implement the `Model` interface to wrap your model's API and translate between its format and Strands' standard format. - -**Key requirements for a model provider:** - -| Requirement | Description | Why it matters | -|-------------|-------------|----------------| -| `ModelConfig` pattern | Configuration via a config class | Consistent configuration across all model providers | -| `stream` method | Streaming response support | Users expect real-time responses | -| `StreamEvent` formatting | Proper event structure | Ensures compatibility with Strands event loop | -| Error handling | Translate provider errors to Strands exceptions | Consistent error experience across providers | -| Type annotations | Full typing for all methods | Better IDE support and error catching | - -**Implementation guide:** - -1. **Create a config class** extending `ModelConfig` -2. **Implement the `Model` interface** with `generate()` and `stream()` methods -3. **Handle streaming properly** by yielding `StreamEvent` objects -4. **Test with real API calls** to verify behavior -5. **Document configuration options** including required credentials - -For detailed implementation guidance, see [Custom Model Provider documentation](../../user-guide/concepts/model-providers/custom_model_provider.md). - -For a real-world example, study [strands-clova](https://github.com/aidendef/strands-clova)—it shows how to properly implement the interface and handle edge cases. - -## Hooks - -Hooks let you inject custom logic at agent lifecycle points. Common use cases include logging tool calls, validating inputs, modifying behavior, and collecting metrics. - -**Available hook points:** - -| Hook point | When it runs | Common uses | -|------------|--------------|-------------| -| `before_tool_call` | Before a tool executes | Logging, validation, input transformation | -| `after_tool_call` | After a tool completes | Logging results, metrics collection | -| `on_tool_error` | When a tool raises an exception | Error tracking, retry logic, fallbacks | - -**Implementation example:** - -```python -from strands import Agent - -def log_tool_calls(tool_name, tool_input): - """Log tool calls for debugging and auditing.""" - print(f"Calling {tool_name} with {tool_input}") - - # You can modify the input here - # Return the (possibly modified) input - return tool_input - -def handle_tool_errors(tool_name, error): - """Handle tool errors with custom logic.""" - print(f"Tool {tool_name} failed: {error}") - - # You can implement retry logic or fallbacks here - # Raise to propagate the error, return a value to recover - raise error - -agent = Agent( - hooks={ - "before_tool_call": log_tool_calls, - "on_tool_error": handle_tool_errors - } -) -``` - -For complete documentation, see [Hooks documentation](../../user-guide/concepts/agents/hooks.md). - -## Session managers - -Session managers handle conversation persistence. By default, Strands keeps conversation history in memory, which works for development but doesn't persist across restarts. For production, you'll want to persist sessions to a database or cache. - -**When to build a custom session manager:** - -| Use case | Backend | Why | -|----------|---------|-----| -| Fast, ephemeral sessions | Redis, Memcached | Low latency for short-lived conversations | -| Serverless, scalable persistence | DynamoDB, Firestore | Automatic scaling and pay-per-use | -| Custom storage | Your database | Integration with existing infrastructure | -| Compliance requirements | Encrypted storage | Meet regulatory requirements | - -**Implementation requirements:** - -1. **Implement the `SessionManager` interface** with `load()`, `save()`, and `delete()` methods -2. **Handle serialization** — Convert conversation history to/from storage format -3. **Manage session IDs** — Generate unique, stable identifiers -4. **Handle errors gracefully** — Fall back to empty history on corruption -5. **Consider performance** — Use connection pooling and caching where appropriate - -**Example implementation:** - -```python -from strands import Agent -from strands_redis import RedisSessionManager - -# Use a custom Redis session manager -session = RedisSessionManager( - host="localhost", - port=6379, - session_id="user-123", - ttl=3600 # 1 hour expiration -) - -agent = Agent(session_manager=session) -``` - -For more details, see [Session Management documentation](../../user-guide/concepts/agents/session-management.md). diff --git a/docs/community/publishing/index.md b/docs/community/publishing/index.md deleted file mode 100644 index df8535b0..00000000 --- a/docs/community/publishing/index.md +++ /dev/null @@ -1,48 +0,0 @@ -# Publishing your component - -Developers building agents often need integrations with external services—databases, APIs, messaging platforms. Writing these integrations from scratch takes time away from building your actual application. And once you've built something useful, sharing it with others requires navigating package publishing, CI/CD setup, and documentation. - -Strands makes this simple. You can extend Strands with custom tools, model providers, hooks, and session managers. And we provide templates and infrastructure to make publishing your components as easy as possible. - -This guide shows you how to publish your own tool, model provider, or other component, making it available to the entire Strands community. - -## Why publish your own component - -When you build something useful, publishing it as your own package gives you control and visibility. - -**Benefits of publishing your own component:** - -| Benefit | Description | -|---------|-------------| -| **Ownership** | You control the roadmap, features, and release schedule | -| **Speed** | Release updates immediately without waiting for core SDK releases | -| **Credit** | Your name and contribution are front and center | -| **Learning** | Gain experience with package publishing and maintenance | -| **Discoverability** | Listed in our community catalog for thousands of developers to find | -| **Flexibility** | Experiment and iterate without core SDK constraints | - -We provide templates and infrastructure to make publishing straightforward. The [strands-tool-template](https://github.com/strands-agents/strands-tool-template) includes pre-configured CI/CD, testing setup, and packaging configuration—you just add your component code. - -→ [How to publish your component](./publishing.md) - -## Understanding the ecosystem - -The Strands ecosystem has three tiers based on who maintains packages and what level of support you can expect. - -**Core packages** live in official Strands repositories like [strands-agents/tools](https://github.com/strands-agents/tools). The Strands team maintains, tests, and supports these packages. We accept bug fixes and improvements to existing core tools, but new tools and integrations should be published as community packages. - -**Partner packages** (coming soon) are high-quality integrations maintained by service providers or trusted partners. If you maintain a service and want to provide an official Strands integration, [start a discussion](https://github.com/strands-agents/sdk-python/discussions) to explore partnership. - -**Community packages** are published and maintained by developers like you. Anyone can publish a community package. This is where most contributions belong—you maintain full ownership and control, iterate at your own pace, and get full credit for your work. - -## Why we don't accept new tools to core - -You might wonder why we don't accept community tools directly into the core repository. Here's our reasoning: - -**Security responsibility.** When we publish code under the `strands-agents` organization, we take responsibility for its security. We need to audit the code, understand every API it integrates with, and respond to security issues promptly. We can't do this for tools that integrate with services we don't use or understand deeply. - -**Maintenance burden.** Core packages require ongoing maintenance—testing against API changes, updating for SDK changes, fixing bugs, reviewing improvements. With a small team, we can't maintain tools for hundreds of services. You know your use case better and can iterate faster when you control the package. - -**Quality expectations.** Mixing core and community code makes it hard to set clear expectations. The tiered approach makes it transparent—core means Strands-maintained, community means author-maintained. - -Publishing your own package gives you ownership, speed, and credit. You control releases, don't wait for reviews, and your name is on the package. diff --git a/docs/community/publishing/publishing.md b/docs/community/publishing/publishing.md deleted file mode 100644 index 87f5dbd4..00000000 --- a/docs/community/publishing/publishing.md +++ /dev/null @@ -1,239 +0,0 @@ -# Publishing your component - -You've built a useful tool or integration for Strands. Now you want to share it with others so they can benefit from your work. This guide walks you through publishing your component to PyPI so anyone can install it with `pip install`. - -We'll use our GitHub template to handle the boilerplate—package structure, CI/CD, testing setup, dependency management—so you can focus on your tool code. By the end, you'll have a published package and know how to release updates. - -## Before you start - -You'll need a GitHub account and a PyPI account. Publishing to PyPI makes your package installable via `pip` and discoverable through PyPI search. - -**Prerequisites:** - -- **GitHub account** — For hosting your repository and CI/CD -- **PyPI account** — Create one at [pypi.org/account/register](https://pypi.org/account/register/) -- **Your tool code** — A working Strands tool or integration you want to share - -If you don't have a PyPI account yet, creating one takes just a minute and is completely free. - -## Create your package - -We provide GitHub templates with everything pre-configured. Let's start by creating your repository from the template. - -### Step 1: Use the template - -The template repository includes all the packaging boilerplate you need—no need to figure out `setup.py`, CI/CD workflows, or testing configuration. - -=== "Python" - - Go to [github.com/strands-agents/strands-tool-template](https://github.com/strands-agents/strands-tool-template) and click "Use this template" to create your repository. - - Name it following the convention `strands-tool-{name}`, for example: - - - `strands-tool-slack` for a Slack integration - - `strands-tool-postgres` for PostgreSQL tools - - `strands-tool-weather` for weather APIs - - This naming convention helps developers discover your package and understand what it does at a glance. - -=== "TypeScript" - - TypeScript templates are coming soon. For now, you can use the Python template as a reference for structure and CI/CD configuration. - -### Step 2: Clone and customize - -Clone your new repository and open it in your editor. We'll customize it with your tool code and package details. - -```bash -git clone https://github.com/YOUR_USERNAME/strands-tool-example.git -cd strands-tool-example -``` - -The template includes placeholder code showing the structure. Take a moment to explore the key files: - -- `src/strands_tool_example/` — Your tool code goes here -- `tests/` — Test files for your tools -- `pyproject.toml` — Package configuration and dependencies -- `.github/workflows/` — CI/CD automation for testing and publishing -- `README.md` — Package documentation - -### Step 3: Add your tool code - -Open `src/strands_tool_example/your_tool.py` and replace the placeholder with your implementation. Use the `@tool` decorator to define your tools. - -```python -from strands import tool - -@tool -def search_database(query: str, limit: int = 10) -> list[dict]: - """ - Search the database for matching records. - - Use this tool when you need to find records based on a search query. - The search is case-insensitive and supports fuzzy matching. - - Args: - query: Search query string - limit: Maximum results to return (default: 10) - - Returns: - List of matching records with id, name, and metadata - - Example: - >>> search_database("customer orders", limit=5) - [{"id": 1, "name": "Order #123", ...}, ...] - """ - # Your implementation here - results = perform_database_search(query, limit) - return results -``` - -**Writing good docstrings is critical**—the docstring is what the AI agent reads to understand when and how to use your tool. Include clear descriptions, parameter explanations, and examples. - -Update the package name in `pyproject.toml` to match your tool name. Change all instances of `strands-tool-example` and `strands_tool_example` to your chosen name. - -### Step 4: Write tests - -Add tests in the `tests/` directory. The template includes pytest configuration and example tests to get you started. Good tests give users confidence in your package and help you catch bugs before they ship. - -```python -# tests/test_your_tool.py -from strands_tool_yourname import search_database - -def test_search_database_basic(): - """Test basic search functionality.""" - results = search_database("test query", limit=5) - - assert isinstance(results, list) - assert len(results) <= 5 - -def test_search_database_empty(): - """Test search with no results.""" - results = search_database("nonexistent query") - - assert results == [] -``` - -Run tests locally to verify everything works. - -```bash -# Set up development environment -hatch shell - -# Run tests -hatch test - -# Run with coverage -hatch test -c -``` - -The template's CI/CD will automatically run these tests on every pull request and before publishing. - -## Configure publishing - -Now we'll set up automatic publishing to PyPI when you create a release. The template handles the mechanics—you just need to provide credentials. - -### Step 1: Create a PyPI API token - -PyPI uses API tokens for secure authentication. These tokens are safer than passwords because you can scope them to specific packages and revoke them if needed. - -Go to [pypi.org/manage/account/token](https://pypi.org/manage/account/token/) and create a new API token. Give it a descriptive name like "strands-tool-example GitHub Actions" so you can identify it later. - -**Important:** Copy the token immediately—PyPI only shows it once. It starts with `pypi-`. - -### Step 2: Add the secret to GitHub - -In your GitHub repository, go to Settings → Secrets and variables → Actions. Click "New repository secret" and add: - -- **Name:** `PYPI_API_TOKEN` -- **Value:** Your PyPI token (the full string starting with `pypi-`) - -The template's GitHub Actions workflow is already configured to use this secret. It will automatically build and publish your package to PyPI whenever you create a release. - -## Publish your package - -With everything configured, publishing is simple. Creating a GitHub release triggers automatic publishing to PyPI. - -### Step 1: Create a release - -Go to your repository on GitHub and click "Releases" → "Create a new release". - -**Create a new tag** following [semantic versioning](https://semver.org/): - -- `v0.1.0` for your first release -- `v0.2.0` for new features -- `v0.1.1` for bug fixes -- `v1.0.0` when you're ready for production - -**Add release notes** describing what your tool does and any changes in this version. Good release notes help users understand what they're getting. - -**Example release notes:** - -```markdown -## Features - -- Added search_database tool for PostgreSQL integration -- Support for fuzzy search and pagination -- Configurable connection pooling - -## Installation - -pip install strands-tool-postgres - -## Usage - -from strands import Agent -from strands_tool_postgres import search_database - -agent = Agent(tools=[search_database]) -agent("Find all customers from last week") -``` - -### Step 2: Watch it publish - -GitHub Actions automatically builds and publishes your package to PyPI. You can watch the progress in the Actions tab of your repository. - -Once complete (usually 1-2 minutes), anyone can install your tool: - -```bash -pip install strands-tool-yourname -``` - -And that's it! Your tool is now available to the entire Strands community 🥳 - -## Get discovered - -To help others find your tool, take these steps to increase visibility. - -### Add GitHub topics - -Add the `strands-tool` topic to your GitHub repository. Go to your repository's main page, click the gear icon next to "About", and add `strands-tool` to the topics list. This makes your tool discoverable through GitHub topic searches. - -### Submit to the community catalog - -Submit your tool to be featured in our [community catalog](../community-packages.md). Create an issue in the [docs repository](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with: - -- Package name and PyPI link -- Clear description of what it does -- Usage examples showing basic integration -- Link to documentation - -We review submissions within 3 days. Well-documented packages with tests get priority for listing. - -### Write good documentation - -Your `README.md` is the first thing users see. Make it count. - -**Essential sections:** - -- **Installation** — Simple pip install command -- **Quick start** — Minimal example showing basic usage -- **Features** — What your tool can do -- **Configuration** — Any required setup or credentials -- **Examples** — Real-world usage scenarios -- **Contributing** — How others can help improve your tool - -## Next steps - -- [Component best practices](./best-practices.md) — Guidelines for building high-quality components -- [Community catalog](../community-packages.md) — See what others have built diff --git a/docs/community/contributing/core-sdk.md b/docs/contribute/contributing/core-sdk.md similarity index 88% rename from docs/community/contributing/core-sdk.md rename to docs/contribute/contributing/core-sdk.md index 8dd96e45..d63318f6 100644 --- a/docs/community/contributing/core-sdk.md +++ b/docs/contribute/contributing/core-sdk.md @@ -11,7 +11,7 @@ We welcome contributions that improve the SDK for everyone. Focus on changes tha - **Bug fixes with tests** that verify the fix and prevent regression - **Performance improvements with benchmarks** showing measurable gains - **Documentation improvements** including docstrings, code examples, and guides -- **Features that align with our [roadmap](https://github.com/orgs/strands-agents/projects/1)** and development tenets +- **Features that align with our [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)** and development tenets - **Small, focused changes** that solve a specific problem clearly ## What we don't accept @@ -20,7 +20,7 @@ Some contributions don't fit the core SDK. Understanding this upfront saves you - **Large refactors without prior discussion** — Major architectural changes require RFC approval - **Breaking changes without RFC approval** — We maintain backward compatibility carefully -- **External tools** — [Publish your own package](../publishing/publishing.md) instead for full ownership +- **External tools** — [Build your own extension](./extensions.md) instead for full ownership - **Changes without tests** — Tests ensure quality and prevent regressions (documentation changes excepted) - **Niche features** — Features serving narrow use cases belong in extensions @@ -116,17 +116,9 @@ Once you've made your changes, here's how to submit them for review. Following t 7. **Submit a pull request** referencing the issue number in the description 8. **Respond to feedback** — we'll review within 3 days and may request changes -**Quality requirements:** - -- All tests must pass (unit and integration tests where applicable) -- Code coverage must meet minimums (Python: varies by module, TypeScript: 80%+) -- Linting and formatting must pass without errors -- Conventional commit format required -- PR description must explain the change clearly (see our [PR guidelines](https://github.com/strands-agents/sdk-python/blob/main/docs/PR.md)) - The pre-commit hooks help catch issues before you push, but you can also run checks manually anytime. ## Related guides - [Feature proposals](./feature-proposals.md) — For significant features requiring discussion -- [Design principles](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md#development-tenets) — What guides our decisions +- [Team documentation](https://github.com/strands-agents/docs/tree/main/team) — Our tenets, decisions, and API review process diff --git a/docs/community/contributing/documentation.md b/docs/contribute/contributing/documentation.md similarity index 98% rename from docs/community/contributing/documentation.md rename to docs/contribute/contributing/documentation.md index 2606b137..a9950f86 100644 --- a/docs/community/contributing/documentation.md +++ b/docs/contribute/contributing/documentation.md @@ -17,10 +17,12 @@ We're looking for contributions that improve the developer experience. Documenta | New examples | Code samples and tutorials | Working code showing real-world usage | | API reference | Improvements to reference documentation | Better parameter descriptions, return value docs | | New guides | Complete tutorials or concept pages | Step-by-step workflows, architecture explanations | -| Translations | Contact us first to coordinate | Non-English documentation (requires coordination) | ## Setup +!!! warning "Migration in progress" + This section will be rewritten as we migrate to a new CMS. + Let's get the docs running locally so you can preview your changes as you work. The docs are built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). ```bash diff --git a/docs/contribute/contributing/extensions.md b/docs/contribute/contributing/extensions.md new file mode 100644 index 00000000..01e8aa23 --- /dev/null +++ b/docs/contribute/contributing/extensions.md @@ -0,0 +1,120 @@ +# Building Extensions + +Extensions are tools, model providers, hooks, and session managers that extend Strands capabilities. You publish these as your own packages on PyPI. + +## Why build an extension + +When you build something useful, publishing it as your own package gives you control and visibility. + +| Benefit | Description | +|---------|-------------| +| **Ownership** | You control the roadmap, features, and release schedule | +| **Speed** | Release updates immediately without waiting for core SDK releases | +| **Credit** | Your name and contribution are front and center | +| **Discoverability** | Listed in our community catalog for thousands of developers to find | + +## Quick start + +We provide a GitHub template with everything pre-configured—package structure, CI/CD, testing setup, and publishing workflows. + +1. **Use the template** — Go to [strands-agents/strands-template](https://github.com/strands-agents/strands-template) and click "Use this template" +2. **Run setup** — Clone your repo and run `python setup_template.py` +3. **Add your code** — Implement your extension +4. **Publish** — Create a GitHub release to automatically publish to PyPI + +## Step-by-step guide + +### Prerequisites + +- **GitHub account** — For hosting your repository and CI/CD +- **PyPI account** — Create one at [pypi.org/account/register](https://pypi.org/account/register/) + +### Create your repository + +Go to [strands-agents/strands-template](https://github.com/strands-agents/strands-template) and click "Use this template". + +Clone it locally and run the setup script: + +```bash +git clone https://github.com/YOUR_USERNAME/your-repo-name +cd your-repo-name +python setup_template.py +``` + +The script prompts for your package name, author info, and description. + +### Implement your extension + +The template includes skeleton implementations for all extension types: + +| 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` | Hook provider | React to agent lifecycle events | +| `session_manager.py` | Session manager | Persist conversations across restarts | + +**Keep what you need, delete the rest.** Most packages only need one or two components. + +For implementation guidance: + +- [Creating custom tools](../../user-guide/concepts/tools/custom-tools.md) +- [Custom model providers](../../user-guide/concepts/model-providers/custom_model_provider.md) +- [Hooks](../../user-guide/concepts/agents/hooks.md) +- [Session management](../../user-guide/concepts/agents/session-management.md) + +### Test your code + +```bash +pip install -e ".[dev]" +hatch run prepare # Runs format, lint, typecheck, test +``` + +### Configure PyPI publishing + +The template includes a GitHub Actions workflow that publishes to PyPI on release. + +To enable it, configure PyPI trusted publishing: + +1. Go to [PyPI](https://pypi.org) → Your projects → Publishing +2. Add a new pending publisher with your GitHub repo details +3. Set environment name to `pypi` + +### Publish + +1. Go to your repository on GitHub +2. Click "Releases" → "Create a new release" +3. Create a tag following [semantic versioning](https://semver.org/) (e.g., `v0.1.0`) +4. Click "Publish release" + +GitHub Actions builds and publishes your package. Anyone can now install it: + +```bash +pip install strands-yourname +``` + +## Naming conventions + +| Item | Convention | Example | +|------|------------|---------| +| PyPI package | `strands-{name}` | `strands-slack` | +| Python module | `strands_{name}` | `strands_slack` | +| GitHub topic | `strands-agents` | For discoverability | + +## Get discovered + +After publishing: + +1. **Add GitHub topics** — Add `strands-agents` to your repository +2. **Submit to catalog** — Get listed in our [community catalog](../../community/community-packages.md) + +→ [Get Featured guide](../../community/get-featured.md) + +## Tips for quality extensions + +| Principle | How to apply | +|-----------|--------------| +| Clear naming | Use verb-noun pairs like `search_database`, not `query` | +| Detailed docstrings | Include parameter explanations, examples, and edge cases | +| Error handling | Catch specific exceptions and provide actionable messages | +| Type hints | Use type annotations on all parameters and returns | diff --git a/docs/contribute/contributing/feature-proposals.md b/docs/contribute/contributing/feature-proposals.md new file mode 100644 index 00000000..fec7f4ed --- /dev/null +++ b/docs/contribute/contributing/feature-proposals.md @@ -0,0 +1,40 @@ +# Feature Proposals + +Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. We use an ADR (Architecture Decision Record) process for larger contributions to ensure your work has the best chance of being merged. + +## When to write an ADR + +Not every contribution needs an ADR. Use this process for changes that have broad impact or require significant time investment. + +| Use ADR for | Skip ADR for | +|-------------|--------------| +| New major features affecting multiple parts of the SDK | Bug fixes with clear solutions | +| Breaking changes to existing APIs | Small improvements and enhancements | +| Architectural changes requiring design discussion | Documentation updates | +| Large contributions (> 1 week of work) | New extensions in your own repository | +| Features that introduce new concepts | Performance optimizations | + +When in doubt, open an issue first. We'll tell you if an ADR is needed. + +## Process + +The ADR process helps align on requirements, explore alternatives, and identify edge cases before implementation begins. + +1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)** — See if your idea aligns with our direction and isn't already planned +2. **Open an issue first** — Describe the problem you're trying to solve. We need to validate the problem is worth solving before you invest time in a detailed proposal +3. **Create an ADR** — Once we agree the problem is worth solving, submit a PR to the [`adrs` folder](https://github.com/strands-agents/docs/tree/main/adrs) in the docs repository using the template there. Reference the issue in your ADR +4. **Gather feedback** — We'll review and discuss with you, asking clarifying questions +5. **Get approval** — When we merge the ADR, that's your go-ahead to implement +6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) +7. **Reference the ADR** — Link to the approved ADR in your implementation PR + +## ADR template + +See the full template in the [ADRs folder README](https://github.com/strands-agents/docs/blob/main/adrs/README.md#adr-template). + +**Tips for effective proposals:** + +- Focus on the problem first—solution comes second +- Include concrete examples showing current pain and proposed improvement +- Be open to feedback—the best solution might differ from your initial idea +- Align with our [development tenets](https://github.com/strands-agents/docs/blob/main/team/TENETS.md) diff --git a/docs/contribute/index.md b/docs/contribute/index.md new file mode 100644 index 00000000..6f687a52 --- /dev/null +++ b/docs/contribute/index.md @@ -0,0 +1,29 @@ +# Contribute + +There are different ways to contribute to the Strands ecosystem. You can improve the core SDK, help with documentation, or build extensions that others can use. + +## Core SDK + +Contributions that improve the SDK powering every Strands agent. + +| I want to... | What it involves | Guide | +|--------------|------------------|-------| +| Fix a bug | Check for existing issues, submit a PR with tests that verify your fix | [Core SDK](./contributing/core-sdk.md) | +| Add a new feature | For small changes, open an issue first. For larger features, go through the ADR process to align on direction | [Feature Proposals](./contributing/feature-proposals.md) | +| Improve the docs | Fix typos, clarify explanations, add examples, or write new guides | [Documentation](./contributing/documentation.md) | + +## Extensions + +Tools, model providers, hooks, and session managers that extend Strands capabilities. You publish these as your own packages. + +| I want to... | What it involves | Guide | +|--------------|------------------|-------| +| Build an extension | Use our template to publish your own package on PyPI. Get listed in our community catalog | [Extensions](./contributing/extensions.md) | + +## Community resources + +- [Community Catalog](../community/community-packages.md) — Discover community-built extensions +- [GitHub Discussions](https://github.com/strands-agents/sdk-python/discussions) — Ask questions, share ideas +- [Roadmap](https://github.com/orgs/strands-agents/projects/8/views/1) — See what we're working on +- [Development Tenets](https://github.com/strands-agents/docs/blob/main/team/TENETS.md) — Principles that guide SDK design +- [Decision Records](https://github.com/strands-agents/docs/blob/main/team/DECISIONS.md) — Past design decisions with rationale diff --git a/mkdocs.yml b/mkdocs.yml index a6955abe..f431a7b1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -241,7 +241,13 @@ nav: - telegram: community/tools/strands-telegram.md - telegram-listener: community/tools/strands-telegram-listener.md - - Contribute ❤️: https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md + - Contribute ❤️: + - Overview: contribute/index.md + - Contribution Types: + - Core SDK: contribute/contributing/core-sdk.md + - Documentation: contribute/contributing/documentation.md + - Feature Proposals: contribute/contributing/feature-proposals.md + - Extensions: contribute/contributing/extensions.md - Python API: [] - TypeScript API: api-reference/typescript/index.html diff --git a/team/API_BAR_RAISING.md b/team/API_BAR_RAISING.md index 25590f4d..b9726320 100644 --- a/team/API_BAR_RAISING.md +++ b/team/API_BAR_RAISING.md @@ -1,8 +1,8 @@ -API Bar Raising +# API Bar Raising ## Introduction -API Bar-Raising is a mechanism intended to ensure the SDK maintains a high-quality, consistent, and future-proof API surface across the SDK when developing new features, while conforming to our expectations and [tenets for the SDK](https://github.com/strands-agents/docs/blob/main/team/TENETS.md). It **is** intended to act as a quality gate while attempting to minimize the friction of integrating new features into the SDK. +API Bar-Raising is a mechanism intended to ensure the SDK maintains a high-quality, consistent, and future-proof API surface across the SDK when developing new features, while conforming to our expectations and [tenets for the SDK](./TENETS.md). It **is** intended to act as a quality gate while attempting to minimize the friction of integrating new features into the SDK. The process focuses exclusively on public API design and customer-facing contracts—not implementation details or internal/private APIs. @@ -33,8 +33,8 @@ The API reviewer focuses exclusively on customer usage and the public API—not **Key questions to ask:** -- Does it conform to the [SDK tenets](https://github.com/strands-agents/docs/blob/main/team/TENETS.md)? -- Does it conform to the [Decision Records](https://github.com/strands-agents/docs/blob/main/team/DECISIONS.md)? +- Does it conform to the [SDK tenets](./TENETS.md)? +- Does it conform to the [Decision Records](./DECISIONS.md)? - If extensibility is a goal: - What is customizable and what is not? - Is it the proper level of abstraction? @@ -42,7 +42,7 @@ The API reviewer focuses exclusively on customer usage and the public API—not - Are the default parameters/behavior the most common? - If not, why did we choose them? -If an API review session yields a decision that can guide future API designs, [document it as a decision record](https://github.com/strands-agents/docs/pull/420). This is a sign of successful bar-raising. +If an API review session yields a decision that can guide future API designs, document it as a decision record. This is a sign of successful bar-raising. ### API Proposer Role @@ -73,4 +73,4 @@ To indicate that a PR requires API review, add the `needs-api-review` label. Onc For **larger features** that require more extensive discussion, schedule a meeting with your designated API reviewer to walk through use cases and API design decisions. These sessions can be formal or informal depending on feature complexity. Individual or medium-sized features can take 30-60 minutes of discussion, while larger features may benefit from multiple sessions throughout the design and implementation phases. The goal is to catch potential issues early while maintaining fast iterations on feature development. -Alternatively, **team consensus** can be used in lieu of a designated API reviewer. This approach works well when broad alignment is needed or when the API introduces patterns the whole team will build upon - for example, the BiDirectional agents API benefited from team-wide discussion. However, use team consensus judiciously for APIs where the investment is justified, as a 30-minute meeting with 10 people represents 5 hours of collective effort. \ No newline at end of file +Alternatively, **team consensus** can be used in lieu of a designated API reviewer. This approach works well when broad alignment is needed or when the API introduces patterns the whole team will build upon - for example, the BiDirectional agents API benefited from team-wide discussion. However, use team consensus judiciously for APIs where the investment is justified, as a 30-minute meeting with 10 people represents 5 hours of collective effort. diff --git a/team/README.md b/team/README.md new file mode 100644 index 00000000..32e93cac --- /dev/null +++ b/team/README.md @@ -0,0 +1,21 @@ +# Team Documentation + +This folder contains internal documentation about how the Strands team builds and maintains the SDK. These documents help contributors understand our design philosophy and decision-making process. + +## Contents + +| Document | Description | +|----------|-------------| +| [TENETS.md](./TENETS.md) | Core principles that guide SDK design and implementation | +| [DECISIONS.md](./DECISIONS.md) | Record of design and API decisions with rationale | +| [API_BAR_RAISING.md](./API_BAR_RAISING.md) | Process for reviewing and approving API changes | + +## For Contributors + +When proposing changes to the SDK, please review these documents to understand: + +- **Tenets** — The principles your contribution should align with +- **Decisions** — Past decisions that may inform your approach +- **API Bar Raising** — The review process for API changes + +If your contribution results in a new decision that could guide future work, consider adding it to [DECISIONS.md](./DECISIONS.md). diff --git a/team/TENETS.md b/team/TENETS.md index d6a8217a..aa4a262e 100644 --- a/team/TENETS.md +++ b/team/TENETS.md @@ -1,4 +1,4 @@ -## Development Tenets +# Development Tenets Our team follows these core principles when designing and implementing features. These tenets help us make consistent decisions, resolve trade-offs, and maintain the quality and coherence of the SDK. When contributing, please consider how your changes align with these principles: @@ -6,7 +6,7 @@ Our team follows these core principles when designing and implementing features. 2. **Extensible by design:** We allow for as much configuration as possible, from hooks to model providers, session managers, tools, etc. We meet customers where they are with flexible extension points that are simple to integrate with. 3. **Composability:** Primitives are building blocks with each other. Each feature of Strands is developed with all other features in mind, they are consistent and complement one another. 4. **The obvious path is the happy path:** Through intuitive naming, helpful error messages, and thoughtful API design, we guide developers toward correct patterns and away from common pitfalls. -5. **We are accessible to humans and agents:** Strands is designed for both humans and AI to understand equally well. We don’t take shortcuts on curated DX for humans and we go the extra mile to make sure coding assistants can help you use those interfaces the right way. +5. **We are accessible to humans and agents:** Strands is designed for both humans and AI to understand equally well. We don't take shortcuts on curated DX for humans and we go the extra mile to make sure coding assistants can help you use those interfaces the right way. 6. **Embrace common standards:** We respect what came before, and do not want to reinvent something that is already widely adopted or done better. When proposing solutions or reviewing code, we reference these principles to guide our decisions. If two approaches seem equally valid, we choose the one that best aligns with our tenets. From 715b18f5ac73e3fb341069066ad3fb4b0bd6bcd8 Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Mon, 26 Jan 2026 22:43:23 -0500 Subject: [PATCH 05/11] docs: fix setup instructions and improve contributing guides - Fix docs setup: use pip install -e . instead of requirements.txt - Add hatch run prepare and npm run check as single commands for quality checks - Add 'Find something to work on' section with ready-for-contribution links - Link feature proposals from breaking changes guidance - Rename template repo to strands-python-extension-template --- docs/contribute/contributing/core-sdk.md | 54 ++++++++++++------- docs/contribute/contributing/documentation.md | 6 ++- docs/contribute/contributing/extensions.md | 11 +--- 3 files changed, 42 insertions(+), 29 deletions(-) diff --git a/docs/contribute/contributing/core-sdk.md b/docs/contribute/contributing/core-sdk.md index d63318f6..1bc7b4e6 100644 --- a/docs/contribute/contributing/core-sdk.md +++ b/docs/contribute/contributing/core-sdk.md @@ -18,8 +18,8 @@ We welcome contributions that improve the SDK for everyone. Focus on changes tha Some contributions don't fit the core SDK. Understanding this upfront saves you time and helps us maintain focus on what matters most. -- **Large refactors without prior discussion** — Major architectural changes require RFC approval -- **Breaking changes without RFC approval** — We maintain backward compatibility carefully +- **Large refactors without prior discussion** — Major architectural changes require a [feature proposal](./feature-proposals.md) +- **Breaking changes without approval** — We maintain backward compatibility carefully; breaking changes require a [feature proposal](./feature-proposals.md) - **External tools** — [Build your own extension](./extensions.md) instead for full ownership - **Changes without tests** — Tests ensure quality and prevent regressions (documentation changes excepted) - **Niche features** — Features serving narrow use cases belong in extensions @@ -62,6 +62,12 @@ Let's get your local environment ready for development. This process differs sli hatch fmt --formatter # Auto-format code with ruff ``` + To run all quality checks at once (format, lint, and tests across all Python versions), use the prepare script. + + ```bash + hatch run prepare # Run all checks before committing + ``` + **Development tips:** - Use `hatch run test-integ` to run integration tests with real model providers @@ -78,21 +84,26 @@ Let's get your local environment ready for development. This process differs sli npm install ``` - The TypeScript SDK uses npm for dependency management and includes automated quality checks through git hooks. - - Install the git hooks for automatic quality checks. + The TypeScript SDK uses npm for dependency management and includes automated quality checks through git hooks. The `prepare` script builds the project and sets up Husky git hooks. ```bash npm run prepare ``` - Now let's verify everything works. + Now let's verify everything works by running all quality checks. + + ```bash + npm run check # Run all checks (lint, format, type-check, tests) + ``` + + You can also run individual checks. ```bash npm test # Run unit tests npm run test:coverage # Run with coverage (80%+ required) npm run lint # Run ESLint npm run format # Format code with Prettier + npm run type-check # TypeScript type checking ``` **Development tips:** @@ -101,20 +112,27 @@ Let's get your local environment ready for development. This process differs sli - Run `npm run test:all` to test in both Node.js and browser environments - Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-typescript/blob/main/CONTRIBUTING.md) for detailed requirements +## Find something to work on + +Looking for a place to start? Check our issues labeled "ready for contribution"—these are well-defined and ready for community work. + +- [Python SDK issues](https://github.com/strands-agents/sdk-python/issues?q=is%3Aissue+state%3Aopen+label%3A%22ready+for+contribution%22) +- [TypeScript SDK issues](https://github.com/strands-agents/sdk-typescript/issues?q=is%3Aissue+state%3Aopen+label%3A%22ready+for+contribution%22) + +Before starting work on any issue, check if someone is already assigned or working on it. + ## Submit your contribution -Once you've made your changes, here's how to submit them for review. Following these steps helps us review your contribution quickly. - -1. **Check existing issues** to see if your bug or feature is already tracked or being worked on -2. **Open an issue first** for non-trivial changes to discuss your approach and get feedback -3. **Fork and create a branch** with a descriptive name like `fix/session-memory-leak` or `feat/add-hooks-support` -4. **Write tests** for your changes—tests are required for all code changes -5. **Run quality checks** before committing to ensure everything passes: - - Python: `hatch fmt --formatter && hatch fmt --linter && hatch test` - - TypeScript: `npm run format && npm run lint && npm test` -6. **Use [conventional commits](https://www.conventionalcommits.org/)** like `fix: resolve memory leak in session manager` or `feat: add streaming support to tools` -7. **Submit a pull request** referencing the issue number in the description -8. **Respond to feedback** — we'll review within 3 days and may request changes +Once you've made your changes, here's how to submit them for review. + +1. **Fork and create a branch** with a descriptive name like `fix/session-memory-leak` or `feat/add-hooks-support` +2. **Write tests** for your changes—tests are required for all code changes +3. **Run quality checks** before committing to ensure everything passes: + - Python: `hatch run prepare` + - TypeScript: `npm run check` +4. **Use [conventional commits](https://www.conventionalcommits.org/)** like `fix: resolve memory leak in session manager` or `feat: add streaming support to tools` +5. **Submit a pull request** referencing the issue number in the description +6. **Respond to feedback** — we'll review within a few days and may request changes The pre-commit hooks help catch issues before you push, but you can also run checks manually anytime. diff --git a/docs/contribute/contributing/documentation.md b/docs/contribute/contributing/documentation.md index a9950f86..893504cb 100644 --- a/docs/contribute/contributing/documentation.md +++ b/docs/contribute/contributing/documentation.md @@ -30,8 +30,12 @@ Let's get the docs running locally so you can preview your changes as you work. git clone https://github.com/strands-agents/docs.git cd docs +# Create and activate virtual environment +python -m venv .venv +source .venv/bin/activate # On Windows use: .venv\Scripts\activate + # Install dependencies -pip install -r requirements.txt +pip install -e . # Start the local development server mkdocs serve diff --git a/docs/contribute/contributing/extensions.md b/docs/contribute/contributing/extensions.md index 01e8aa23..b5f6ba23 100644 --- a/docs/contribute/contributing/extensions.md +++ b/docs/contribute/contributing/extensions.md @@ -17,7 +17,7 @@ When you build something useful, publishing it as your own package gives you con We provide a GitHub template with everything pre-configured—package structure, CI/CD, testing setup, and publishing workflows. -1. **Use the template** — Go to [strands-agents/strands-template](https://github.com/strands-agents/strands-template) and click "Use this template" +1. **Use the template** — Go to [strands-agents/strands-python-extension-template](https://github.com/strands-agents/strands-python-extension-template) and click "Use this template" 2. **Run setup** — Clone your repo and run `python setup_template.py` 3. **Add your code** — Implement your extension 4. **Publish** — Create a GitHub release to automatically publish to PyPI @@ -109,12 +109,3 @@ After publishing: 2. **Submit to catalog** — Get listed in our [community catalog](../../community/community-packages.md) → [Get Featured guide](../../community/get-featured.md) - -## Tips for quality extensions - -| Principle | How to apply | -|-----------|--------------| -| Clear naming | Use verb-noun pairs like `search_database`, not `query` | -| Detailed docstrings | Include parameter explanations, examples, and edge cases | -| Error handling | Catch specific exceptions and provide actionable messages | -| Type hints | Use type annotations on all parameters and returns | From 219ea10acd7ceb4387e70e7e994b0796438a8f4c Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Mon, 26 Jan 2026 22:51:41 -0500 Subject: [PATCH 06/11] docs: add code of conduct and security reporting links --- docs/contribute/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 6f687a52..11d1b890 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -27,3 +27,5 @@ Tools, model providers, hooks, and session managers that extend Strands capabili - [Roadmap](https://github.com/orgs/strands-agents/projects/8/views/1) — See what we're working on - [Development Tenets](https://github.com/strands-agents/docs/blob/main/team/TENETS.md) — Principles that guide SDK design - [Decision Records](https://github.com/strands-agents/docs/blob/main/team/DECISIONS.md) — Past design decisions with rationale +- [Code of Conduct](https://aws.github.io/code-of-conduct) — Community guidelines +- [Report a Security Issue](https://aws.amazon.com/security/vulnerability-reporting/) — For vulnerabilities, not public issues From 2f49e68a0ec643a7cd911db696380c0ae5f7aaa9 Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Mon, 26 Jan 2026 22:56:09 -0500 Subject: [PATCH 07/11] fix: simplify add package section in community packages --- docs/community/community-packages.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index d7a14efd..55a9a518 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -52,16 +52,8 @@ Platform integrations help you connect Strands agents with external services and ## Add your package -Built something useful? We'd love to list it here. Publishing your package to the catalog makes it discoverable to thousands of developers. +Built something useful? We'd love to feature it here. -**Requirements:** +→ [Extensions guide](../contribute/contributing/extensions.md) — How to build and publish your package -1. **Publish your package to PyPI** — See our [extensions guide](../contribute/contributing/extensions.md) for step-by-step instructions -2. **Add the `strands-agents` topic** to your GitHub repository so developers can find you -3. **Submit a request** using our [content addition template](https://github.com/strands-agents/docs/issues/new?template=content_addition.yml) with: - - Package name and PyPI link - - Clear description of what it does - - Usage examples showing basic integration - - Documentation link (README or dedicated docs) - -See our [Get Featured](./get-featured.md) guide for step-by-step instructions on adding your package to the docs. +→ [Get Featured guide](./get-featured.md) — How to get listed in this catalog From 0c6d5044a035d17b686affb2522cd1e4c1875b7b Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Tue, 27 Jan 2026 14:50:20 -0500 Subject: [PATCH 08/11] docs: simplify extensions guide and update contribute section - Reframe extensions.md as publishing guide, not building guide - Slim down to essentials with link to template - Update index.md to match new framing - Fix arrow link patterns in community-packages.md --- docs/community/community-packages.md | 4 +- docs/contribute/contributing/extensions.md | 119 +++++---------------- docs/contribute/index.md | 4 +- 3 files changed, 31 insertions(+), 96 deletions(-) diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index 55a9a518..f28fe307 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -54,6 +54,4 @@ Platform integrations help you connect Strands agents with external services and Built something useful? We'd love to feature it here. -→ [Extensions guide](../contribute/contributing/extensions.md) — How to build and publish your package - -→ [Get Featured guide](./get-featured.md) — How to get listed in this catalog +See the [Extensions guide](../contribute/contributing/extensions.md) for how to build and publish your package, and the [Get Featured guide](./get-featured.md) for how to get listed in this catalog. diff --git a/docs/contribute/contributing/extensions.md b/docs/contribute/contributing/extensions.md index b5f6ba23..e60b556b 100644 --- a/docs/contribute/contributing/extensions.md +++ b/docs/contribute/contributing/extensions.md @@ -1,111 +1,48 @@ -# Building Extensions +# Publishing extensions -Extensions are tools, model providers, hooks, and session managers that extend Strands capabilities. You publish these as your own packages on PyPI. +You've built a tool that calls your company's internal API. Or a model provider for a regional LLM service. Or a session manager that persists to Redis. It works great for your project—now you want to share it with others. -## Why build an extension +This guide walks you through packaging and publishing your Strands components so other developers can install them with `pip install`. -When you build something useful, publishing it as your own package gives you control and visibility. +## Why publish -| Benefit | Description | -|---------|-------------| -| **Ownership** | You control the roadmap, features, and release schedule | -| **Speed** | Release updates immediately without waiting for core SDK releases | -| **Credit** | Your name and contribution are front and center | -| **Discoverability** | Listed in our community catalog for thousands of developers to find | +When you build a useful component, you have two choices: keep it in your project, or publish it as a package. -## Quick start +Publishing makes sense when your component solves a problem others face too. A Slack integration, a database session manager, a provider for a popular LLM service—these help the broader community. Publishing also means you own the package. You control when to release updates, what features to add, and how to prioritize bugs. -We provide a GitHub template with everything pre-configured—package structure, CI/CD, testing setup, and publishing workflows. +Your package can get listed in our [community catalog](../../community/community-packages.md), making it discoverable to developers looking for exactly what you built. -1. **Use the template** — Go to [strands-agents/strands-python-extension-template](https://github.com/strands-agents/strands-python-extension-template) and click "Use this template" -2. **Run setup** — Clone your repo and run `python setup_template.py` -3. **Add your code** — Implement your extension -4. **Publish** — Create a GitHub release to automatically publish to PyPI +## What you can publish -## Step-by-step guide +Strands has several extension points. Each serves a different purpose in the agent lifecycle. -### Prerequisites +| Component | Purpose | Learn more | +|-----------|---------|------------| +| **Tools** | Add capabilities to agents—call APIs, access databases, interact with services | [Custom tools](../../user-guide/concepts/tools/python-tools.md) | +| **Model providers** | Integrate LLM APIs beyond the built-in providers | [Custom model providers](../../user-guide/concepts/model-providers/custom_model_provider.md) | +| **Hook providers** | React to agent lifecycle events like invocations, tool calls, and model calls | [Hooks](../../user-guide/concepts/agents/hooks.md) | +| **Session managers** | Persist conversations to external storage for resumption or sharing | [Session management](../../user-guide/concepts/agents/session-management.md) | +| **Conversation managers** | Control how message history grows—trim old messages or summarize context | [Conversation management](../../user-guide/concepts/agents/conversation-management.md) | -- **GitHub account** — For hosting your repository and CI/CD -- **PyPI account** — Create one at [pypi.org/account/register](https://pypi.org/account/register/) +Tools are the most common extension type. They let agents interact with specific services like Slack, databases, or internal APIs. -### Create your repository +## Get started -Go to [strands-agents/strands-template](https://github.com/strands-agents/strands-template) and click "Use this template". +We provide a Python template that handles the boilerplate: package structure, CI/CD workflows, testing setup, and automatic PyPI publishing on release. -Clone it locally and run the setup script: +Use [strands-agents/strands-python-extension-template](https://github.com/strands-agents/strands-python-extension-template) to create your repository. Click "Use this template" on GitHub. The template includes skeleton files for all extension types, a setup script that configures your package metadata, and GitHub Actions workflows for testing and publishing. -```bash -git clone https://github.com/YOUR_USERNAME/your-repo-name -cd your-repo-name -python setup_template.py -``` +The template README walks through each step: running the setup script, adding your code, configuring PyPI trusted publishing, and creating releases. -The script prompts for your package name, author info, and description. - -### Implement your extension - -The template includes skeleton implementations for all extension types: - -| 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` | Hook provider | React to agent lifecycle events | -| `session_manager.py` | Session manager | Persist conversations across restarts | - -**Keep what you need, delete the rest.** Most packages only need one or two components. - -For implementation guidance: - -- [Creating custom tools](../../user-guide/concepts/tools/custom-tools.md) -- [Custom model providers](../../user-guide/concepts/model-providers/custom_model_provider.md) -- [Hooks](../../user-guide/concepts/agents/hooks.md) -- [Session management](../../user-guide/concepts/agents/session-management.md) - -### Test your code - -```bash -pip install -e ".[dev]" -hatch run prepare # Runs format, lint, typecheck, test -``` - -### Configure PyPI publishing - -The template includes a GitHub Actions workflow that publishes to PyPI on release. - -To enable it, configure PyPI trusted publishing: - -1. Go to [PyPI](https://pypi.org) → Your projects → Publishing -2. Add a new pending publisher with your GitHub repo details -3. Set environment name to `pypi` - -### Publish - -1. Go to your repository on GitHub -2. Click "Releases" → "Create a new release" -3. Create a tag following [semantic versioning](https://semver.org/) (e.g., `v0.1.0`) -4. Click "Publish release" - -GitHub Actions builds and publishes your package. Anyone can now install it: - -```bash -pip install strands-yourname -``` - -## Naming conventions - -| Item | Convention | Example | -|------|------------|---------| -| PyPI package | `strands-{name}` | `strands-slack` | -| Python module | `strands_{name}` | `strands_slack` | -| GitHub topic | `strands-agents` | For discoverability | +!!! info "TypeScript" + A TypeScript extension template is coming soon. ## Get discovered -After publishing: +Publishing to PyPI makes your package installable, but developers need to find it first. + +First you can add the `strands-agents` topic to your GitHub repository, so developers browsing GitHub can find Strands-related projects. Go to your repo settings, click the gear icon next to "About", and add topics. -1. **Add GitHub topics** — Add `strands-agents` to your repository -2. **Submit to catalog** — Get listed in our [community catalog](../../community/community-packages.md) +Additionally you can submit your package to our [community catalog](../../community/community-packages.md), which lists extensions the community has built. Getting listed puts your package in front of developers actively looking for Strands extensions. -→ [Get Featured guide](../../community/get-featured.md) +See the [Get Featured guide](../../community/get-featured.md) for step-by-step instructions on submitting your package. diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 11d1b890..1242dd31 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -14,11 +14,11 @@ Contributions that improve the SDK powering every Strands agent. ## Extensions -Tools, model providers, hooks, and session managers that extend Strands capabilities. You publish these as your own packages. +Share your tools, model providers, hooks, and session managers with the community by publishing them as packages. | I want to... | What it involves | Guide | |--------------|------------------|-------| -| Build an extension | Use our template to publish your own package on PyPI. Get listed in our community catalog | [Extensions](./contributing/extensions.md) | +| Publish an extension | Package your component and publish to PyPI so others can use it | [Publishing Extensions](./contributing/extensions.md) | ## Community resources From 696d34309de1994acfdfdaa338a287431c146480 Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Tue, 27 Jan 2026 15:11:26 -0500 Subject: [PATCH 09/11] fix(contribute): small improvements --- docs/community/community-packages.md | 2 +- docs/contribute/contributing/core-sdk.md | 2 +- docs/contribute/contributing/documentation.md | 3 +-- docs/contribute/contributing/extensions.md | 15 +++++---------- docs/contribute/index.md | 4 ++-- 5 files changed, 10 insertions(+), 16 deletions(-) diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index f28fe307..182e9991 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -2,7 +2,7 @@ The Strands community has built tools and integrations for a variety of use cases. This catalog helps you discover what's available and find packages that solve your specific needs. -Browse by category below to find tools, model providers, session managers, and platform integrations built by the community. You can also browse community projects dynamically at [strands.my](https://strands.my/). +Browse by category below to find tools, model providers, session managers, and platform integrations built by the community. !!! info "Community maintained" These packages are maintained by their authors, not the Strands team. Review packages before using them in production. Quality and support may vary. diff --git a/docs/contribute/contributing/core-sdk.md b/docs/contribute/contributing/core-sdk.md index 1bc7b4e6..7d49973e 100644 --- a/docs/contribute/contributing/core-sdk.md +++ b/docs/contribute/contributing/core-sdk.md @@ -19,7 +19,7 @@ We welcome contributions that improve the SDK for everyone. Focus on changes tha Some contributions don't fit the core SDK. Understanding this upfront saves you time and helps us maintain focus on what matters most. - **Large refactors without prior discussion** — Major architectural changes require a [feature proposal](./feature-proposals.md) -- **Breaking changes without approval** — We maintain backward compatibility carefully; breaking changes require a [feature proposal](./feature-proposals.md) +- **Breaking changes without approval** — We maintain backward compatibility carefully. Breaking changes require a [feature proposal](./feature-proposals.md) - **External tools** — [Build your own extension](./extensions.md) instead for full ownership - **Changes without tests** — Tests ensure quality and prevent regressions (documentation changes excepted) - **Niche features** — Features serving narrow use cases belong in extensions diff --git a/docs/contribute/contributing/documentation.md b/docs/contribute/contributing/documentation.md index 893504cb..c1033af4 100644 --- a/docs/contribute/contributing/documentation.md +++ b/docs/contribute/contributing/documentation.md @@ -61,7 +61,7 @@ The submission process varies based on the size of your change. Small fixes can ## Style guidelines -We aim for documentation that teaches, not just describes. A reader should finish understanding the "why" before the "how." This section covers our voice, writing style, and code example conventions. +We aim for documentation that teaches, not just describes. A reader finishes understanding the "why" before the "how." This section covers our voice, writing style, and code example conventions. ### Voice and tone @@ -115,4 +115,3 @@ agent = Agent( agent("What's the weather like?") ``` -For more detailed style guidance, see the [complete documentation style guide](https://github.com/strands-agents/docs/blob/main/STYLE_GUIDE.md) in the docs repository. diff --git a/docs/contribute/contributing/extensions.md b/docs/contribute/contributing/extensions.md index e60b556b..c656b6af 100644 --- a/docs/contribute/contributing/extensions.md +++ b/docs/contribute/contributing/extensions.md @@ -18,7 +18,7 @@ Strands has several extension points. Each serves a different purpose in the age | Component | Purpose | Learn more | |-----------|---------|------------| -| **Tools** | Add capabilities to agents—call APIs, access databases, interact with services | [Custom tools](../../user-guide/concepts/tools/python-tools.md) | +| **Tools** | Add capabilities to agents—call APIs, access databases, interact with services | [Custom tools](../../user-guide/concepts/tools/custom-tools.md) | | **Model providers** | Integrate LLM APIs beyond the built-in providers | [Custom model providers](../../user-guide/concepts/model-providers/custom_model_provider.md) | | **Hook providers** | React to agent lifecycle events like invocations, tool calls, and model calls | [Hooks](../../user-guide/concepts/agents/hooks.md) | | **Session managers** | Persist conversations to external storage for resumption or sharing | [Session management](../../user-guide/concepts/agents/session-management.md) | @@ -28,21 +28,16 @@ Tools are the most common extension type. They let agents interact with specific ## Get started +!!! info "TypeScript" + A TypeScript extension template is coming soon. + We provide a Python template that handles the boilerplate: package structure, CI/CD workflows, testing setup, and automatic PyPI publishing on release. Use [strands-agents/strands-python-extension-template](https://github.com/strands-agents/strands-python-extension-template) to create your repository. Click "Use this template" on GitHub. The template includes skeleton files for all extension types, a setup script that configures your package metadata, and GitHub Actions workflows for testing and publishing. The template README walks through each step: running the setup script, adding your code, configuring PyPI trusted publishing, and creating releases. -!!! info "TypeScript" - A TypeScript extension template is coming soon. ## Get discovered -Publishing to PyPI makes your package installable, but developers need to find it first. - -First you can add the `strands-agents` topic to your GitHub repository, so developers browsing GitHub can find Strands-related projects. Go to your repo settings, click the gear icon next to "About", and add topics. - -Additionally you can submit your package to our [community catalog](../../community/community-packages.md), which lists extensions the community has built. Getting listed puts your package in front of developers actively looking for Strands extensions. - -See the [Get Featured guide](../../community/get-featured.md) for step-by-step instructions on submitting your package. +Once you publish, the next step is getting other developers to discover and use your package. See the [Get Featured guide](../../community/get-featured.md) for how to add GitHub topics and get listed in our community catalog. diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 1242dd31..467807d7 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -4,7 +4,7 @@ There are different ways to contribute to the Strands ecosystem. You can improve ## Core SDK -Contributions that improve the SDK powering every Strands agent. +These contributions improve the SDK powering every Strands agent. | I want to... | What it involves | Guide | |--------------|------------------|-------| @@ -14,7 +14,7 @@ Contributions that improve the SDK powering every Strands agent. ## Extensions -Share your tools, model providers, hooks, and session managers with the community by publishing them as packages. +You can share your tools, model providers, hooks, and session managers with the community by publishing them as packages. | I want to... | What it involves | Guide | |--------------|------------------|-------| From 4ff13716acc84a46b323094ecfdb697ac687638c Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Thu, 29 Jan 2026 15:04:52 -0500 Subject: [PATCH 10/11] fix: remove adrs folder --- adrs/0001-extensibility-ecosystem-strategy.md | 302 ----------- adrs/0002-community-health-strategy.md | 475 ------------------ adrs/README.md | 88 ---- 3 files changed, 865 deletions(-) delete mode 100644 adrs/0001-extensibility-ecosystem-strategy.md delete mode 100644 adrs/0002-community-health-strategy.md delete mode 100644 adrs/README.md diff --git a/adrs/0001-extensibility-ecosystem-strategy.md b/adrs/0001-extensibility-ecosystem-strategy.md deleted file mode 100644 index e76a5ace..00000000 --- a/adrs/0001-extensibility-ecosystem-strategy.md +++ /dev/null @@ -1,302 +0,0 @@ -# Strands Agents: Extensibility & Ecosystem Strategy - -> This document is a part of community/contributor management series. See [Strands Agents: Contributor Experience Analysis](./contributor-story.md), [Strands Agents: Community Health Strategy & Playbook](./community-health.md), [Strands Agents: Extensibility & Ecosystem Strategy](./extensibility.md), and [Strands Agents: Task Backlog [Community & Ecosystem]](./task-backlog.md) - -## Introduction - -This document defines our strategy for growing the Strands ecosystem—tools, integrations, and extensions built by the community. It builds on the [Contributor Story Analysis](./contributor-story.md) which identified tool publishing friction as a major problem, and the [Community Health Strategy](./community-health.md) which established our overall open source goals. - -**The problem:** The diversity of extensions is one of the most critical factors when choosing an agentic SDK. If we have tools for your use case vs a competitor where you need to write everything, the choice is clear. But today: -- Our tools repo has 94% external PRs that we're not accepting -- Publishing your own package requires hours of setup -- Even after publishing, there's no way for users to discover your tool - -**The goal:** Make it easy for developers to extend Strands and for users to discover those extensions—without taking on maintenance burden we can't sustain. - ---- - -## Part 1: Extension Points in Strands - -Before discussing strategy, let's be clear about what can be extended. Every idea here (templates, catalog, etc) applies to all extension types. - -**Tools** are the most common extension point. A tool is a function the agent can call—search the web, query a database, send an email. Tools are where most community interest lies. - -**Model Providers** let you connect Strands to different LLMs. We support Bedrock, Anthropic, OpenAI, Ollama, and others. Community members might want to add providers for other services. - -**Hook Providers** allow custom logic at various points in the agent lifecycle—before/after tool calls, on errors, etc. These are useful for logging, monitoring, or custom behaviors. - -**Session Managers** handle conversation state persistence. The default is in-memory, but you might want Redis, DynamoDB, or something else. - -For this document, we'll focus primarily on tools since that's where the demand is. The same patterns apply to other extension types. - ---- - -## Part 2: Current State - -### The Tools Repository Problem - -The tools repo tells a clear story: -- **94% of open PRs are from contributors** -- **Oldest open PR is 190+ days old** -- **Only 40.5% of issues get a maintainer response** - -Contributors want to add tools. We're not accepting them. The PRs sit open for months, contributors get frustrated, and our metrics look terrible. - -**Why we don't accept external tools:** - -We had a CVE for a MongoDB tool that a community member submitted. The team doesn't have enough expertise to fully understand and test it. We can't take security responsibility for code we can't verify. - -This isn't about gatekeeping—it's about honesty. We can't maintain tools for services we don't use, APIs we don't have keys for, and domains we don't understand. - -### The Publishing Friction Problem - -The alternative we offer—publish your own package—requires: -1. Create a GitHub repository -2. Set up a PyPI account -3. Configure GitHub Actions for CI/CD -4. Set up package structure (pyproject.toml, src layout) -5. Write documentation -6. Configure secrets for publishing - -For a 20-line tool, this is absurd. The overhead kills contribution. - -### The Discoverability Problem - -Even if someone publishes a tool, **no one can find it**. There's no catalog, no registry, no search. A developer looking for a Slack tool has no way to know one exists unless they happen to find it on PyPI or GitHub. - -This is the worst outcome: we've pushed contribution outside our repos, but we haven't solved the discovery problem that made being in our repos valuable in the first place. - ---- - -## Part 3: Strategy Options - -We considered several approaches before landing on our recommendation. - -### Option A: "Bring Your Code, We Vend It" (Rejected) - -The idea: create a repo where people dump their code, we publish whatever passes CI. - -**Pros:** -- Lowest friction for contributors -- Tools get the "strands" stamp -- Easy distribution via strands-tools package - -**Cons:** -- AppSec and leadership will push back—we'd be publishing code we haven't reviewed -- Even with explicit disclaimers ("we take no responsibility"), this requires leadership buy-in -- We become responsible for security issues in code we don't understand -- Maintenance burden scales with contributions -- One bad tool damages the whole package's reputation - -**Decision:** Rejected. The security and maintenance risks are too high, and getting leadership approval would be difficult. - -### Option B: GitHub Template + Self-Publish - -The idea: provide a template repository with everything pre-configured. Contributors clone it, add their code, configure secrets, and publish to their own PyPI namespace. - -**Pros:** -- Dramatically reduces publishing friction -- We don't maintain the code—authors do -- Clear ownership and responsibility -- Authors can iterate at their own pace - -**Cons:** -- Tools don't get "strands" branding -- Requires solving discoverability separately -- Some friction remains (PyPI account, secrets) - -**Decision:** This is our primary approach. - -### Option C: Tiered Approach (Recommended) - -This is the recommended approach. We need a set of tools we provide—this is critical for people to get started and test their use cases. - -**Why a separate tools repo?** Dependency management. Each tool is essentially another client/dependency. Keeping them separate from the core SDK keeps the SDK lean. - -**Tier 1 - Core:** We maintain, we test, we support. Tools critical for getting started with the SDK. Lives in `strands-agents/tools`. - -**Tier 2 - Partner:** Third parties maintain, we highlight in catalog with a "Partner" label. For major integrations (AWS services, popular APIs). - -**Tier 3 - Community:** Catalog listing only. We display their README as-is (similar to strands.my). We don't maintain or endorse, just make discoverable. - -**Pros:** -- Allows us to highlight important integrations -- Clear expectations at each tier -- Scales with ecosystem growth - -**Cons:** -- More complex to manage -- Tier 2 requires partnership agreements - -**Decision:** This is our target state. Start with Template + Catalog (Option B) to unblock contributors now, then build toward tiered approach. - ---- - -## Part 4: Template Implementation - -We need to provide scaffolding so contributors can publish extensions without hours of setup. - -### Recommendation: Template CLI - -CLI tool that generates projects from parameters: - -```bash -uvx strands-create tool --name slack --author "Your Name" -``` - -**Pros:** Best DX, handles naming automatically, no cleanup -**Cons:** Need to build and maintain CLI - -**Existing work:** Tool template already exists at [mkmeral/strands-tool-template](https://github.com/mkmeral/strands-tool-template). CLI can use this as the underlying template for tools. - -**Rollout:** -1. Phase 1: CLI generates tool projects (covers 90% of demand) -2. Phase 2: Add model providers, hook providers, session managers -3. Phase 3: Interactive mode, optional features - -### Naming Convention - -- Package: `strands-tool-{name}` -- Import: `strands_tool_{name}` -- GitHub topic: `strands-tool` (for catalog discovery) - ---- - -## Part 5: Tools Catalog Strategy - -The template solves publishing friction. The catalog solves discoverability. - -### What It Is - -A page on strandsagents.com listing community tools. Users can browse, search, and find tools for their use cases. - -### Implementation Phases - -We have a parallel workstream to migrate our website to Astro/Starlight (see CMS Migration), which will enable dynamic content loading. We don't want to block discoverability on that migration. - -**Phase 1: Manual Catalog (Now - Stop-gap)** - -Manually populate a static list while CMS migration is in progress. - -Actions: -1. Search GitHub for repos with strands-tool topic or naming convention -2. Search PyPI for strands- packages -3. Curate results into a static markdown page in current MkDocs docs -4. Link from docs navigation - -Optional: Link to strands.my as an additional discovery option (community-built dashboard that auto-discovers strands- packages from PyPI). - -**Phase 2: Dynamic Catalog (Post-CMS Migration)** - -Once Astro/Starlight is live, leverage its remote content capabilities to: -- Query GitHub API for repos with strands-tool topic -- Query PyPI API for strands-* packages -- Auto-generate catalog entries -- Add tier labels (Core/Partner/Community) - -TODO: have some curation - -### Catalog Information - -For each tool, show: -- Name and description -- Author/maintainer -- GitHub repo link -- PyPI/npm link -- Install command -- Category/tags -- Tier label (Core/Partner/Community) - ---- - -## Part 6: Communication and Migration - -We need to clearly communicate the new path and update existing guidance. - -### Contributor Guidance - -We need a unified contributor guide in docs. For extensibility specifically: - -- How to use the template -- How to get listed in the catalog -- What we DO accept in core tools repo (bug fixes to existing tools, documentation) - -### Tools Repository Updates - -**README.md** - Add prominent notice: - -> **Note:** We don't accept external tools to this repository. To publish your own tool, use our [GitHub template](link) and publish to PyPI. Your tool can be listed in our [community catalog](link). - -**CONTRIBUTING.md** - Update to explain: -- Why we don't accept external tools (security, maintenance) -- How to use the template -- How to get listed in the catalog -- What we DO accept (bug fixes to existing tools, documentation) - -### Existing PRs - -For the 34 open PRs from contributors in tools: -1. Post a comment explaining the new path -2. Link to the template -3. Offer to help them migrate their code -4. Close PRs after reasonable time (2 weeks?) - -### Website Updates - -- Add "Ecosystem" or "Community Tools" section to docs -- Link from main navigation -- Include in "Getting Started" guides - ---- - -## Part 7: Implementation Roadmap - -| Phase | Goal | Tasks | -|-------|------|-------| -| **1: CLI** | Reduce publishing friction | Build `strands-create` CLI with tool template, Publish to PyPI, Write documentation for CLI usage, Test end-to-end flow | -| **2: Communication** | Redirect contributors to new path | Update tools repo README and CONTRIBUTING.md, Comment on open external PRs with new path, Close stale PRs with explanation | -| **3: Basic Catalog** | Solve discoverability | Create static catalog page on docs site, Add initial tools, Document how to request catalog listing | -| **4: Dynamic Catalog** | Scale discoverability | Define GitHub topic convention (`strands-tool`), Build GitHub API integration, Add search/filter functionality | -| **5: Ecosystem Growth** | Grow the flywheel | Promote community tools in docs, Highlight tools in release notes, Evaluate need for tiered approach | - ---- - -## Part 8: Contributor Guide - -We need a unified contributor guide in docs that explains how to develop and publish extensions. The guide should cover both Python and TypeScript (TypeScript SDK is experimental but growing). - -**For Tool Contributors (Python):** -1. Run `strands-create tool --name yourname --author "Your Name"` -2. Add your tool code -3. Push to GitHub -4. Add `PYPI_API_TOKEN` to repo secrets -5. Create a GitHub release → automatically publishes to PyPI -6. Add `strands-tool` topic to your repo for catalog visibility - -**For Tool Contributors (TypeScript):** -- Similar flow with npm instead of PyPI -- CLI support TBD (TypeScript SDK is experimental) - -**For Other Extension Types:** -- Model providers: `strands-create model-provider --name yourname` -- Hook providers: `strands-create hook-provider --name yourname` -- Session managers: `strands-create session-manager --name yourname` - -The guide should link to: -- The `strands-create` CLI (PyPI) -- The community catalog -- Example implementations -- Strands SDK documentation for extension interfaces - ---- - -## Open Questions - -1. **Partner tier:** How do we identify and label partners? Probably a "Partner" label in the catalog for major integration providers (Slack, databases, etc.). - ---- - -## TODO: - -- open source the docs, and refer there -- check GH wiki pages diff --git a/adrs/0002-community-health-strategy.md b/adrs/0002-community-health-strategy.md deleted file mode 100644 index 2e41c58b..00000000 --- a/adrs/0002-community-health-strategy.md +++ /dev/null @@ -1,475 +0,0 @@ -# Strands Agents: Community Health Strategy & Playbook - -> This document is a part of community/contributor management series. See [Strands Agents: Contributor Experience Analysis](./contributor-story.md), [Strands Agents: Community Health Strategy & Playbook](./community-health.md), [Strands Agents: Extensibility & Ecosystem Strategy](./extensibility.md), and [Strands Agents: Task Backlog [Community & Ecosystem]](./task-backlog.md) - -## Terminology - -| Term | Definition | -|------|------------| -| **Maintainers** | AWS team that owns Strands Agents SDK | -| **Contributors** | Anyone who contributes to the Strands ecosystem (e.g., publishing tools on PyPI) | -| **Core Contributors** | Contributors to core Strands packages (sdk-python, sdk-typescript, tools, docs) | -| **Customers** | End users of Strands — may overlap with contributors if they publish components | -| **Community** | Everyone: contributors, customers, etc. | - ---- - -## Introduction - -This document defines what we want from being open source and how we operationalize community health. It builds on the [Contributor Story Analysis](./contributor-story.md) which identified friction points in our contributor experience. While that document focused on understanding problems, this one focuses on strategy and solutions. - -The goal is to get team and leadership alignment on our open source goals, then provide an operational playbook for achieving them. - -### Where We Are Today - -Strands Agents is an open source AI agent SDK. We're growing fast (~5K stars) but our contributor experience metrics need improvement: - -- **External PRs take 10.6 days to merge** (industry benchmark: < 7 days) -- **Only 52% of external PRs get merged** (industry benchmark: > 60%) -- **Issue response time averages 13 days** (industry benchmark: < 2 days) -- **Only 4 repeat contributors** in sdk-python (we're not retaining core contributors) - -Before we can fix these problems, we need to answer a fundamental question: **What do we actually want from being open source?** The answer determines how much we invest and where. - ---- - -## Part 1: What We Want From Open Source - -We're already open source. The question isn't "should we be open source?" but "how do we make the best of it?" This section defines what we're optimizing for and the trade-offs we're making. - -### The Core Trade-off - -Being open source gives us: - -- **Adoption:** Zero friction. Developers pip install and start building. -- **Community Contributions:** We're a small team. Community extends our reach with bug fixes, docs, and specialized features. -- **Community Signals:** Direct feedback on what to prioritize. Users tell us about critical bugs, missing features, and emerging use cases. -- **Ecosystem:** Third parties build tools, integrations, content. Network effects make the platform stickier. -- **Trust:** Enterprises can audit our code. Transparency builds confidence. - -But it costs us: - -- **Opportunity Cost:** PR review, issue triage, documentation, support. Every hour on community is an hour not on features. -- **Community Trust Risk:** With a small team, slow responses damage reputation. If we're not reacting to community, we lose trust—and contributors. -- **Control:** Communities can fork if they disagree with direction. - -**The key question: How do we balance community investment with feature development?** - -### Goals (Prioritized) - -**P0: Adoption** - -Downloads, usage, stars. This is always the north star—everything else serves this goal. We can't directly move these numbers with community work alone, but it's what we're ultimately optimizing for. - -**P1: Ecosystem Growth** - -Tools, integrations, and extensions make the SDK sticky. A developer will choose the SDK that has tools for their use case. This is the flywheel—once kickstarted, it grows without us. We need both quality AND quantity here. - -**P2: Community Health & Contributor Experience** - -Community contributions scale our velocity. Bug fixes, docs, specialized features — work we couldn't prioritize ourselves. But this only works if contributors stick around. Fast responses, clear processes, good experience. If contributors have a bad experience, they don't come back—and they tell others. - -**P3: Community Signals** - -The community tells us what matters. Bug reports, feature requests, and discussions help us prioritize. This is a two-way relationship—we need to listen, not just broadcast. - -**P4: Trust and Brand** - -Enterprise adoption requires transparency. Being open source signals trustworthiness. This is table stakes, not a differentiator. - -### What We're NOT Optimizing For - -To be explicit about trade-offs: - -- **Not maximizing community size at any cost.** Quality matters. -- **Not accepting every PR.** We'll reject PRs that don't align with project direction. -- **Not providing 24/7 support.** We're not a support organization. - -### Success Metrics - -**Adoption Metrics (P0)** — The north star - -| Metric | Current | Notes | -|--------|---------|-------| -| GitHub Stars (sdk-python) | ~5K | Track trend | -| PyPI Downloads/month | 419,400 (weekly) | Track trend | -| npm Downloads/month | 11,084 (weekly) | Track trend | - -**Ecosystem Metrics (P1)** — The flywheel - -| Metric | Current | 6-Month Target | 12-Month Target | -|--------|---------|----------------|-----------------| -| Community Tools (listed on website) | 5 | 30 | 100 | -| Model Providers | 4 | 10 | 20 | -| Session Managers | 1 | 5 | 20 | - -**Community Health Metrics (P2)** — What we operationalize - -| Metric | Current | 6-Month Target | 12-Month Target | -|--------|---------|----------------|-----------------| -| PR First Response | 2.4 days | < 3 days | < 48h | -| PR Merge Time (core contributors) | 10.6 days | < 7 days | < 5 days | -| Issue First Response | 13 days | < 3 days | < 48h | -| Repeat Core Contributors | 4 | 10 | 20 | - -See [Extensibility & Ecosystem doc](./extensibility.md) for detailed ecosystem metrics (community tools, integrations, etc.). - ---- - -## Part 2: Competitor Learnings - -We can learn from how other AI agent SDKs handle community. Let's take what works. - -| Project | Stars | Community Channel | What We Can Learn | -|---------|-------|-------------------|-------------------| -| LangChain | ~120K | Slack + Forum | 400+ integrations, comprehensive contributor docs, "good first issue" labeling | -| CrewAI | ~42K | Forum | Fast issue closure (97%+), 100K+ certified developers community | -| AutoGen | ~53K | Discord | Human-in-the-loop focus, research-oriented community | -| **Strands** | ~5K | None | — | - -*Star counts verified January 2026.* - -**Key observations:** -- All competitors have real-time community channels. We don't. -- CrewAI and LangChain close 97%+ of issues. We close 54%. -- Fast response time correlates with contributor retention. - -**Practices worth adopting:** -- **Clear contribution docs:** LangChain has detailed contributor documentation covering setup, PR process, code standards, and testing requirements. They redirect CONTRIBUTING.md to comprehensive docs site. -- **Issue labeling:** LangChain uses `good first issue` and `help wanted` labels to guide new contributors. They also have a pinned "Looking to Contribute? Start Here!" issue. -- **Design discussion before implementation:** LangChain requires design discussion for large features before implementation—prevents wasted effort on both sides. - ---- - -## Part 3: Key Decisions - -Based on the analysis, here are the strategic decisions we need to make: - -### Decision 1: Response Time SLA - -**Decision:** Commit to < 3 day first response SLA (aligned with twice-weekly triage meetings). - -**Rationale:** Research shows response time is a key predictor of contributor retention. Fast initial responses signal that contributions are valued and encourage repeat engagement. - -Currently we do internal triage, but we don't have public priority labels and we don't respond to contributors. From their perspective, they see no engagement. Same applies to PRs. - -The cost of slow response (lost contributors, bad reputation) exceeds the cost of interruption. First response doesn't mean full review—just acknowledgment and initial triage. - -**Implementation:** Triage happens in twice-weekly "Community PR and Issue Review" meetings (Tue/Thu). This requires: -- Oncall dashboard so they can see what needs response -- Clear guidelines on what "first response" means -- Processes documented in oncall runbook - -### Decision 2: PR Acceptance Rate Target - -**Decision:** Target 65-70% acceptance rate (up from 52%). - -**Rationale:** Current 52% rate means contributors have coin-flip odds. This discourages contribution. But we shouldn't accept everything—quality matters. - -The gap is likely due to unclear expectations, not bad contributions. Better guidelines and early feedback should improve the rate without lowering standards. - -**Implementation:** -- Clear contribution guidelines documenting what we accept/reject -- Early feedback on direction before significant investment -- Add a proposal/RFC process for contributors to propose new features before implementation using GitHub Discussions with a proposal template—lower friction, signals we want conversation not just task tracking, and keeps proposals separate from bugs/feature requests. - -### Decision 3: Tools Repository Policy - -**Decision:** Don't accept external tools to core repo. Provide template + catalog instead. - -**Rationale:** We can't test, maintain, or take security responsibility for tools we don't understand. The MongoDB CVE incident showed the risk. But we should make it easy to publish and discover community tools. - -**Implementation:** See [Extensibility & Ecosystem doc](./extensibility.md) for details on: -- GitHub template for tool packages -- Community tools catalog/registry -- Clear communication in tools repo -- Contributor guide in docs explaining how to develop and publish tools (use template → update PyPI secrets → update tool code → publish, use tags for visibility) - -### Decision 4: Community Channel - -**Proposal:** Adopt Discord as our real-time community channel. - -**Rationale:** All competitors have real-time community channels. Internal contributors have Slack access which gives them a significant advantage over external contributors. A real-time channel bridges this gap. - -**Moderation:** We may take over an existing Discord from the AgentCore team, which reduces cold-start and provides existing moderation infrastructure. - -**Trade-off:** Requires ongoing moderation investment, but the cost of not having a community channel (slower communication, contributor disadvantage) is higher. - ---- - -## Part 4: Observability - -We can't improve what we don't measure. Currently, we have no visibility into contributor health metrics. We need to build these dashboards to operationalize community health. - -### SLAs - -| Item Type | First Response | Cycle Time | Notes | -|-----------|---------------|------------|-------| -| PRs | < 3 days | < 3 days between responses | Oncall acknowledges, owner assigned in twice-weekly meeting | -| Issues | < 3 days | < 3 days | Triage and label in twice-weekly meeting | -| Discussions | < 72h | Best effort | Lower priority | -| Security Issues | < 24h | ASAP | Escalate immediately | - -### Metrics We Track - -**P0 Metrics (Review Weekly)** - -These directly measure core contributor experience: - -- **Core Contributor PR Success Rate:** % of core contributor PRs merged. Target: > 65% -- **PR First Response Time:** Median time to first maintainer response. Target: < 3 days -- **PR Merge Time (core contributors):** Median time from open to merge. Target: < 7 days -- **Issue First Response Time:** Median time to first response. Target: < 3 days -- **Issue Response Rate:** % of issues with maintainer response. Target: > 80% - -**P1 Metrics (Review Monthly)** - -These measure overall health: - -- **Stars:** GitHub stars across all repos. Target: Growing -- **Downloads:** PyPI + npm downloads. Target: Growing -- **New Core Contributors:** First-time core contributors per month. Target: > 10 -- **Repeat Core Contributors:** Core contributors with 2+ PRs. Target: Growing -- **BMI (Backlog Management Index):** Closed issues / Opened issues. Target: > 1.0 - -### Dashboards - -**Health & Trends Dashboard** - -For team review meetings. Shows trends over time: -- PR/Issue response times (trend) -- Success rates (trend) -- Open items count (trend) -- Contributor growth (trend) -- Stars/downloads (trend) - -**Oncall Operations Dashboard** - -For oncall to find items needing attention. Prioritized lists: -1. Items awaiting maintainer response (last comment from community member) -2. SLA breaches (> 3 days without response) -3. First-time core contributor PRs (need extra care) -4. Oldest open items -5. High-priority labeled items - -### Alerting - -**Phase 1 (Now):** Manual review of metrics in weekly oncall handover. - -**Phase 2 (Near-term):** Slack alert when items exceed 3 days without response. - -**Phase 3 (Future):** SLA breach creates internal Sev2.5 ticket for stale items. - ---- - -## Part 5: Visibility - -Observability (Part 4) is about us seeing community health. Visibility is about the community seeing our plans and thinking. - -### Why It Matters - -Contributors need context to contribute effectively. If they don't know our roadmap, they might spend a week on a PR we'll reject because it doesn't align with direction. If they don't understand our design principles, their code won't match our patterns. - -Visibility also builds trust. When we explain why we make decisions, the community understands we're not arbitrary gatekeepers. - -### What We Publish - -**Public Roadmap** - -What we're working on and what's coming. This helps contributors: -- Avoid duplicating work we're already doing -- Understand if their feature idea aligns with direction -- Find areas where contributions are welcome - -The roadmap should be high-level (themes, not tickets) and updated quarterly. - -**Design Principles** - -Our mental models for how Strands should work. We already have a Decision Record in the SDK repo that documents design decisions with rationale. We should expand this pattern: -- Model-first approach (let the LLM decide, not hardcoded logic) -- Keep the core SDK lean (tools/providers live separately) -- Hooks as low-level primitives, high-level abstractions built on top -- Prefer composition over inheritance - -These help contributors write code that fits our patterns. - -**Decision Rationale** - -When we make significant decisions (like not accepting external tools), we should explain why. This prevents frustration and helps the community understand our constraints. - ---- - -## Part 6: Processes and Mechanisms - -### Oncall Responsibilities - -Oncall is responsible for community management for the week. - -**Daily Tasks:** -- Check oncall dashboard for urgent items (security issues, SLA breaches) -- Handle security issues immediately (< 24h SLA) - -**Twice-Weekly Tasks (Tue/Thu meetings):** -- Triage new issues (label, prioritize, respond) -- Review new PRs (check alignment, assign owners) -- Follow up on items awaiting response - -**Weekly Tasks:** -- Review metrics in handover meeting -- Hand off in-progress items to next oncall -- Flag systemic issues to team - -**What Oncall is NOT Responsible For:** -- Full code review of all PRs (assign to appropriate maintainer) -- Fixing all bugs (triage and assign) -- 24/7 availability - -### PR Ownership Model - -**Problem:** PRs fall through cracks. No one owns them end-to-end. - -**Solution:** Assign a maintainer to own each core contributor PR during twice-weekly "Community PR and Issue Review" meetings (Tue/Thu). This reduces oncall load and distributes work across the team. - -**Process:** -1. During twice-weekly meeting, team reviews new PRs, checks alignment, assigns owners -2. Owner shepherds PR from first review to merge/close -3. Target: ~2 PRs per maintainer per week -4. If contributor doesn't respond in 1 week, owner can drop assignment -5. If we're getting more PRs than we can assign, discuss capacity in the meeting - -**Guidelines for Owners:** -- Engineers self-balance based on current load -- Big PRs count as multiple -- Dead PRs (no response > 2 weeks) can be closed or taken over -- When in doubt, ask in team channel or bring up during meetings - -### Trusted Contributors (Strands Champions) - -Internal engineers and solution architects want to contribute to Strands and be more involved. We can leverage these folks to scale our community management capacity. They're more reliable than random contributors because they have internal accountability and context. - -We can later extend this program to outside contributors, but for now this document is focused on internal engineers. - -**What they can do:** -- Triage and respond to issues -- Participate in discussions and RFCs -- Review PRs — their approval counts same as maintainers, but they can't merge -- Flag issues/discussions to maintainers via internal channel - -**What this enables:** -- Faster response times without adding maintainer headcount -- More eyes on PRs (smaller PRs can be reviewed and approved by trusted contributors, reducing maintainer load) -- Better coverage of community channels - -**Status:** We have an initial group of internal SAs interested. Details (commitment, onboarding, recognition) to be figured out as we go. - -### Triage Process - -**For New Issues:** -1. Review in twice-weekly meeting -2. Add type label: `bug`, `feature`, `question`, `documentation` -3. Add priority: `priority:critical`, `priority:high`, `priority:medium`, `priority:low` -4. Add area: `area:core`, `area:tools`, `area:models`, etc. -5. If good for external contribution: add `ready-for-contribution` -6. Respond to author with acknowledgment - -**For New PRs:** -1. Review in twice-weekly meeting -2. Check: Does this align with project direction? -3. If yes: Assign maintainer owner, add `awaiting-review` -4. If no: Provide feedback, close if appropriate -5. If unclear: Ask clarifying questions - -### Contribution Guidelines - -We need a unified contributor entry point in docs that covers: -- How to contribute to core SDK (core contributors) -- How to contribute new components like tools, model providers (contributors) -- Our decisions and internal thinking (roadmap, design principles) - -**What PRs We Accept:** -- Bug fixes with tests -- Documentation improvements -- Performance improvements with benchmarks -- Features that align with roadmap -- Features discussed and approved in issue first - -**What PRs We Don't Accept:** -- Features that don't align with project direction -- Breaking changes without prior discussion -- Code without tests -- Large refactors without prior discussion -- Tools to core tools repo (use template instead) - -**When to Close PRs:** -- No response from author > 2 weeks after feedback -- Doesn't align with project direction (after discussion) -- Duplicate of existing PR -- Author requests closure - -**When to Take Over PRs:** -- Author explicitly allows it -- PR is 90% done, just needs minor fixes -- Critical bug fix that's stalled - ---- - -## Part 7: Automation - -We have several agent projects in progress that can help: - -- Aaron's bot that generates responses to issues (helps oncall understand issues faster) -- Extend to replicate bugs and generate reproducible code -- Use internal Slack channel to generate draft responses -- Containerized agents for more direct tooling - -The idea is to use GitHub and local agents to generate responses and accelerate the team. We optimize these agents internally, then move the same configuration to GitHub Actions for automation. This creates a pipeline for agents to go from internal → GitHub. Along the way we'll need to solve agent permission problems (likely through specialized PAT tokens). - -**Use cases:** -- Write/update docs -- Review PRs (enabled by maintainer after alignment check) -- Replicate (and later solve) bugs -- Prioritize items -- SLA breach notifications -- Removing stale items - -**Dev tooling approach:** We should build shared dev tools (CLI, containerized agents) that we optimize together as a team. The progression: local tools → Slack notifications based on GitHub events → GitHub Actions responding directly. This lets us iterate quickly internally before exposing to community. - -### Agent-Assisted Review - -**Goal:** Reduce maintainer burden on mechanical review tasks. - -**Concerns:** Avoid Hadoop-style noise where every PR has pages of auto-generated boilerplate. It's demoralizing for contributors. - -**Approach:** -- Start with opt-in, not default -- Focus on actionable feedback only -- Summarize issues, don't list every lint error -- Human always makes final decision - -**Status:** We have a review agent in progress. Need to invest time to complete and iterate on these projects before broader rollout. - ---- - -## Part 8: Implementation Roadmap - -See the complete roadmap at [Task Backlog](./task-backlog.md) - ---- - -## Open Questions - -- **Oncall capacity:** Oncall is also responsible for bugs and critical issues. Is adding community management too much? Need to monitor and adjust. -- **Discord moderation:** We may take over an existing Discord from the AgentCore team. Need to confirm feasibility. - ---- - -## TODO: - -- Going public from internal discussions -- Define what first response is + guidelines -- in SLAs, maybe split to time to triage, time to resolution - - Avg First response < 3d - - Avg Triage < 1w - - Avg Resolution < 2w -- making triaging public -- note: ready to contribute → pr → review (we should prioritize this) diff --git a/adrs/README.md b/adrs/README.md deleted file mode 100644 index 73f4901e..00000000 --- a/adrs/README.md +++ /dev/null @@ -1,88 +0,0 @@ -# Architecture Decision Records (ADRs) - -This folder contains Architecture Decision Records for significant features and changes to Strands Agents. ADRs document the context, decision, and consequences of architectural choices. - -## What is an ADR? - -An ADR is a design document that captures an important architectural decision along with its context and consequences. Once approved and merged, it becomes part of the project's decision history. - -## When to write an ADR - -Write an ADR for: - -- New major features affecting multiple parts of the SDK -- Breaking changes to existing APIs -- Architectural changes requiring design discussion -- Large contributions (> 1 week of work) -- Features that introduce new concepts - -Skip the ADR process for bug fixes, small improvements, documentation updates, and new extensions in your own repository. - -## How to submit an ADR - -1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)** — See if your idea aligns with our direction -2. **Fork the [docs repository](https://github.com/strands-agents/docs)** -3. **Create your ADR** — Add a new file: `adrs/NNNN-feature-name.md` using the template below -4. **Submit a pull request** — We'll review and discuss -5. **Iterate based on feedback** — Address comments and questions -6. **Get approval** — Once approved and merged, implement the feature -7. **Reference the ADR** — Link to it in your implementation PR - -## ADR template - -```markdown -# ADR: [Feature Name] - -**Status**: Proposed | Accepted | Deprecated | Superseded - -**Date**: YYYY-MM-DD - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -- What task are you trying to accomplish? -- What makes it difficult or impossible today? -- Who experiences this problem? - -## Decision - -What is the change that we're proposing and/or doing? - -- Changes to the API (with code examples) -- How it integrates with existing features -- Expected behavior and usage patterns - -## Developer Experience - -Show what the developer experience looks like: - -- Code examples showing typical usage -- Configuration or setup required -- Error messages and edge cases - -## Alternatives Considered - -What other approaches did you consider? Why did you choose this one? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## Willingness to Implement - -Are you willing to implement this if approved? - -Yes / No / Maybe with guidance -``` - -## ADR naming - -Use the format `NNNN-short-description.md` where NNNN is the next available number: - -- `0001-streaming-hooks.md` -- `0002-retry-strategies.md` - -## Accepted ADRs - -*No ADRs have been accepted yet.* From 0aa8b320c5ec2a5baee4db0a41aa092fbd14e0e3 Mon Sep 17 00:00:00 2001 From: Murat Kaan Meral Date: Thu, 29 Jan 2026 15:55:48 -0500 Subject: [PATCH 11/11] fix(proposals): Update feature proposals based on designs folder changes --- .../contributing/feature-proposals.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/contribute/contributing/feature-proposals.md b/docs/contribute/contributing/feature-proposals.md index fec7f4ed..d117041e 100644 --- a/docs/contribute/contributing/feature-proposals.md +++ b/docs/contribute/contributing/feature-proposals.md @@ -1,12 +1,12 @@ # Feature Proposals -Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. We use an ADR (Architecture Decision Record) process for larger contributions to ensure your work has the best chance of being merged. +Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. We use a design document process for larger contributions to ensure your work has the best chance of being merged. -## When to write an ADR +## When to write a design document -Not every contribution needs an ADR. Use this process for changes that have broad impact or require significant time investment. +Not every contribution needs a design document. Use this process for changes that have broad impact or require significant time investment. -| Use ADR for | Skip ADR for | +| Write a design document for | Skip the design process for | |-------------|--------------| | New major features affecting multiple parts of the SDK | Bug fixes with clear solutions | | Breaking changes to existing APIs | Small improvements and enhancements | @@ -14,23 +14,23 @@ Not every contribution needs an ADR. Use this process for changes that have broa | Large contributions (> 1 week of work) | New extensions in your own repository | | Features that introduce new concepts | Performance optimizations | -When in doubt, open an issue first. We'll tell you if an ADR is needed. +When in doubt, open an issue first. We'll tell you if a design document is needed. ## Process -The ADR process helps align on requirements, explore alternatives, and identify edge cases before implementation begins. +The design document process helps align on requirements, explore alternatives, and identify edge cases before implementation begins. 1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)** — See if your idea aligns with our direction and isn't already planned 2. **Open an issue first** — Describe the problem you're trying to solve. We need to validate the problem is worth solving before you invest time in a detailed proposal -3. **Create an ADR** — Once we agree the problem is worth solving, submit a PR to the [`adrs` folder](https://github.com/strands-agents/docs/tree/main/adrs) in the docs repository using the template there. Reference the issue in your ADR +3. **Create a design document** — Once we agree the problem is worth solving, submit a PR to the [`designs` folder](https://github.com/strands-agents/docs/tree/main/designs) in the docs repository using the template there. Reference the issue in your design document 4. **Gather feedback** — We'll review and discuss with you, asking clarifying questions -5. **Get approval** — When we merge the ADR, that's your go-ahead to implement +5. **Get approval** — When we merge the design document, that's your go-ahead to implement 6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) -7. **Reference the ADR** — Link to the approved ADR in your implementation PR +7. **Reference the design** — Link to the approved design document in your implementation PR -## ADR template +## Design document template -See the full template in the [ADRs folder README](https://github.com/strands-agents/docs/blob/main/adrs/README.md#adr-template). +See the full template in the [designs folder README](https://github.com/strands-agents/docs/blob/main/designs/README.md#design-document-template). **Tips for effective proposals:**