# Contributing to AgentScope Thank you for your interest in contributing to AgentScope! As an open-source project, we warmly welcome and encourage contributions from the community. Whether you're fixing bugs, adding new features, improving documentation, or sharing ideas, your contributions help make AgentScope better for everyone. ## 1. Development Roadmap and How to Get Involved To support the long-term, healthy growth of AgentScope and its open-source community, we keep our development plan transparent and openly tracked. **Our roadmap is public.** The AgentScope development plan is published and continuously updated on our [GitHub Projects page](https://github.com/orgs/agentscope-ai/projects/2). The roadmap reflects the technical direction set by the core team, who are responsible for AgentScope's overall design and quality. **Tasks open to the community.** Items labeled `help wanted` on the Projects page/issues are contribution opportunities open to everyone. If one of these interests you: - Comment on the related issue to let us know you'd like to take it on - This helps us avoid duplicate efforts and coordinate with you early **If you'd like to join the core development.** We warmly welcome contributors who want to go deeper and help shape AgentScope itself. Over time, we plan to gradually invite committed contributors into the core development circle. Before reaching out, we'd like to share a few honest expectations so you can decide whether it's a good fit right now: - Core development involves frequent design discussions, code reviews, and iterative revisions — it asks for a sustained investment of time and energy - To keep AgentScope cohesive and reliable, the core team retains responsibility for the project's technical direction and quality bar; core contributors work within this collaborative process If this fits your situation, please reach out to the core developers — we'd love to talk. **Proposing something new.** If you have an idea that isn't on the roadmap yet, please open a new issue describing your proposal. The core team will respond and discuss it with you so we can find the best path forward together. ## 2. Responsible Use of AI in Contributions AgentScope welcomes contributors who use AI coding assistants — Claude Code, Cursor, Codex, Copilot, and others. We just ask that they be used **responsibly**. AgentScope is sustained by reviewer time and community trust, and AI-assisted contributions need to honor both. A few expectations when AI is involved in your work: - **You — not the AI — are the author.** Read the diff line by line, run it, and make sure you understand *what* changed and *why* before you push. "Claude Code / Cursor / Codex told me to do it" is not an acceptable answer in code review, and is not the kind of behavior that builds a healthy open-source community. PRs whose authors cannot explain their own changes will be closed. - **Review your AI-generated code before opening a PR.** Reviewer time is the most precious resource in this project. Don't outsource your own review to the maintainers by dumping unreviewed AI output into a PR. - **Keep PRs atomic.** Do not submit a 10K+-line PR produced by an AI in a single shot. Such PRs are unreviewable and will be rejected. Break the work into focused, single-purpose PRs the same way a human contributor would. - **AI-assisted code follows the same rules.** All of AgentScope's development principles — modularity, lazy imports, conventional commits, test coverage, no surprise API breaks — apply identically to code written with AI assistance. AI is not an excuse for skipping conventions. The goal is simple: AI helps you move faster, but the responsibility for what lands in AgentScope still rests with you as a human contributor. ## 3. Contribution Workflow End-to-end, contributing a change to AgentScope looks like this. ### Step 1. Claim or create an issue Before writing code, find or open the issue that frames your work. - **Working on an existing item?** Browse [Projects](https://github.com/orgs/agentscope-ai/projects/2) and [Issues](https://github.com/agentscope-ai/agentscope/issues) for items labeled `help wanted` (see [§1](#1-development-roadmap-and-how-to-get-involved)). Comment on the issue to claim it before starting. - **Proposing something new?** Open a new issue describing the problem, your proposed solution, and any design alternatives. Wait for feedback from the core team before starting a non-trivial implementation — this avoids wasted rewrites. ### Step 2. Fork the repo and create a development branch 1. Fork [agentscope-ai/agentscope](https://github.com/agentscope-ai/agentscope) on GitHub. 2. Clone your fork and add the upstream remote: ```bash git clone https://github.com//agentscope.git cd agentscope git remote add upstream https://github.com/agentscope-ai/agentscope.git ``` 3. Create a topic branch off the latest `main`: ```bash git checkout main git pull upstream main git checkout -b feat/ ``` Use a branch name aligned with the change type, e.g., `feat/redis-memory`, `fix/react-agent-leak`, `docs/contributing-update`. ### Step 3. Set up your local environment AgentScope requires **Python 3.11+** (see `pyproject.toml`). ```bash # Create an isolated environment (uv shown; virtualenv / conda also fine) uv venv source .venv/bin/activate # Install AgentScope in editable mode with the dev extras pip install -e ".[dev]" # or, equivalently, with uv: uv pip install -e ".[dev]" # Enable the git pre-commit hooks pre-commit install ``` The `dev` extra pulls in `pre-commit`, `pytest`, the documentation toolchain, and the `full` extra (which itself includes `models`, `service`, and `storage`). A single installation gives you everything needed to develop and run the complete test suite. ### Step 4. Develop A few conventions to follow while writing code: - **Lazy imports for optional dependencies.** Any dependency **not listed in `[project.dependencies]` of `pyproject.toml`** — i.e., anything coming from the optional groups (`gemini`, `ollama`, `xai`, `service`, `storage`, etc.) — **must be lazy-imported** at point of use rather than at module top level: ```python def some_function(): import google.genai # from the `gemini` extra — lazy-imported # ... use google.genai here ``` This keeps `import agentscope` lightweight, and `ImportError` surfaces only when a feature actually relying on the extra is invoked. If your change requires a brand-new dependency, decide first whether it belongs in the base `[project.dependencies]` (always required, kept small) or in one of the optional extras — and discuss it in the issue before merging. - **Follow the project's code style.** Pre-commit handles formatting and most lint rules automatically. Don't fight the formatter. - **Write unit tests alongside features.** Tests live under `tests/` and follow the existing structure. Tests that rely on an optional extra (e.g., Redis, Ollama) should skip cleanly when that extra isn't installed. ### Step 5. Run pre-commit, tests, and update documentation Before opening the PR, run the same checks CI will run: ```bash # Auto-format and lint pre-commit run --all-files # Run the unit tests pytest tests ``` If a pre-commit hook fails, fix the issue (most fixes are applied automatically) and re-stage the files. Don't bypass hooks with `--no-verify`. **Update documentation alongside the code change.** - AgentScope's user-facing documentation lives in a separate repository: **[agentscope-ai/docs](https://github.com/agentscope-ai/docs)**. If your change affects user-facing behavior — new modules, new public APIs, behavior changes, tutorials — please open a companion PR there. - Update inline docstrings and example snippets for any new public APIs. - Update `README.md` if your change affects how users get started or what AgentScope advertises. ### Step 6. Commit and open a pull request **Commit message format.** We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This keeps commit history readable and enables automatic changelog generation. ``` (): ``` **Types:** - `feat:` A new feature - `fix:` A bug fix - `docs:` Documentation only changes - `style:` Changes that do not affect the meaning of the code (whitespace, formatting, etc.) - `refactor:` A code change that neither fixes a bug nor adds a feature - `perf:` A code change that improves performance - `ci:` Adding missing tests or correcting existing tests - `chore:` Changes to the build process or auxiliary tools and libraries **Examples:** ```bash feat(models): add support for Claude-3 model fix(agent): resolve memory leak in ReActAgent docs(readme): update installation instructions refactor(formatter): simplify message formatting logic ci(models): add unit tests for OpenAI integration ``` **Pull request title format.** PR titles follow the same Conventional Commits format and are validated automatically by GitHub Actions on PRs against `main`. PRs with invalid titles will be blocked until corrected. ``` (): ``` **Requirements:** - Title must start with one of: `feat`, `fix`, `docs`, `ci`, `refactor`, `test`, `chore`, `perf`, `style`, `build`, `revert` - Scope is optional but recommended - **Scope must be lowercase** — only lowercase letters, numbers, hyphens (`-`), and underscores (`_`) are allowed - Description should start with a lowercase letter - Keep the title concise and descriptive **Examples:** ``` ✅ Valid: feat(memory): add redis cache support fix(agent): resolve memory leak in ReActAgent docs(tutorial): update installation guide ci(workflow): add PR title validation refactor(my-feature): simplify logic ❌ Invalid: feat(Memory): add cache # Scope must be lowercase feat(MEMORY): add cache # Scope must be lowercase feat(MyFeature): add feature # Scope must be lowercase ``` **Open the PR.** Push your branch to your fork and open a pull request against `agentscope-ai/agentscope:main`. In the PR description: - Link the issue you claimed (`Fixes #123` or `Refs #123`) - Summarize what changed and why - Note any breaking changes, deprecations, or migration steps - Link the companion docs PR in [agentscope-ai/docs](https://github.com/agentscope-ai/docs) if you opened one ## 4. Important Notices A few cross-cutting constraints worth knowing before you start a contribution. Module-specific notices live in the corresponding module guide below. - **Open an issue before non-trivial work.** Surprise PRs that touch many files, change public APIs, or introduce a new module are difficult to review and likely to be rejected. Discuss the design in an issue first. - **Keep PRs focused and atomic.** One PR, one purpose. Don't bundle a refactor with a feature, or a feature with an unrelated bug fix. - **Don't break public APIs without notice.** Maintain backward compatibility when you can. If a breaking change is unavoidable, call it out clearly in the PR description and update the affected examples and docs in the same PR. - **Don't bypass the lazy import principle.** Optional dependencies must be imported at point of use, not at module top level. - **Don't add dependencies casually.** Every new dependency is a long-term maintenance commitment. If a dependency is needed by only one module, prefer a lazy import inside that module. - **Don't ignore CI failures.** Pre-commit, type checks, and tests must pass before a PR is ready for review. Don't push the burden of fixing them onto the reviewer. - **Be respectful.** Follow our Code of Conduct. AgentScope's review culture is direct but kind, and we expect the same from contributors. ## 5. Module-Specific Contribution Guides The notes below cover the modules most commonly extended by community contributors. For other modules, please open an issue first so we can coordinate. ### Chat Model A chat model in AgentScope is more than a single class — to be usable inside an `Agent`, it needs a small set of upstream/downstream pieces. A complete chat-model contribution includes **all** of the following: 1. **Credential class** — under `agentscope.credential`, subclassing `CredentialBase`. Carries the API key, endpoint, and other auth fields your SDK needs. _Reference: `agentscope/credential/_anthropic.py`_ 2. **Chat model class** — under `agentscope.model./`, subclassing `ChatModelBase`. The implementation needs to cover: - Both streaming and non-streaming modes - Tools API integration (function/tool calling) - The `tool_choice` argument - Reasoning models, where applicable _Reference: `agentscope/model/_anthropic/`_ 3. **Model card YAML(s)** — under `agentscope.model.._models/`, one YAML per supported model. Required fields: `name`, `label`, `status`, `input_types`, `output_types`, `context_size`, `output_size`. Optional: `parameter_overrides`, `deprecated_at`. Example (`claude-sonnet-4-6.yaml`): ```yaml name: claude-sonnet-4-6 label: Claude Sonnet 4.6 status: active input_types: - text/plain - image/jpeg output_types: - text/plain context_size: 1000000 output_size: 65536 parameter_overrides: max_tokens: {"maximum": 65536} ``` 4. **Formatter classes** — under `agentscope.formatter`, both subclassing `FormatterBase`. Two variants are required because some APIs treat multi-agent conversations differently from single-user chat: - `ChatFormatter` for single-user chat scenarios - `MultiAgentFormatter` for multi-agent scenarios Each formatter converts `Msg` objects into the request format the provider's API expects. _Reference: `agentscope/formatter/_anthropic_formatter.py`_ > ⚠️ PRs that add only the model class without the matching credential, > model card YAML, and both formatter variants will not be merged. ### Agent AgentScope deliberately maintains a **single core agent class** — `agentscope.agent.Agent` — that integrates all functionality of the AgentScope library (memory, tools, MCP, formatters, models, etc.). For specialized or domain-specific agents, please contribute them as [examples](#examples) rather than as new classes in `agentscope.agent`. If you believe a use case genuinely requires a new top-level agent class: 1. **Open an issue first** describing the use case and explaining why composing existing `Agent` capabilities is insufficient. 2. **Wait for design discussion** with the core team before starting any implementation. 3. PRs that introduce a new agent class without prior discussion will be rejected. ### Workspace A Workspace provides the runtime context an agent operates in (skills, scheduled tasks, etc.). Adding a new workspace backend requires two classes plus documentation: 1. **Workspace class** — under `agentscope.workspace`, subclassing `WorkspaceBase`. Implements the storage and lifecycle semantics of your backend. _Reference: `agentscope/workspace/_local_workspace.py` (`LocalWorkspace`)_ 2. **Workspace manager class** — alongside `agentscope/app/_manager/_workspace_manager.py`, subclassing `WorkspaceManagerBase`. Wires your workspace into the application lifecycle. _Reference: `LocalWorkspaceManager` in the same file._ 3. **Documentation** — open a companion PR in [agentscope-ai/docs](https://github.com/agentscope-ai/docs) describing how to configure and use your workspace. ### Examples We highly encourage contributions of new examples that showcase AgentScope's capabilities. The `examples/` directory in the main repository focuses on **demonstrating specific features and capabilities** — concise, educational reference implementations. For more complete, production-style applications, please contribute them to **[agentscope-samples](https://github.com/agentscope-ai/agentscope-samples)** instead. A new example should live in its own subdirectory: ``` examples/ └── / ├── main.py ├── README.md # explain the example's purpose, how to run it, and expected output └── ... ``` `examples/agent_service/` is a good starting reference. ## Getting Help If you need assistance or have questions: - Open a [Discussion](https://github.com/agentscope-ai/agentscope/discussions) - Report bugs via [Issues](https://github.com/agentscope-ai/agentscope/issues) - Contact the maintainers at DingTalk or Discord (links in the README.md) --- Thank you for contributing to AgentScope! Your efforts help build a better tool for the entire community.