diff --git a/docs/assets/auto-redirect.js b/docs/assets/auto-redirect.js new file mode 100644 index 00000000..81ed8523 --- /dev/null +++ b/docs/assets/auto-redirect.js @@ -0,0 +1,22 @@ +/** + * Auto-redirect to the first link in the markdown. + * + * This is a workaround for mkdocs not supporting redirects in a way that doesn't have a huge-flash of content. + */ +class AutoRedirect extends HTMLElement { + connectedCallback() { + const currentUrl = window.location.href; + const link = this.parentElement.closest(".md-content")?.querySelector("a[href]") + + if (link) { + // immediately redirecting makes a flash of content, so do it after a second + setTimeout(() => { + if (currentUrl == window.location.href) { + window.location.replace(link.href); + } + }, 1000) + } + } +} + +customElements.define('auto-redirect', AutoRedirect); \ No newline at end of file diff --git a/docs/community/community-packages.md b/docs/community/community-packages.md new file mode 100644 index 00000000..97b5f557 --- /dev/null +++ b/docs/community/community-packages.md @@ -0,0 +1,60 @@ +# Community Packages + +The Strands Agents ecosystem 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. + +## Creating A Package + +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: + +- **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. + +[strands-clova](https://github.com/aidendef/strands-clova) is a community package that can serve as a good example. + +## Publishing to PyPI + +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. + +Best practices for publishing include: + +- **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. + +## Getting Featured in Documentation + +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. + +Submit your package for consideration by creating an issue in the [Strands Agents documentation repository](https://github.com/strands-agents/docs/issues). Include: + + - 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 + +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. + +## Best Practices and Examples + +### Model Providers + +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. + +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). + diff --git a/docs/community/model-providers/clova-studio.md b/docs/community/model-providers/clova-studio.md new file mode 100644 index 00000000..f16a63fa --- /dev/null +++ b/docs/community/model-providers/clova-studio.md @@ -0,0 +1,90 @@ +# CLOVA Studio + +{{ community_contribution_banner }} + +[CLOVA Studio](https://www.ncloud.com/product/aiService/clovaStudio) is Naver Cloud Platform's AI service that provides large language models optimized for Korean language processing. The [`strands-clova`](https://pypi.org/project/strands-clova/) package ([GitHub](https://github.com/aidendef/strands-clova)) provides a community-maintained integration for the Strands Agents SDK, enabling seamless use of CLOVA Studio's Korean-optimized AI models. + +## Installation + +CLOVA Studio integration is available as a separate community package: + +```bash +pip install strands-agents strands-clova +``` + +## Usage + +After installing `strands-clova`, you can import and initialize the CLOVA Studio provider: + +```python +from strands import Agent +from strands_clova import ClovaModel + +model = ClovaModel( + api_key="your-clova-api-key", # or set CLOVA_API_KEY env var + model="HCX-005", + temperature=0.7, + max_tokens=2048 +) + +agent = Agent(model=model) +response = await agent.invoke_async("안녕하세요! 오늘 날씨가 어떤가요?") +print(response.message) +``` + +## Configuration + +### Environment Variables + +```bash +export CLOVA_API_KEY="your-api-key" +export CLOVA_REQUEST_ID="optional-request-id" # For request tracking +``` + +### Model Configuration + +The supported configurations are: + +| Parameter | Description | Example | Default | +|------------|-------------|---------|---------| +| `model` | Model ID | `HCX-005` | `HCX-005` | +| `temperature` | Sampling temperature (0.0-1.0) | `0.7` | `0.7` | +| `max_tokens` | Maximum tokens to generate | `4096` | `2048` | +| `top_p` | Nucleus sampling parameter | `0.8` | `0.8` | +| `top_k` | Top-k sampling parameter | `0` | `0` | +| `repeat_penalty` | Repetition penalty | `1.1` | `1.1` | +| `stop` | Stop sequences | `["\\n\\n"]` | `[]` | + +## Advanced Features + +### Korean Language Optimization + +CLOVA Studio excels at Korean language tasks: + +```python +# Korean customer support bot +model = ClovaModel(api_key="your-api-key", temperature=0.3) +agent = Agent( + model=model, + system_prompt="당신은 친절한 고객 서비스 상담원입니다." +) + +response = await agent.invoke_async("제품 반품 절차를 알려주세요") +``` + +### Bilingual Capabilities + +Handle both Korean and English seamlessly: + +```python +# Process Korean document and get English summary +response = await agent.invoke_async( + "다음 한국어 문서를 영어로 요약해주세요: [문서 내용]" +) +``` + +## References + +- [strands-clova GitHub Repository](https://github.com/aidendef/strands-clova) +- [CLOVA Studio Documentation](https://www.ncloud.com/product/aiService/clovaStudio) +- [Naver Cloud Platform](https://www.ncloud.com/) \ No newline at end of file diff --git a/docs/community/model-providers/cohere.md b/docs/community/model-providers/cohere.md new file mode 100644 index 00000000..4824186f --- /dev/null +++ b/docs/community/model-providers/cohere.md @@ -0,0 +1,78 @@ +# Cohere + +{{ community_contribution_banner }} + +[Cohere](https://cohere.com) provides cutting-edge language models. These are accessible through OpenAI's SDK via the Compatibility API. This allows easy and portable integration with the Strands Agents SDK using the familiar OpenAI interface. + +## Installation + +The Strands Agents SDK provides access to Cohere models through the OpenAI compatibility layer, configured as an optional dependency. To install, run: + +```bash +pip install 'strands-agents[openai]' strands-agents-tools +``` + +## Usage + +After installing the `openai` package, you can import and initialize the Strands Agents' OpenAI-compatible provider for Cohere models as follows: + +```python +from strands import Agent +from strands.models.openai import OpenAIModel +from strands_tools import calculator + +model = OpenAIModel( + client_args={ + "api_key": "", + "base_url": "https://api.cohere.ai/compatibility/v1", # Cohere compatibility endpoint + }, + model_id="command-a-03-2025", # or see https://docs.cohere.com/docs/models + params={ + "stream_options": None + } +) + +agent = Agent(model=model, tools=[calculator]) +agent("What is 2+2?") +``` + +## Configuration + +### Client Configuration + +The `client_args` configure the underlying OpenAI-compatible client. When using Cohere, you must set: + +* `api_key`: Your Cohere API key. Get one from the [Cohere Dashboard](https://dashboard.cohere.com). +* `base_url`: + * `https://api.cohere.ai/compatibility/v1` + +Refer to [OpenAI Python SDK GitHub](https://github.com/openai/openai-python) for full client options. + +### Model Configuration + +The `model_config` specifies which Cohere model to use and any additional parameters. + +| Parameter | Description | Example | Options | +| ---------- | ------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | +| `model_id` | Model name | `command-r-plus` | See [Cohere docs](https://docs.cohere.com/docs/models) | +| `params` | Model-specific parameters | `{"max_tokens": 1000, "temperature": 0.7}` | [API reference](https://docs.cohere.com/docs/compatibility-api) | + +## Troubleshooting + +### `ModuleNotFoundError: No module named 'openai'` + +You must install the `openai` dependency to use this provider: + +```bash +pip install 'strands-agents[openai]' +``` + +### Unexpected model behavior? + +Ensure you're using a model ID compatible with Cohere’s Compatibility API (e.g., `command-r-plus`, `command-a-03-2025`, `embed-v4.0`), and your `base_url` is set to `https://api.cohere.ai/compatibility/v1`. + +## References + +* [Cohere Docs: Using the OpenAI SDK](https://docs.cohere.com/docs/compatibility-api) +* [Cohere API Reference](https://docs.cohere.com/reference) +* [OpenAI Python SDK](https://github.com/openai/openai-python) diff --git a/docs/user-guide/concepts/model-providers/clova-studio.md b/docs/user-guide/concepts/model-providers/clova-studio.md index f16a63fa..5f0eab8d 100644 --- a/docs/user-guide/concepts/model-providers/clova-studio.md +++ b/docs/user-guide/concepts/model-providers/clova-studio.md @@ -1,90 +1,4 @@ -# CLOVA Studio -{{ community_contribution_banner }} + -[CLOVA Studio](https://www.ncloud.com/product/aiService/clovaStudio) is Naver Cloud Platform's AI service that provides large language models optimized for Korean language processing. The [`strands-clova`](https://pypi.org/project/strands-clova/) package ([GitHub](https://github.com/aidendef/strands-clova)) provides a community-maintained integration for the Strands Agents SDK, enabling seamless use of CLOVA Studio's Korean-optimized AI models. - -## Installation - -CLOVA Studio integration is available as a separate community package: - -```bash -pip install strands-agents strands-clova -``` - -## Usage - -After installing `strands-clova`, you can import and initialize the CLOVA Studio provider: - -```python -from strands import Agent -from strands_clova import ClovaModel - -model = ClovaModel( - api_key="your-clova-api-key", # or set CLOVA_API_KEY env var - model="HCX-005", - temperature=0.7, - max_tokens=2048 -) - -agent = Agent(model=model) -response = await agent.invoke_async("안녕하세요! 오늘 날씨가 어떤가요?") -print(response.message) -``` - -## Configuration - -### Environment Variables - -```bash -export CLOVA_API_KEY="your-api-key" -export CLOVA_REQUEST_ID="optional-request-id" # For request tracking -``` - -### Model Configuration - -The supported configurations are: - -| Parameter | Description | Example | Default | -|------------|-------------|---------|---------| -| `model` | Model ID | `HCX-005` | `HCX-005` | -| `temperature` | Sampling temperature (0.0-1.0) | `0.7` | `0.7` | -| `max_tokens` | Maximum tokens to generate | `4096` | `2048` | -| `top_p` | Nucleus sampling parameter | `0.8` | `0.8` | -| `top_k` | Top-k sampling parameter | `0` | `0` | -| `repeat_penalty` | Repetition penalty | `1.1` | `1.1` | -| `stop` | Stop sequences | `["\\n\\n"]` | `[]` | - -## Advanced Features - -### Korean Language Optimization - -CLOVA Studio excels at Korean language tasks: - -```python -# Korean customer support bot -model = ClovaModel(api_key="your-api-key", temperature=0.3) -agent = Agent( - model=model, - system_prompt="당신은 친절한 고객 서비스 상담원입니다." -) - -response = await agent.invoke_async("제품 반품 절차를 알려주세요") -``` - -### Bilingual Capabilities - -Handle both Korean and English seamlessly: - -```python -# Process Korean document and get English summary -response = await agent.invoke_async( - "다음 한국어 문서를 영어로 요약해주세요: [문서 내용]" -) -``` - -## References - -- [strands-clova GitHub Repository](https://github.com/aidendef/strands-clova) -- [CLOVA Studio Documentation](https://www.ncloud.com/product/aiService/clovaStudio) -- [Naver Cloud Platform](https://www.ncloud.com/) \ No newline at end of file +This guide has moved to [community/model-providers/clova-studio](../../../community/model-providers/clova-studio.md). diff --git a/docs/user-guide/concepts/model-providers/cohere.md b/docs/user-guide/concepts/model-providers/cohere.md index a7d0ca6e..31a2eda3 100644 --- a/docs/user-guide/concepts/model-providers/cohere.md +++ b/docs/user-guide/concepts/model-providers/cohere.md @@ -1,77 +1,5 @@ -# Cohere -[Cohere](https://cohere.com) provides cutting-edge language models. These are accessible through OpenAI's SDK via the Compatibility API. This allows easy and portable integration with the Strands Agents SDK using the familiar OpenAI interface. + -## Installation +This guide has moved to [community/model-providers/cohere](../../../community/model-providers/cohere.md). -The Strands Agents SDK provides access to Cohere models through the OpenAI compatibility layer, configured as an optional dependency. To install, run: - -```bash -pip install 'strands-agents[openai]' strands-agents-tools -``` - -## Usage - -After installing the `openai` package, you can import and initialize the Strands Agents' OpenAI-compatible provider for Cohere models as follows: - -```python -from strands import Agent -from strands.models.openai import OpenAIModel -from strands_tools import calculator - -model = OpenAIModel( - client_args={ - "api_key": "", - "base_url": "https://api.cohere.ai/compatibility/v1", # Cohere compatibility endpoint - }, - model_id="command-a-03-2025", # or see https://docs.cohere.com/docs/models - params={ - "stream_options": None - } -) - -agent = Agent(model=model, tools=[calculator]) -agent("What is 2+2?") -``` - -## Configuration - -### Client Configuration - -The `client_args` configure the underlying OpenAI-compatible client. When using Cohere, you must set: - -* `api_key`: Your Cohere API key. Get one from the [Cohere Dashboard](https://dashboard.cohere.com). -* `base_url`: - * `https://api.cohere.ai/compatibility/v1` - -Refer to [OpenAI Python SDK GitHub](https://github.com/openai/openai-python) for full client options. - -### Model Configuration - -The `model_config` specifies which Cohere model to use and any additional parameters. - -| Parameter | Description | Example | Options | -| ---------- | ------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | -| `model_id` | Model name | `command-r-plus` | See [Cohere docs](https://docs.cohere.com/docs/models) | -| `params` | Model-specific parameters | `{"max_tokens": 1000, "temperature": 0.7}` | [API reference](https://docs.cohere.com/docs/compatibility-api) | - -## Troubleshooting - -### `ModuleNotFoundError: No module named 'openai'` - -You must install the `openai` dependency to use this provider: - -```bash -pip install 'strands-agents[openai]' -``` - -### Unexpected model behavior? - -Ensure you're using a model ID compatible with Cohere’s Compatibility API (e.g., `command-r-plus`, `command-a-03-2025`, `embed-v4.0`), and your `base_url` is set to `https://api.cohere.ai/compatibility/v1`. - -## References - -* [Cohere Docs: Using the OpenAI SDK](https://docs.cohere.com/docs/compatibility-api) -* [Cohere API Reference](https://docs.cohere.com/reference) -* [OpenAI Python SDK](https://github.com/openai/openai-python) -* [Strands Agents API](../../../api-reference/models.md) diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index 12033ea1..7b3b032d 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -442,9 +442,9 @@ Strands Agents supports several other model providers beyond Amazon Bedrock: - **[Ollama](concepts/model-providers/ollama.md)** - Run models locally for privacy or offline use - **[OpenAI](concepts/model-providers/openai.md)** - Access to OpenAI or OpenAI-compatible models - **[Writer](concepts/model-providers/writer.md)** - Access to Palmyra models -- **[Cohere](concepts/model-providers/cohere.md)** - Use Cohere models through an OpenAI compatible interface +- **[Cohere community](../community/model-providers/cohere.md)** - Use Cohere models through an OpenAI compatible interface +- **[CLOVA Studio community](../community/model-providers/clova-studio.md)** - Korean-optimized AI models from Naver Cloud Platform - **[Custom Providers](concepts/model-providers/custom_model_provider.md)** - Build your own provider for specialized needs -- **[CLOVA Studio community](concepts/model-providers/clova-studio.md)** - Korean-optimized AI models from Naver Cloud Platform ## Capturing Streamed Data & Events diff --git a/mkdocs.yml b/mkdocs.yml index dbb2fe3e..dcd2f21f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,6 +67,7 @@ extra_javascript: # Workaround for site_url breaking mermaid rendering; see the following for more info: # https://github.com/squidfunk/mkdocs-material/issues/3742#issuecomment-1076068038 - https://unpkg.com/mermaid@11/dist/mermaid.min.js + - assets/auto-redirect.js nav: - User Guide: @@ -99,9 +100,9 @@ nav: - OpenAI: user-guide/concepts/model-providers/openai.md - SageMaker: user-guide/concepts/model-providers/sagemaker.md - Writer: user-guide/concepts/model-providers/writer.md - - Cohere: user-guide/concepts/model-providers/cohere.md - Custom Providers: user-guide/concepts/model-providers/custom_model_provider.md - - CLOVA Studio community: user-guide/concepts/model-providers/clova-studio.md # ALWAYS ADD A SPACE BEFORE COMMUNITY + - Cohere community: user-guide/concepts/model-providers/cohere.md # ALWAYS ADD A SPACE BEFORE COMMUNITY + - CLOVA Studio community: user-guide/concepts/model-providers/clova-studio.md - Streaming: - Overview: user-guide/concepts/streaming/overview.md - Async Iterators: user-guide/concepts/streaming/async-iterators.md @@ -131,6 +132,7 @@ nav: - Amazon Bedrock AgentCore : user-guide/deploy/deploy_to_bedrock_agentcore.md - Amazon EKS: user-guide/deploy/deploy_to_amazon_eks.md - Amazon EC2: user-guide/deploy/deploy_to_amazon_ec2.md + - Examples: - Overview: examples/README.md - CLI Reference Agent Implementation: examples/python/cli-reference-agent.md @@ -145,6 +147,13 @@ nav: - Meta Tooling: examples/python/meta_tooling.md - MCP: examples/python/mcp_calculator.md - Multi-modal: examples/python/multimodal.md + + - Community: + - Community Packages: community/community-packages.md + - Model Providers: + - Cohere: community/model-providers/cohere.md + - CLOVA Studio: community/model-providers/clova-studio.md + - Contribute ❤️: https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md - API Reference: - Agent: api-reference/agent.md @@ -184,6 +193,8 @@ plugins: User Guide: - README.md - user-guide/**/*.md + Community: + - community/**/*.md Examples: - examples/**/*.md API Reference: