Skip to content

Commit ede0785

Browse files
zastrowmzastrowm
authored
feat: Add community package guidelines + top level community node (#275)
Start building out community docs by adding a new top level community node. Under this node, we have packaging guidelines (new content) + we list out the community-contributed model providers. To maintain backwards compatibility, we have stub pages for the moved cohere/clova-studio that redirect to the moved pages - this required some weird workaround that I hope to remove once we have a new docs CMS --------- Co-authored-by: Mackenzie Zastrow <[email protected]>
1 parent 204e981 commit ede0785

File tree

8 files changed

+269
-166
lines changed

8 files changed

+269
-166
lines changed

‎docs/assets/auto-redirect.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/**
2+
* Auto-redirect to the first link in the markdown.
3+
*
4+
* This is a workaround for mkdocs not supporting redirects in a way that doesn't have a huge-flash of content.
5+
*/
6+
class AutoRedirect extends HTMLElement {
7+
connectedCallback() {
8+
const currentUrl = window.location.href;
9+
const link = this.parentElement.closest(".md-content")?.querySelector("a[href]")
10+
11+
if (link) {
12+
// immediately redirecting makes a flash of content, so do it after a second
13+
setTimeout(() => {
14+
if (currentUrl == window.location.href) {
15+
window.location.replace(link.href);
16+
}
17+
}, 1000)
18+
}
19+
}
20+
}
21+
22+
customElements.define('auto-redirect', AutoRedirect);

‎docs/community/community-packages.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Community Packages
2+
3+
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.
4+
5+
## Creating A Package
6+
7+
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:
8+
9+
- **Create a GitHub repository** - use the naming convention `strands-{thing}` for consistency with the ecosystem.
10+
- **Add detailed documentation** - add a README with usage examples and API references.
11+
- **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.
12+
13+
[strands-clova](https://github.com/aidendef/strands-clova) is a community package that can serve as a good example.
14+
15+
## Publishing to PyPI
16+
17+
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.
18+
19+
Best practices for publishing include:
20+
21+
- **Configure GitHub workflows** - set up CI/CD to automatically publish releases to PyPI when you create new releases.
22+
- **Follow semantic versioning** - use semver.org conventions for version numbering to help users understand the impact of updates.
23+
24+
## Getting Featured in Documentation
25+
26+
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.
27+
28+
Submit your package for consideration by creating an issue in the [Strands Agents documentation repository](https://github.com/strands-agents/docs/issues). Include:
29+
30+
- Package Name: the name your package name and PyPI link
31+
- Description: a brief description of functionality including why it benefits the community.
32+
- Usage examples: how strands customers would wire up and use the components
33+
34+
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.
35+
36+
## Best Practices and Examples
37+
38+
### Model Providers
39+
40+
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.
41+
42+
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).
43+
44+
A good example of a community model provider is [strands-clova](https://github.com/aidendef/strands-clova).
45+
46+
### Tools
47+
48+
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.
49+
50+
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:
51+
52+
- [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
53+
- [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.
54+
55+
## Support & Resources
56+
57+
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.
58+
59+
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).
60+

‎docs/community/model-providers/clova-studio.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# CLOVA Studio
2+
3+
{{ community_contribution_banner }}
4+
5+
[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.
6+
7+
## Installation
8+
9+
CLOVA Studio integration is available as a separate community package:
10+
11+
```bash
12+
pip install strands-agents strands-clova
13+
```
14+
15+
## Usage
16+
17+
After installing `strands-clova`, you can import and initialize the CLOVA Studio provider:
18+
19+
```python
20+
from strands import Agent
21+
from strands_clova import ClovaModel
22+
23+
model = ClovaModel(
24+
api_key="your-clova-api-key", # or set CLOVA_API_KEY env var
25+
model="HCX-005",
26+
temperature=0.7,
27+
max_tokens=2048
28+
)
29+
30+
agent = Agent(model=model)
31+
response = await agent.invoke_async("안녕하세요! 오늘 날씨가 어떤가요?")
32+
print(response.message)
33+
```
34+
35+
## Configuration
36+
37+
### Environment Variables
38+
39+
```bash
40+
export CLOVA_API_KEY="your-api-key"
41+
export CLOVA_REQUEST_ID="optional-request-id" # For request tracking
42+
```
43+
44+
### Model Configuration
45+
46+
The supported configurations are:
47+
48+
| Parameter | Description | Example | Default |
49+
|------------|-------------|---------|---------|
50+
| `model` | Model ID | `HCX-005` | `HCX-005` |
51+
| `temperature` | Sampling temperature (0.0-1.0) | `0.7` | `0.7` |
52+
| `max_tokens` | Maximum tokens to generate | `4096` | `2048` |
53+
| `top_p` | Nucleus sampling parameter | `0.8` | `0.8` |
54+
| `top_k` | Top-k sampling parameter | `0` | `0` |
55+
| `repeat_penalty` | Repetition penalty | `1.1` | `1.1` |
56+
| `stop` | Stop sequences | `["\\n\\n"]` | `[]` |
57+
58+
## Advanced Features
59+
60+
### Korean Language Optimization
61+
62+
CLOVA Studio excels at Korean language tasks:
63+
64+
```python
65+
# Korean customer support bot
66+
model = ClovaModel(api_key="your-api-key", temperature=0.3)
67+
agent = Agent(
68+
model=model,
69+
system_prompt="당신은 친절한 고객 서비스 상담원입니다."
70+
)
71+
72+
response = await agent.invoke_async("제품 반품 절차를 알려주세요")
73+
```
74+
75+
### Bilingual Capabilities
76+
77+
Handle both Korean and English seamlessly:
78+
79+
```python
80+
# Process Korean document and get English summary
81+
response = await agent.invoke_async(
82+
"다음 한국어 문서를 영어로 요약해주세요: [문서 내용]"
83+
)
84+
```
85+
86+
## References
87+
88+
- [strands-clova GitHub Repository](https://github.com/aidendef/strands-clova)
89+
- [CLOVA Studio Documentation](https://www.ncloud.com/product/aiService/clovaStudio)
90+
- [Naver Cloud Platform](https://www.ncloud.com/)

‎docs/community/model-providers/cohere.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Cohere
2+
3+
{{ community_contribution_banner }}
4+
5+
[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.
6+
7+
## Installation
8+
9+
The Strands Agents SDK provides access to Cohere models through the OpenAI compatibility layer, configured as an optional dependency. To install, run:
10+
11+
```bash
12+
pip install 'strands-agents[openai]' strands-agents-tools
13+
```
14+
15+
## Usage
16+
17+
After installing the `openai` package, you can import and initialize the Strands Agents' OpenAI-compatible provider for Cohere models as follows:
18+
19+
```python
20+
from strands import Agent
21+
from strands.models.openai import OpenAIModel
22+
from strands_tools import calculator
23+
24+
model = OpenAIModel(
25+
client_args={
26+
"api_key": "<COHERE_API_KEY>",
27+
"base_url": "https://api.cohere.ai/compatibility/v1", # Cohere compatibility endpoint
28+
},
29+
model_id="command-a-03-2025", # or see https://docs.cohere.com/docs/models
30+
params={
31+
"stream_options": None
32+
}
33+
)
34+
35+
agent = Agent(model=model, tools=[calculator])
36+
agent("What is 2+2?")
37+
```
38+
39+
## Configuration
40+
41+
### Client Configuration
42+
43+
The `client_args` configure the underlying OpenAI-compatible client. When using Cohere, you must set:
44+
45+
* `api_key`: Your Cohere API key. Get one from the [Cohere Dashboard](https://dashboard.cohere.com).
46+
* `base_url`:
47+
* `https://api.cohere.ai/compatibility/v1`
48+
49+
Refer to [OpenAI Python SDK GitHub](https://github.com/openai/openai-python) for full client options.
50+
51+
### Model Configuration
52+
53+
The `model_config` specifies which Cohere model to use and any additional parameters.
54+
55+
| Parameter | Description | Example | Options |
56+
| ---------- | ------------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
57+
| `model_id` | Model name | `command-r-plus` | See [Cohere docs](https://docs.cohere.com/docs/models) |
58+
| `params` | Model-specific parameters | `{"max_tokens": 1000, "temperature": 0.7}` | [API reference](https://docs.cohere.com/docs/compatibility-api) |
59+
60+
## Troubleshooting
61+
62+
### `ModuleNotFoundError: No module named 'openai'`
63+
64+
You must install the `openai` dependency to use this provider:
65+
66+
```bash
67+
pip install 'strands-agents[openai]'
68+
```
69+
70+
### Unexpected model behavior?
71+
72+
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`.
73+
74+
## References
75+
76+
* [Cohere Docs: Using the OpenAI SDK](https://docs.cohere.com/docs/compatibility-api)
77+
* [Cohere API Reference](https://docs.cohere.com/reference)
78+
* [OpenAI Python SDK](https://github.com/openai/openai-python)

‎docs/user-guide/concepts/model-providers/clova-studio.md‎

Lines changed: 2 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,4 @@
1-
# CLOVA Studio
21

3-
{{ community_contribution_banner }}
2+
<auto-redirect />
43

5-
[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.
6-
7-
## Installation
8-
9-
CLOVA Studio integration is available as a separate community package:
10-
11-
```bash
12-
pip install strands-agents strands-clova
13-
```
14-
15-
## Usage
16-
17-
After installing `strands-clova`, you can import and initialize the CLOVA Studio provider:
18-
19-
```python
20-
from strands import Agent
21-
from strands_clova import ClovaModel
22-
23-
model = ClovaModel(
24-
api_key="your-clova-api-key", # or set CLOVA_API_KEY env var
25-
model="HCX-005",
26-
temperature=0.7,
27-
max_tokens=2048
28-
)
29-
30-
agent = Agent(model=model)
31-
response = await agent.invoke_async("안녕하세요! 오늘 날씨가 어떤가요?")
32-
print(response.message)
33-
```
34-
35-
## Configuration
36-
37-
### Environment Variables
38-
39-
```bash
40-
export CLOVA_API_KEY="your-api-key"
41-
export CLOVA_REQUEST_ID="optional-request-id" # For request tracking
42-
```
43-
44-
### Model Configuration
45-
46-
The supported configurations are:
47-
48-
| Parameter | Description | Example | Default |
49-
|------------|-------------|---------|---------|
50-
| `model` | Model ID | `HCX-005` | `HCX-005` |
51-
| `temperature` | Sampling temperature (0.0-1.0) | `0.7` | `0.7` |
52-
| `max_tokens` | Maximum tokens to generate | `4096` | `2048` |
53-
| `top_p` | Nucleus sampling parameter | `0.8` | `0.8` |
54-
| `top_k` | Top-k sampling parameter | `0` | `0` |
55-
| `repeat_penalty` | Repetition penalty | `1.1` | `1.1` |
56-
| `stop` | Stop sequences | `["\\n\\n"]` | `[]` |
57-
58-
## Advanced Features
59-
60-
### Korean Language Optimization
61-
62-
CLOVA Studio excels at Korean language tasks:
63-
64-
```python
65-
# Korean customer support bot
66-
model = ClovaModel(api_key="your-api-key", temperature=0.3)
67-
agent = Agent(
68-
model=model,
69-
system_prompt="당신은 친절한 고객 서비스 상담원입니다."
70-
)
71-
72-
response = await agent.invoke_async("제품 반품 절차를 알려주세요")
73-
```
74-
75-
### Bilingual Capabilities
76-
77-
Handle both Korean and English seamlessly:
78-
79-
```python
80-
# Process Korean document and get English summary
81-
response = await agent.invoke_async(
82-
"다음 한국어 문서를 영어로 요약해주세요: [문서 내용]"
83-
)
84-
```
85-
86-
## References
87-
88-
- [strands-clova GitHub Repository](https://github.com/aidendef/strands-clova)
89-
- [CLOVA Studio Documentation](https://www.ncloud.com/product/aiService/clovaStudio)
90-
- [Naver Cloud Platform](https://www.ncloud.com/)
4+
This guide has moved to [community/model-providers/clova-studio](../../../community/model-providers/clova-studio.md).

0 commit comments

Comments
 (0)