diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md index 5b06b923..182e9991 100644 --- a/docs/community/community-packages.md +++ b/docs/community/community-packages.md @@ -1,54 +1,57 @@ -# 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 and find packages that solve your specific needs. -## Creating A Package +Browse by category below to find tools, model providers, session managers, and platform integrations built by the community. -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: +!!! 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. -- **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. +## Tools -[strands-clova](https://github.com/aidendef/strands-clova) is a community package that can serve as a good example. +Tools extend your agents with capabilities for specific services and platforms. Each package provides one or more tools you can add to your agents. -## Publishing to PyPI +| 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 | -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. +## Model providers -Best practices for publishing include: +Model providers add support for additional LLM services beyond the built-in providers. Use these to integrate with specialized or regional LLM platforms. -- **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. +| 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 | -## Getting Featured in Documentation +## Session managers -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. +Session managers provide alternative storage backends for conversation history. Use these when you need persistent, scalable, or distributed session storage. -See our [Get Featured](./get-featured.md) guide for step-by-step instructions on adding your package to the docs. +| Package | Description | +|---------|-------------| +| [AgentCore Memory](./session-managers/agentcore-memory.md) | Amazon AgentCore | +| [Valkey](./session-managers/strands-valkey-session-manager.md) | Valkey session manager | -## Best Practices and Examples +## Integrations -### Model Providers +Platform integrations help you connect Strands agents with external services and user interfaces. -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. +| Package | Description | +|---------|-------------| +| [AG-UI](./integrations/ag-ui.md) | AG-UI integration | -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). +## Add your package -### 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). +Built something useful? We'd love to feature it here. +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/core-sdk.md b/docs/contribute/contributing/core-sdk.md new file mode 100644 index 00000000..7d49973e --- /dev/null +++ b/docs/contribute/contributing/core-sdk.md @@ -0,0 +1,142 @@ +# 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. 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. Focus on changes that benefit the entire community rather than solving niche use cases. + +- **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/8/views/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 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) +- **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 + +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. This process differs slightly between Python and TypeScript. + +=== "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](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 # Run unit tests + hatch test -c # Run with coverage report + ``` + + You can also run linters and formatters manually. + + ```bash + hatch fmt --linter # Check for code quality issues + 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 + - 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. + + ```bash + git clone https://github.com/strands-agents/sdk-typescript.git + cd sdk-typescript + npm install + ``` + + 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 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:** + + - 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 + +## 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. + +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. + +## Related guides + +- [Feature proposals](./feature-proposals.md) — For significant features requiring discussion +- [Team documentation](https://github.com/strands-agents/docs/tree/main/team) — Our tenets, decisions, and API review process diff --git a/docs/contribute/contributing/documentation.md b/docs/contribute/contributing/documentation.md new file mode 100644 index 00000000..c1033af4 --- /dev/null +++ b/docs/contribute/contributing/documentation.md @@ -0,0 +1,117 @@ +# Contributing to Documentation + +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. Documentation changes can range from small typo fixes to complete new guides. + +| 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 | + +## 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 +# Clone the docs repository +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 -e . + +# 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 + +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. + +**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 finishes understanding the "why" before the "how." This section covers our voice, writing style, and code example conventions. + +### Voice and tone + +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 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 for structured data | +| Add lead-in sentences before lists | Jump directly into bulleted lists | + +### Code examples + +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 +# Good: Start simple +from strands import Agent +agent = Agent() +agent("Hello, world!") + +# 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." +) +agent("What's the weather like?") +``` + diff --git a/docs/contribute/contributing/extensions.md b/docs/contribute/contributing/extensions.md new file mode 100644 index 00000000..c656b6af --- /dev/null +++ b/docs/contribute/contributing/extensions.md @@ -0,0 +1,43 @@ +# Publishing extensions + +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. + +This guide walks you through packaging and publishing your Strands components so other developers can install them with `pip install`. + +## Why publish + +When you build a useful component, you have two choices: keep it in your project, or publish it as a package. + +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. + +Your package can get listed in our [community catalog](../../community/community-packages.md), making it discoverable to developers looking for exactly what you built. + +## What you can publish + +Strands has several extension points. Each serves a different purpose in the agent lifecycle. + +| Component | Purpose | Learn more | +|-----------|---------|------------| +| **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) | +| **Conversation managers** | Control how message history grows—trim old messages or summarize context | [Conversation management](../../user-guide/concepts/agents/conversation-management.md) | + +Tools are the most common extension type. They let agents interact with specific services like Slack, databases, or internal APIs. + +## 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. + + +## Get discovered + +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/contributing/feature-proposals.md b/docs/contribute/contributing/feature-proposals.md new file mode 100644 index 00000000..d117041e --- /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 a design document process for larger contributions to ensure your work has the best chance of being merged. + +## When to write a design document + +Not every contribution needs a design document. Use this process for changes that have broad impact or require significant time investment. + +| 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 | +| 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 a design document is needed. + +## Process + +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 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 design document, that's your go-ahead to implement +6. **Implement** — Follow the [SDK contribution process](./core-sdk.md) +7. **Reference the design** — Link to the approved design document in your implementation PR + +## Design document 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:** + +- 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..467807d7 --- /dev/null +++ b/docs/contribute/index.md @@ -0,0 +1,31 @@ +# 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 + +These contributions 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 + +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 | +|--------------|------------------|-------| +| Publish an extension | Package your component and publish to PyPI so others can use it | [Publishing 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 +- [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 diff --git a/mkdocs.yml b/mkdocs.yml index e641bbb7..d3cac9a4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -242,7 +242,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.