161 lines
5.5 KiB
Markdown
161 lines
5.5 KiB
Markdown
# How to Contribute
|
|
|
|
Thank you for your interest in AgentScope Samples! AgentScope Samples provides ready-to-use agent examples built on AgentScope and AgentScope Runtime. We welcome all types of contributions, from new sample agent applications to bug fixes and documentation improvements.
|
|
|
|
## Reporting Issues
|
|
|
|
### Bugs
|
|
|
|
Before reporting a bug, please test with the latest version and search existing issues. When submitting a bug report, include:
|
|
|
|
- Clear description of the issue and reproduction steps
|
|
- Code/error messages
|
|
- Environment details (OS, Python version, AgentScope version)
|
|
- Affected examples
|
|
|
|
### Security Issues
|
|
|
|
Report security issues through [Alibaba Security Response Center (ASRC)](https://security.alibaba.com/).
|
|
|
|
## Requesting New Features
|
|
|
|
If you'd like a feature or new type of example that doesn't exist in AgentScope Samples, please open a feature request issue on GitHub describing:
|
|
|
|
- The feature or example and its purpose
|
|
- How it should work
|
|
- What problem it solves or what use case it demonstrates
|
|
|
|
**Note**: If you want to contribute your own example, please also open an issue first to discuss your idea and avoid duplicate work.
|
|
|
|
|
|
|
|
## Contributing Code
|
|
|
|
### Setup
|
|
|
|
1. **Fork and clone** the repository
|
|
|
|
2. **Create a branch**:
|
|
```bash
|
|
git checkout -b feature/your-sample-name
|
|
```
|
|
|
|
### Creating New Examples
|
|
|
|
#### Choose a Relevant Scenario
|
|
|
|
We encourage examples across various domains including (but not limited to):
|
|
|
|
| Domain | Example Ideas |
|
|
|--------|---------------|
|
|
| **Finance** | Robo-advisors, risk assessment, financial report analysis |
|
|
| **Healthcare** | Symptom checker, medical record summarization, medication reminders |
|
|
| **Education** | Personalized tutoring, auto-grading, Q&A knowledge retrieval |
|
|
| **E-commerce / Retail** | Customer service, product recommendation, inventory management |
|
|
| **Gaming / Entertainment** | NPC dialogue systems, dynamic story generators |
|
|
| **Office Automation** | Meeting summarizers, auto-reply email agents, scheduling coordinators |
|
|
| **Research** | Literature review assistants, data analysis agents |
|
|
| **SRE / DevOps** | Alert triage, log anomaly detection, root cause analysis, automated remediation |
|
|
| **General Utilities** | Multi-agent workflows, tool calling, memory management patterns |
|
|
|
|
**Tip**: Pick a domain you know well or are passionate about—realistic use cases have the greatest impact!
|
|
|
|
#### Directory Structure
|
|
|
|
Choose an appropriate category (`browser_use/`, `conversational_agents/`, `deep_research/`, `evaluation/`, `functionality/`, `games/`) and create your example directory. If a suitable category doesn't exist, you can propose a new one in your pull request.
|
|
|
|
**Simple example:**
|
|
```
|
|
your_sample_name/
|
|
├── README.md
|
|
├── main.py
|
|
├── your_agent.py
|
|
└── requirements.txt
|
|
```
|
|
|
|
**Full-stack example** (use `_fullstack_runtime` suffix):
|
|
```
|
|
your_sample_fullstack_runtime/
|
|
├── README.md
|
|
├── backend/
|
|
│ ├── requirements.txt
|
|
│ └── ...
|
|
└── frontend/
|
|
├── package.json
|
|
└── ...
|
|
```
|
|
|
|
#### README.md Requirements (Mandatory)
|
|
|
|
Your README.md **must** include:
|
|
|
|
1. **Title and Description**: What the example demonstrates
|
|
|
|
2. **Project Structure** (mandatory): File tree with descriptions
|
|
```markdown
|
|
## 🌳 Project Structure
|
|
|
|
\`\`\`
|
|
.
|
|
├── README.md # Documentation
|
|
├── main.py # Entry point
|
|
├── agent.py # Agent implementation
|
|
└── requirements.txt # Dependencies
|
|
\`\`\`
|
|
```
|
|
|
|
3. **Prerequisites**: Python version, API keys, etc.
|
|
|
|
4. **Installation**:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
5. **Setup**: Environment variables or configuration steps
|
|
|
|
6. **Usage**: How to run the example
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
#### Standalone Installation
|
|
|
|
Each example must include a standalone `requirements.txt` file listing all necessary dependencies to ensure it can be installed and run independently without relying on other examples.
|
|
|
|
|
|
### Submitting Your Contribution
|
|
|
|
1. **Commit** with clear messages:
|
|
```bash
|
|
git commit -m "Add: new browser automation sample"
|
|
```
|
|
Use prefixes: `Add:`, `Fix:`, `Update:`, `Doc:`
|
|
|
|
2. **Push** to your fork:
|
|
```bash
|
|
git push origin feature/your-sample-name
|
|
```
|
|
|
|
3. **Create a Pull Request** including:
|
|
- Clear description of what the example demonstrates
|
|
- References to related issues (e.g., "Closes #123")
|
|
|
|
4. **Code Review**: Address feedback from maintainers
|
|
|
|
### Recognition for Contributors
|
|
|
|
- Your name will be added to the contributors list
|
|
- Outstanding examples may be featured on the AgentScope website, documentation, or social media
|
|
- You'll be part of a growing community shaping the future of agentic AI!
|
|
|
|
Thank you for contributing to AgentScope Samples! If you have any questions, feel free to reach out through:
|
|
|
|
- **GitHub Discussions**: Ask questions and share experiences (use **English**)
|
|
- **Discord**: Join our Discord channel for real-time discussions
|
|
- **DingTalk**: Chinese users can join our DingTalk group
|
|
|
|
| [Discord](https://discord.gg/eYMpfnkG8h) | DingTalk |
|
|
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|
|
| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="https://img.alicdn.com/imgextra/i4/O1CN014mhqFq1ZlgNuYjxrz_!!6000000003235-2-tps-400-400.png" width="100" height="100"> |
|
|
|