agentscope-ai--agentscope/CONTRIBUTING.md

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. 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 and Issues for items labeled help wanted (see §1). 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 on GitHub.
2. Clone your fork and add the upstream remote:

   git clone https://github.com/<your-username>/agentscope.git
   cd agentscope
   git remote add upstream https://github.com/agentscope-ai/agentscope.git
   

3. Create a topic branch off the latest main:

   git checkout main
   git pull upstream main
   git checkout -b feat/<short-description>
   

   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).

# 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:

  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:

# 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. 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 specification. This keeps commit history readable and enables automatic changelog generation.

<type>(<scope>): <subject>

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:

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.

<type>(<scope>): <description>

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 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.<provider>/, 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.<provider>._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):

   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:

   • <Provider>ChatFormatter for single-user chat scenarios
   • <Provider>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 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 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 instead.

A new example should live in its own subdirectory:

examples/
└── <example-name>/
    ├── 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
• Report bugs via 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.