Skip to content

Build and run agents you can see, understand and trust.

docs(readme): udpate the docs for 2.0 release (#1657)

DavdGao50c8716e73df
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 519299fd3..f03ed6243 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,36 +1,199 @@
# Contributing to AgentScope
-## Welcome! 🎉
-Thank you for your interest in contributing to AgentScope! As an open-source project, we warmly welcome and encourage
+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.
-## How to Contribute
+## 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.
-To ensure smooth collaboration and maintain the quality of the project, please follow these guidelines when contributing:
+- **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.
-### 1. Check Existing Plans and Issues
+- **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.
-Before starting your contribution, please review our development roadmap:
+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.
-- **Check the [Projects](https://github.com/orgs/agentscope-ai/projects/2) page** and **[Issues with `roadmap` label](https://github.com/agentscope-ai/agentscope/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)** to see our planned development tasks.
+## 3. Contribution Workflow
- - **If a related issue exists** and is marked as unassigned or open:
- - Please comment on the issue to express your interest in working on it
- - This helps avoid duplicate efforts and allows us to coordinate development
+End-to-end, contributing a change to AgentScope looks like this.
- - **If no related issue exists**:
- - Please create a new issue describing your proposed changes or feature
- - Our team will respond promptly to provide feedback and guidance
- - This helps us maintain the project roadmap and coordinate community efforts
+### Step 1. Claim or create an issue
-### 2. Commit Message Format
+Before writing code, find or open the issue that frames your work.
-We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This leads to more readable
-commit history and enables automatic changelog generation.
+- **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/<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`:
+ ```bash
+ 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`).
+
+```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.
-**Format:**
```
<type>(<scope>): <subject>
```
@@ -39,7 +202,7 @@ commit history and enables automatic changelog generation.
- `feat:` A new feature
- `fix:` A bug fix
- `docs:` Documentation only changes
-- `style:` Changes that do not affect the meaning of the code (white-space, formatting, etc)
+- `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
@@ -54,19 +217,18 @@ refactor(formatter): simplify message formatting logic
ci(models): add unit tests for OpenAI integration
```
-### 3. Pull Request Title Format
-
-Pull request titles must follow the same [Conventional Commits](https://www.conventionalcommits.org/) specification:
+**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.
-**Format:**
```
<type>(<scope>): <description>
```
**Requirements:**
-- The title must start with one of the allowed types: `feat`, `fix`, `docs`, `ci`, `refactor`, `test`, `chore`, `perf`, `style`, `build`, `revert`
+- 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
+- **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
@@ -85,238 +247,174 @@ feat(MEMORY): add cache # Scope must be lowercase
feat(MyFeature): add feature # Scope must be lowercase
```
-**Automated Validation:**
-- PR titles targeting the `main` branch are automatically validated by GitHub Actions
-- PRs with invalid titles will be blocked until the title is corrected
-
-### 4. Code Development Guidelines
-
-#### a. Pre-commit Checks
-
-Before submitting code, you must run pre-commit hooks to ensure code quality and consistency:
-
-**Installation:**
-```bash
-pip install pre-commit
-pre-commit install
-```
-
-**Running pre-commit:**
-```bash
-# Run on all files
-pre-commit run --all-files
-
-# Pre-commit will automatically run on git commit after installation
-```
-
-#### b. Import Statement Guidelines
-
-AgentScope follows a **lazy import principle** to minimize resource loading:
-
-- **DO**: Import modules only when they are actually used
- ```python
- def some_function():
- import openai
- # Use openai library here
- ```
-
-This approach ensures that `import agentscope` remains lightweight and doesn't load unnecessary dependencies.
-
-#### c. Unit Tests
-
-- All new features must include appropriate unit tests
-- Ensure existing tests pass before submitting your PR
-- Run tests using:
- ```bash
- pytest tests
- ```
-
-#### d. Documentation
-
-- Update relevant documentation for new features
-- Include code examples where appropriate
-- Update the README.md if your changes affect user-facing functionality
-
-
-## Types of Contributions
-
-### Adding New Chat Models
-
-AgentScope currently supports the following API providers at the chat model level: **OpenAI**, **DashScope**,
-**Gemini**, **Anthropic**, and **Ollama**. These APIs are compatible with various service providers including vLLM,
-DeepSeek, SGLang, and others.
-
-**⚠️ Important Notice:**
-
-Adding a new chat model is not merely a model-level task. It involves multiple components including:
-- Message formatters
-- Token counters
-- Tools API integration
-
-This is a substantial amount of work. To better focus our efforts on agent capability development and maintenance,
-**the official development team currently does not plan to add support for new chat model APIs**. However, when there
-is a strong need from the developer community, we will do our best to accommodate these requirements.
-
-**If you wish to contribute a new chat model**, here are the components needed to be compatible with the
-existing `ReActAgent` in the repository:
-
-#### Required Components:
-
-1. **Chat Model Class** (under `agentscope.model`):
- ```python
- from agentscope.model import ChatModelBase
-
-
- class YourChatModel(ChatModelBase):
- """
- The functionalities that you need to consider include:
- - Tools API integration
- - Both streaming and non-streaming modes (compatible with tools API)
- - tool_choice argument
- - reasoning models
- """
- ```
-
-2. **Formatter Class** (under `agentscope.formatter`):
- ```python
- from agentscope.formatter import FormatterBase
-
- class YourModelFormatter(FormatterBase):
- """
- Convert `Msg` objects into the format required by your API provider.
- If your API doesn't support multi-agent scenarios (e.g. doesn't support the name field in messages), you need to
- implement two separate formatter classes for chatbot and multi-agent scenarios.
- """
- ```
-
-3. **Token Counter** (under `agentscope.token`, recommended):
- ```python
- from agentscope.token import TokenCounterBase
-
- class YourTokenCounter(TokenCounterBase):
- """
- Implement token counting logic for your model.
- This is recommended but not strictly required.
- """
+**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.<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`):
+ ```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}
```
-### Adding New Agents
+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
-To achieve true modularity, the `agentscope.agent` module currently aims to maintain only the **`ReActAgent`** class
-as the core implementation. We ensure all functionalities in this class are **modular, detachable, and composable**.
+ Each formatter converts `Msg` objects into the request format the
+ provider's API expects.
+ _Reference: `agentscope/formatter/_anthropic_formatter.py`_
-In AgentScope, we follow an examples-first development workflow: prototype new implementations in the `examples/`
-directory, then abstract and modularize the functionality, and finally integrate it into the core library.
+> ⚠️ PRs that add only the model class without the matching credential,
+> model card YAML, and both formatter variants will not be merged.
-For specialized or domain-specific agents, we recommend contributing them to the **`examples/agents`** directory:
+### Agent
-```
-examples/
-└── agents/
- ├── main.py
- ├── README.md # Explain the agent's purpose and usage
- └── ... # The other scripts
-```
+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.).
-### Adding New Examples
+For specialized or domain-specific agents, please contribute them as
+[examples](#examples) rather than as new classes in `agentscope.agent`.
-We highly encourage contributions of new examples that showcase the capabilities of AgentScope! Your examples help others learn and get inspired.
+If you believe a use case genuinely requires a new top-level agent class:
-**📝 About the Examples Directory:**
+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.
-To maintain code quality and keep the repository accessible for everyone, we've designed the `examples/` directory in the main AgentScope repository to focus on **demonstrating AgentScope's functionalities**. Think of these as educational references and feature showcases that help developers quickly understand what AgentScope can do.
+### Workspace
-**What makes a great example here:**
-- Clearly demonstrates specific AgentScope features or capabilities
-- Easy to understand and follow along
-- Serves as a learning material or reference implementation
-- Focused and concise
+A Workspace provides the runtime context an agent operates in (skills,
+scheduled tasks, etc.). Adding a new workspace backend requires two
+classes plus documentation:
-**For More Complex Applications:**
+1. **Workspace class** — under `agentscope.workspace`, subclassing
+ `WorkspaceBase`. Implements the storage and lifecycle semantics of
+ your backend.
+ _Reference: `agentscope/workspace/_local_workspace.py` (`LocalWorkspace`)_
-Have you built something amazing with AgentScope? Perhaps a more sophisticated, production-ready application? That's fantastic! 🎉
+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._
-We'd love to see your work in our **[agentscope-samples](https://github.com/agentscope-ai/agentscope-samples)** repository. This dedicated space is perfect for showcasing complete, real-world applications and sharing your AgentScope-based projects with the community. It's a great way to inspire others and demonstrate the full potential of the AgentScope ecosystem!
+3. **Documentation** — open a companion PR in
+ [agentscope-ai/docs](https://github.com/agentscope-ai/docs) describing
+ how to configure and use your workspace.
-**Example Organization:**
+### Examples
-Examples in the main repository are organized into subdirectories based on their type:
+We highly encourage contributions of new examples that showcase
+AgentScope's capabilities.
-- `examples/agent/` for specialized agents
-- `examples/functionality/` for showcasing specific functionalities of AgentScope
-- `examples/game/` for game-related examples
-- `examples/evaluation/` for evaluation scripts
-- `examples/workflows/` for workflow demonstrations
-- `examples/tuner/` for tuning-related examples
+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.
-An example structure could be:
+A new example should live in its own subdirectory:
```
examples/
-└── {example_type}/
- └── {example_name}/
- ├── main.py
- ├── README.md # Explain the example's purpose and usage
- └── ... # The other scripts
+└── <example-name>/
+ ├── main.py
+ ├── README.md # explain the example's purpose, how to run it, and expected output
+ └── ...
```
-### Adding New Memory Databases
-
-The memory module in AgentScope currently supports:
-
-- **In-memory storage**: For lightweight, temporary memory needs
-- **Relational databases via SQLAlchemy**: For persistent, structured data storage
-- **NoSQL databases**: For flexible schema requirements (e.g., Redis)
-
-**⚠️ Important Notice:**
-
-For **relational databases**, we use **SQLAlchemy** as a unified abstraction layer. SQLAlchemy already supports a wide
-range of SQL databases including PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, and many others.
-
-**Therefore, we do not accept separate implementations for relational databases that are already supported by SQLAlchemy.**
-If you need support for a specific relational database, please ensure it works through the existing SQLAlchemy integration.
-
-**If you wish to contribute a new memory database implementation**, please consider:
-
-1. **For relational databases**: Use the existing SQLAlchemy integration.
-
-2. **For NoSQL databases**: If you're adding support for a new NoSQL database (e.g., MongoDB, Cassandra), please:
- - Implement a new memory class that extends the appropriate base class
- - Add comprehensive unit tests
- - Update documentation accordingly
-
-
-## Do's and Don'ts
-
-### ✅ DO:
-
-- **Start small**: Begin with small, manageable contributions
-- **Communicate early**: Discuss major changes before implementing them
-- **Write tests**: Ensure your code is well-tested
-- **Document your code**: Help others understand your contributions
-- **Follow commit conventions**: Use conventional commit messages
-- **Be respectful**: Follow our Code of Conduct
-- **Ask questions**: If you're unsure about something, just ask!
-
-### ❌ DON'T:
-
-- **Don't surprise us with big pull requests**: Large, unexpected PRs are difficult to review and may not align with project goals. Always open an issue first to discuss major changes
-- **Don't ignore CI failures**: Fix any issues flagged by continuous integration
-- **Don't mix concerns**: Keep PRs focused on a single feature or fix
-- **Don't forget to update tests**: Changes in functionality should be reflected in tests
-- **Don't break existing APIs**: Maintain backward compatibility when possible, or clearly document breaking changes
-- **Don't add unnecessary dependencies**: Keep the core library lightweight
-- **Don't bypass the lazy import principle**: This keeps AgentScope fast to import
+`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)
+- 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. 🚀
+Thank you for contributing to AgentScope! Your efforts help build a better tool for the entire community.
diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md
index 59ac4e397..1244b60f1 100644
--- a/CONTRIBUTING_zh.md
+++ b/CONTRIBUTING_zh.md
@@ -1,317 +1,298 @@
-# 贡献到 AgentScope
+# 为 AgentScope 做贡献
-## 欢迎!🎉
+感谢大家对 AgentScope 的关注!
-感谢开源社区对 AgentScope 项目的关注和支持,作为一个开源项目,我们热烈欢迎并鼓励来自社区的贡献。无论是修复错误、添加新功能、改进文档还是
-分享想法,这些贡献都能帮助 AgentScope 变得更好。
+作为一个开源项目,我们欢迎并鼓励来自社区的贡献。无论是修复 bug、新增功能、完善文档,还是分享想法,每一份贡献都让 AgentScope 变得更好。
-## 如何贡献
+## 1. 开发路线图与参与方式
-为了确保顺利协作并保持项目质量,请在贡献时遵循以下指南:
+为了支持 AgentScope 开源社区的长期健康发展,我们将公开、透明地维护 AgentScope 的开发计划。
-### 1. 检查现有计划和问题
+**路线图公开**。AgentScope 的开发计划会发布在 [GitHub Projects 页面](https://github.com/orgs/agentscope-ai/projects/2),并持续更新。路线图会反映 AgentScope 的技术发展方向,由核心开发团队对 AgentScope 的整体设计与质量负责。
-在开始贡献之前,请查看我们的开发路线图:
+**社区可认领的任务**。Projects 页面 / Issues 中标有 `help wanted` 的条目对所有人开放。如果你有兴趣参与某一项:
-- **查看 [Projects](https://github.com/orgs/agentscope-ai/projects/2) 页面** 和 **[带有 `roadmap` 标签的 Issues](https://github.com/agentscope-ai/agentscope/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)** 以了解我们计划的开发任务。
+- 请在对应 issue 下评论,告知准备认领
+- 这样可以避免重复劳动,也方便我们尽早协作
- - **如果存在相关问题** 并且标记为未分配或开放状态:
- - 请在该问题下评论,表达您有兴趣参与该任务
- - 这有助于协调开发工作,避免重复工作
+**成为核心开发者**。我们欢迎想要更深入参与、共同塑造 AgentScope 的开发者。我们会在合适的时机邀请投入度高的贡献者成为核心开发者。
+成为核心开发者也意味着更频繁的参与到 AgentScope 的开发工作中,包括:
- - **如果不存在相关问题**:
- - 请创建一个新 issue 用以描述对应的更改或功能
- - 我们的团队将及时进行回复并提供反馈
- - 这有助于我们维护项目路线图并协调社区工作
+- 更加频繁的设计讨论、代码评审与多轮迭代,需要持续的时间和精力投入
+- 为保证 AgentScope 的整体一致性与可靠性,核心团队保留对项目技术方向与质量标准的把控
-### 2. 提交信息格式
+**提出新想法**。针对有路线图上还没有的想法,请新建 issue 描述提议。核心开发团队会尽可能地及时回复并一起讨论可行的推进路径。
-AgentScope 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。这使得提交历史更易读,并能够自动生成更新日志。
+## 2. 在贡献中负责任地使用 AI
-**格式:**
-```
-<type>(<scope>): <subject>
-```
+AgentScope 欢迎使用 AI 编码助手的贡献者——Claude Code、Cursor、Codex、Copilot 等等。我们只要求**负责任地使用**。AgentScope 依靠评审者的时间和社区信任运转,AI 辅助的贡献需要兼顾两者。
-**类型:**
-- `feat:` 新功能
-- `fix:` 错误修复
-- `docs:` 仅文档更改
-- `style:` 不影响代码含义的更改(空格、格式等)
-- `refactor:` 既不修复错误也不添加功能的代码更改
-- `perf:` 提高性能的代码更改
-- `ci:` 添加缺失的测试或更正现有测试
-- `chore:` 对构建过程或辅助工具和库的更改
+涉及 AI 时的几条要求:
-**示例:**
-```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
-```
+- **作者是人,不是 AI**。在 push 之前,请逐行阅读 diff,运行代码,确认理解了**改了什么**和**为什么改**。“Claude Code / Cursor / Codex 就是这么写的”并不是一个合适的理由,也不利于开源社区的健康发展。
-### 3. Pull Request 标题格式
+- **创建 PR 前先自行评审 AI 生成的代码**。所有人的事件都是宝贵的资源,请不要将没有审阅过的 AI 代码/改动直接丢给维护者评审。
-Pull Request 标题必须遵循相同的 [Conventional Commits](https://www.conventionalcommits.org/) 规范:
+- **保持 PR 原子化**。不要提交 AI 一次性生成的 10K+ 行 PR,这种 PR 无法评审,会被拒绝。请把改动拆成若干个聚焦原子化功能的、具有单一目标的 PR。
-**格式:**
-```
-<type>(<scope>): <description>
-```
+- **AI 生成代码遵守同样的原则**。AgentScope 的所有开发原则——模块化、惰性导入、约定式提交、测试覆盖、不破坏 API——对 AI 辅助代码同等适用。
-**要求:**
-- 标题必须以允许的类型之一开头:`feat`、`fix`、`docs`、`ci`、`refactor`、`test`、`chore`、`perf`、`style`、`build`、`revert`
-- Scope 是可选的但建议添加
-- **Scope 必须是小写** - 只允许小写字母、数字、连字符(`-`)和下划线(`_`)
-- 描述应以小写字母开头
-- 保持标题简洁且具有描述性
+简而言之:AI 让我们的开发更快,但确保合入 AgentScope 的代码质量责任仍在贡献者本人。
-**示例:**
-```
-✅ 有效:
-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
-
-❌ 无效:
-feat(Memory): add cache # Scope 必须是小写
-feat(MEMORY): add cache # Scope 必须是小写
-feat(MyFeature): add feature # Scope 必须是小写
-```
+## 3. 贡献流程
-**自动化验证:**
-- 针对 `main` 分支的 PR 标题会通过 GitHub Actions 自动验证
-- 标题无效的 PR 将被阻止,直到标题被修正
+端到端的贡献流程如下。
-### 4. 代码开发指南
+### 第 1 步:认领或创建 issue
-#### a. 提交前检查
+在写代码之前,先找到或创建对应的 issue。
-在提交代码之前,请运行 pre-commit 钩子以确保代码质量和一致性:
+- **基于已有任务**:浏览 [Projects](https://github.com/orgs/agentscope-ai/projects/2) 与 [Issues](https://github.com/agentscope-ai/agentscope/issues) 中标有 `help wanted` 的条目(参见 [§1](#1-开发路线图与参与方式)),在 issue 下评论认领后再开始。
+- **提出新想法**:新建 issue 描述问题、方案与设计上的取舍。等待核心开发团队反馈后再开始实现,避免事后大规模返工。
+### 第 2 步:Fork 仓库并创建开发分支
-```bash
-pip install pre-commit
-pre-commit install
-```
+1. 在 GitHub 上 fork [agentscope-ai/agentscope](https://github.com/agentscope-ai/agentscope)。
+2. clone 自己的 fork 并添加 upstream 远端:
+ ```bash
+ git clone https://github.com/<your-username>/agentscope.git
+ cd agentscope
+ git remote add upstream https://github.com/agentscope-ai/agentscope.git
+ ```
+3. 基于最新的 `main` 创建主题分支:
+ ```bash
+ git checkout main
+ git pull upstream main
+ git checkout -b feat/<short-description>
+ ```
+
+### 第 3 步:搭建本地环境
+
+AgentScope 要求 **Python 3.11+**(详见 `pyproject.toml`)。
-**运行 pre-commit:**
```bash
-# 在所有文件上运行
-pre-commit run --all-files
+# 创建隔离环境(这里用 uv,也可用 virtualenv / conda)
+uv venv
+source .venv/bin/activate
+
+# 以可编辑模式安装 AgentScope,并带上 dev extras
+pip install -e ".[dev]"
+# 等价的 uv 写法:
+uv pip install -e ".[dev]"
-# 安装后,pre-commit 将在 git commit 时自动运行
+# 启用 git pre-commit hooks
+pre-commit install
```
-#### b. 关于代码中的 Import
+`dev` extra 会拉入 `pre-commit`、`pytest`、文档工具链以及 `full` extra(包含 `models`、`service`、`storage`)。一次安装即可获得开发与运行完整测试套件所需的一切。
-AgentScope 遵循**懒加载导入原则**以最小化资源加载:
+### 第 4 步:开发
-- **推荐做法**:仅在实际使用时导入模块
+写代码时遵守的几条约定:
+
+- **可选依赖必须惰性导入**。任何**未列在 `pyproject.toml` 的 `[project.dependencies]` 中**的依赖——也就是来自可选 extra(`gemini`、`ollama`、`xai`、`service`、`storage` 等)的——**必须在使用点惰性导入**,而不是放在模块顶部:
```python
def some_function():
- import openai
- # 在此处使用 openai 库
+ import google.genai # 来自 `gemini` extra,惰性导入
+ # ... 在这里使用 google.genai
```
+ 这样保持 `import agentscope` 轻量,`ImportError` 只在实际用到该 extra 的功能时才抛出。如果改动需要引入全新的依赖,先决定它属于基础 `[project.dependencies]`(始终需要、保持精简)还是某个可选 extra,并在 issue 中讨论后再合入。
-这种方法确保 `import agentscope` 是一个轻量操作,不会加载不必要的依赖项。
-
-#### c. 单元测试
-
-- 所有新功能都必须包含适当的单元测试
-- 在提交 PR 之前确保现有测试通过
-- 使用以下命令运行测试:
- ```bash
- pytest tests
- ```
+- **遵守项目代码风格**。pre-commit 会自动处理格式与大部分 lint 规则,请在提交前运行 pre-commit 来修复问题。
-#### d. 文档
+- **功能要配套写单元测试**。测试位于 `tests/` 下,沿用现有结构。依赖可选 extra 的测试(如 Redis、Ollama)在该 extra 未安装时应能干净 skip。
-- 为新功能更新相关文档
-- 在适当的地方包含代码示例
-- 如果更改影响面向用户的功能,请更新 README.md
+### 第 5 步:跑 pre-commit、测试,并更新文档
+创建 PR 之前,请在本地运行如下的命令检查代码格式与功能:
-## 贡献类型
-
-### 添加新的 ChatModel
+```bash
+# 自动格式化与 lint
+pre-commit run --all-files
-AgentScope 目前内置支持以下 API 提供商:**OpenAI**、**DashScope**、**Gemini**、**Anthropic** 和 **Ollama**。
-其中 `OpenAIChatModel` 的实现还兼容不同的服务提供商,如 vLLM,DeepSeek、SGLang 等。
+# 单元测试
+pytest tests
+```
-**⚠️ 重要:**
+如果 pre-commit hook 失败,请修复格式问题(多数会自动修复),然后重新 commit。
-添加新的 ChatModel 不仅涉及模型层面的实现,还涉及到其它组件的配合,具体包括:
-- 消息格式化器(formatter)
-- Token 计数器(token counter)
-- Tools API 集成
+**改代码的同时请更新文档**。
-这意味着添加一个 ChatModel 需要大量的工作来确保其与 AgentScope 生态系统的其他部分无缝集成。
-为了更好地专注于智能体能力开发和维护,**官方开发团队目前不计划添加对新 API 的支持**。
-但是当开发者社区有强烈需求时,我们将尽力满足这些需求。
+- AgentScope 文档放在独立仓库:**[agentscope-ai/docs](https://github.com/agentscope-ai/docs)**。如果改动影响用户可见行为——新模块、新公开 API、行为变化、教程——请在该仓库同步开一个配套 PR。
+- 为新公开 API 更新 docstring 与示例片段。
+- 如果改动影响新手上手或 AgentScope 的对外宣传内容,更新 `README.md`。
-**对于一个 ChatModel 类的实现**,为了与仓库中 `ReActAgent` 兼容,所需要实现的组件如下:
+### 第 6 步:提交与发起 PR
-#### 必需组件:
+**Commit 信息格式**。我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范,便于阅读历史与自动生成 changelog。
-1. **ChatModel**(位于 `agentscope.model` 下):
- ```python
- from agentscope.model import ChatModelBase
+```
+<type>(<scope>): <subject>
+```
+**Type 列表:**
+- `feat:` 新功能
+- `fix:` bug 修复
+- `docs:` 仅文档变更
+- `style:` 不影响代码语义的改动(空白、格式等)
+- `refactor:` 既不是修 bug 也不是加功能的代码改动
+- `perf:` 性能优化
+- `ci:` 增补或修正测试
+- `chore:` 构建流程或辅助工具/库的变更
- class YourChatModel(ChatModelBase):
- """
- 需要考虑的功能包括:
- - 集成 tools API
- - 支持流式和非流式模式,并与 tools API 兼容
- - 支持 tool_choice 参数
- - 考虑支持推理模型
- """
- ```
+**示例:**
+```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
+```
-2. **格式化器类**(位于 `agentscope.formatter` 下):
- ```python
- from agentscope.formatter import FormatterBase
+**PR 标题格式**。PR 标题同样遵循 Conventional Commits 格式,并由 GitHub Actions 在针对 `main` 的 PR 上自动校验。标题不合规的 PR 会被阻止合入,直到修正为止。
- class YourModelFormatter(FormatterBase):
- """
- 将 `Msg` 对象转换为对应 API 提供商所需的格式。
- 如果模型 API 不支持多智能体场景(例如不支持消息中的 name 字段),需要
- 为 chatbot 和多智能体场景分别实现两个格式化器类。
- """
- ```
+```
+<type>(<scope>): <description>
+```
-3. **Token 计数器**(位于 `agentscope.token` 下,推荐):
- ```python
- from agentscope.token import TokenCounterBase
+**要求:**
+- 标题须以下列 type 之一开头:`feat`、`fix`、`docs`、`ci`、`refactor`、`test`、`chore`、`perf`、`style`、`build`、`revert`
+- scope 可选,建议带上
+- **scope 必须小写**——只允许小写字母、数字、连字符(`-`)和下划线(`_`)
+- description 以小写字母开头
+- 标题保持简洁、有信息量
- class YourTokenCounter(TokenCounterBase):
- """
- 为对应模型实现 token 计数逻辑(推荐实现,非严格要求)。
- """
- ```
+**示例:**
+```
+✅ 合规:
+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
+
+❌ 不合规:
+feat(Memory): add cache # scope 必须小写
+feat(MEMORY): add cache # scope 必须小写
+feat(MyFeature): add feature # scope 必须小写
+```
-### 添加新的智能体
+**发起 PR**。把分支 push 到自己的 fork,对 `agentscope-ai/agentscope:main` 发起 pull request。在 PR 描述里:
-为了确保 AgentScope 中所有的功能实现都是**模块化的、可拆卸的和可组合的**,`agentscope.agent` 模块目前仅维护 **`ReActAgent`** 类作为核心实现。
+- 关联认领的 issue(`Fixes #123` 或 `Refs #123`)
+- 概述改了什么、为什么改
+- 标注任何破坏性改动、废弃项或迁移步骤
+- 如果同时开了文档 PR,链接到 [agentscope-ai/docs](https://github.com/agentscope-ai/docs) 的对应 PR
-在 AgentScope 中,我们遵循示例优先的开发工作流程:
+## 4. 重要事项
-- 在 `examples/` 目录中初步实现新的功能
-- 然后将重要功能抽象和模块化,集成到核心库中
-- 修改 `examples/` 目录中的示例以使用新的核心功能
+开始贡献前需要了解的几条横向约束。模块特定的事项见下文对应模块指南。
-对于专门的或特定领域的智能体,我们建议按照以下组织形式将它们贡献到 **`examples/agent`** 目录:
+- **非平凡改动先开 issue**。突然提交涉及大量文件、改动公开 API 或引入新模块的 PR 难以评审,多半会被拒。先在 issue 中讨论设计。
+- **PR 保持聚焦、原子**。一个 PR 一个目的。不要把重构和功能、或功能和不相干的 bug 修复混在一起。
+- **不擅自破坏公开 API**。能保持向后兼容就保持。无法避免的破坏性改动,在 PR 描述中清楚说明,并在同一个 PR 里更新受影响的示例和文档。
+- **不绕过惰性导入原则**。可选依赖必须在使用点导入,不能放在模块顶部。
+- **不随意引入依赖**。每个新依赖都是长期维护负担。如果只有一个模块用到,优先在该模块内部惰性导入。
+- **不忽视 CI 失败**。pre-commit、类型检查、测试必须通过后再发起 review,不要把修复负担推给评审者。
+- **保持尊重**。遵守行为准则。AgentScope 的评审风格直接但友善,对贡献者也是同样期待。
-```
-examples/
-└── agent/
- ├── main.py
- ├── README.md # 解释智能体的目的和用法
- └── ... # 其他脚本
-```
+## 5. 模块特定贡献指南
-### 添加新的示例
+下文覆盖社区贡献者最常扩展的模块。其他模块请先开 issue 协调。
-欢迎开源社区贡献新的示例来展示 AgentScope 的各种功能!
+### Chat Model
-**📝 关于示例目录:**
+AgentScope 中的一个 chat model 不只是一个类——要在 `Agent` 中可用,需要一组上下游配套实现。一个完整的 chat model 贡献需包含**以下全部**:
-为了避免仓库变得过于臃肿,我们将 AgentScope 仓库中的 `examples/` 目录设计为专注于**展示 AgentScope 的功能性**。可以把这些示例看作是指导性的参考和功能展示,帮助开发者快速理解 AgentScope 能做什么。
+1. **Credential 类**——位于 `agentscope.credential`,继承 `CredentialBase`。承载 API key、endpoint 及 SDK 所需的其他鉴权字段。
+ _参考:`agentscope/credential/_anthropic.py`_
-**什么样的示例适合放在这里:**
-- 清晰地展示 AgentScope 的特定功能或能力
-- 易于理解和跟随学习
-- 作为学习材料或参考实现
-- 专注且简洁
+2. **Chat model 类**——位于 `agentscope.model.<provider>/`,继承 `ChatModelBase`。实现需覆盖:
+ - 流式与非流式两种模式
+ - Tools API 集成(function/tool calling)
+ - `tool_choice` 参数
+ - 适用时的 reasoning 模型支持
-**对于更复杂的应用:**
+ _参考:`agentscope/model/_anthropic/`_
-对于更加复杂,生产就绪的应用,我们非常期待在 **[agentscope-samples](https://github.com/agentscope-ai/agentscope-samples)** 仓库中看到您的作品。这个仓库专门用于展示、分享基于 AgentScope 生态搭建的完整的、真实世界的应用。
+3. **Model card YAML**——位于 `agentscope.model.<provider>._models/`,每个支持的模型一份 YAML。必填字段:`name`、`label`、`status`、`input_types`、`output_types`、`context_size`、`output_size`。可选字段:`parameter_overrides`、`deprecated_at`。
-**示例组织方式:**
+ 示例(`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 类**——位于 `agentscope.formatter`,均继承 `FormatterBase`。需要两种变体,因为部分 API 对多 agent 对话与单用户对话的处理方式不同:
+ - `<Provider>ChatFormatter` 处理单用户对话场景
+ - `<Provider>MultiAgentFormatter` 处理多 agent 场景
-- `examples/agent/` 用于专门的智能体
-- `examples/functionality/` 用于展示 AgentScope 的特定功能
-- `examples/game/` 用于游戏相关示例
-- `examples/evaluation/` 用于评估脚本
-- `examples/workflows/` 用于工作流演示
-- `examples/tuner/` 用于微调相关示例
+ 每个 formatter 把 `Msg` 对象转换成对应 provider API 期望的请求格式。
+ _参考:`agentscope/formatter/_anthropic_formatter.py`_
-示例结构如下:
+> ⚠️ 只加 model 类、缺少配套 credential、model card YAML 与两种 formatter 变体的 PR 不会被合入。
-```
-examples/
-└── {example_type}/
- └── {example_name}/
- ├── main.py
- ├── README.md # 解释示例的目的和用法
- └── ... # 其他脚本
-```
+### Agent
-### 添加新的记忆数据库
+AgentScope 目前只维护**一个核心 agent 类**——`agentscope.agent.Agent`——它整合了 AgentScope 库的全部功能(memory、tools、MCP、formatter、model 等)。
-AgentScope 的记忆模块目前支持:
+特定领域或专用 agent 请作为 [example](#examples) 贡献,而不是在 `agentscope.agent` 中新增类。
-- **内存存储**:用于轻量级的临时记忆需求
-- **通过 SQLAlchemy 支持关系型数据库**:用于持久化的结构化数据存储
-- **NoSQL 数据库**:用于灵活的模式需求(例如 Redis)
+如果确信某个用例需要新的顶层 agent 类:
-**⚠️ 请注意:**
+1. **先开 issue**,描述用例并说明为什么组合现有 `Agent` 能力不够。
+2. **等核心团队的设计讨论**,再开始具体的代码实现。
+3. 未经事先讨论就引入新 agent 类的 PR 会被拒绝。
-对于**关系型数据库**,我们使用 **SQLAlchemy** 作为统一的抽象层。SQLAlchemy 已经支持多种 SQL 数据库,包括 PostgreSQL、MySQL、SQLite、Oracle、Microsoft SQL Server 等。
+### Workspace
-**因此,为了保持 AgentScope 代码的整洁,目前不接受为 SQLAlchemy 已经支持的关系型数据库单独实现新的支持。**
-如果您需要支持特定的关系型数据库,请确保通过现有的 SQLAlchemy 集成来实现。
+Workspace 提供 agent 运行所需的运行时上下文(skills、scheduled tasks 等)。新增 workspace 后端需要两个类加配套文档:
-**如果您希望贡献新的记忆数据库实现**,请考虑以下几点:
+1. **Workspace 类**——位于 `agentscope.workspace`,继承 `WorkspaceBase`。实现该后端的存储与生命周期语义。
+ _参考:`agentscope/workspace/_local_workspace.py`(`LocalWorkspace`)_
-1. **对于关系型数据库**:使用现有的 SQLAlchemy 集成。
+2. **Workspace manager 类**——位于 `agentscope/app/_manager/_workspace_manager.py`,继承 `WorkspaceManagerBase`。把 workspace 接入应用生命周期。
+ _参考:同文件中的 `LocalWorkspaceManager`_
-2. **对于 NoSQL 数据库**:如果您要添加对新 NoSQL 数据库的支持(例如 MongoDB、Cassandra),请:
- - 实现一个扩展适当基类的新记忆类
- - 添加全面的单元测试
- - 相应地更新文档
+3. **文档**——在 [agentscope-ai/docs](https://github.com/agentscope-ai/docs) 配套发起 PR,说明该 workspace 的配置与使用方式。
+### Examples
-## Do's and Don'ts
+我们非常欢迎新增展示 AgentScope 能力的 example。
-### ✅ DO
+主仓库 `examples/` 目录聚焦于**演示具体特性与能力**——简洁、教学性的参考实现。更完整、贴近生产形态的应用,请贡献到 **[agentscope-samples](https://github.com/agentscope-ai/agentscope-samples)**。
-- **从小处着手**:从小的、可管理的贡献开始
-- **及早沟通**:在实现主要功能之前进行讨论
-- **编写测试**:确保代码经过充分测试
-- **添加代码注释**:帮助他人理解贡献内容
-- **遵循提交约定**:使用约定式提交消息
-- **保持尊重**:遵守我们的行为准则
-- **提出问题**:如果不确定某事,请提问!
+新 example 放在自己的子目录下:
-### ❌ DON'T
+```
+examples/
+└── <example-name>/
+ ├── main.py
+ ├── README.md # 说明 example 的目的、运行方式与预期输出
+ └── ...
+```
-- **不要用大型 PR 让我们措手不及**:大型的、意外的 PR 难以审查,并且可能与项目目标不一致。在进行重大更改之前,请务必先开启一个问题进行讨论
-- **不要忽略 CI 失败**:修复持续集成标记的任何问题
-- **不要混合关注点**:保持 PR 专注于单一功能的实现或修复
-- **不要忘记更新测试**:功能的更改应反映在测试中
-- **不要破坏现有 API**:在可能的情况下保持向后兼容性,或清楚地记录破坏性更改
-- **不要添加不必要的依赖项**:保持核心库轻量级
-- **不要绕过懒加载导入原则**:确保 AgentScope 在导入阶段不至于臃肿
+`examples/agent_service/` 是不错的参考起点。
## 获取帮助
-如果需要帮助或有疑问:
+需要协助或有问题,可以:
-- 💬 开启一个 [Discussion](https://github.com/agentscope-ai/agentscope/discussions)
-- 🐛 通过 [Issues](https://github.com/agentscope-ai/agentscope/issues) 报告错误
-- 📧 通过钉钉交流群或 Discord 联系开发团队(链接在 README.md 中)
+- 发起 [Discussion](https://github.com/agentscope-ai/agentscope/discussions)
+- 在 [Issues](https://github.com/agentscope-ai/agentscope/issues) 中报告 bug
+- 通过钉钉或 Discord 联系维护者(链接见 README.md)
---
-感谢为 AgentScope 做出贡献!🚀
-
+感谢您为 AgentScope 所做的贡献!每一份努力都在为社区构建更好的开源工具。
diff --git a/README.md b/README.md
index 85fbddd18..9173f35ec 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
<span align="center">
-[**中文主页**](https://github.com/agentscope-ai/agentscope/blob/main/README_zh.md) | [**Tutorial**](https://doc.agentscope.io/) | [**Roadmap (Jan 2026 -)**](https://github.com/agentscope-ai/agentscope/blob/main/docs/roadmap.md) | [**FAQ**](https://doc.agentscope.io/tutorial/faq.html)
+[**中文主页**](https://github.com/agentscope-ai/agentscope/blob/main/README_zh.md) | [**Tutorial**](https://docs.agentscope.io/) | [**Roadmap**](https://github.com/orgs/agentscope-ai/projects/2/views/1)
</span>
@@ -21,7 +21,7 @@
</a>
<a href="https://pypi.org/project/agentscope/">
<img
- src="https://img.shields.io/badge/python-3.10+-blue?logo=python"
+ src="https://img.shields.io/badge/python-3.11+-blue?logo=python"
alt="pypi"
/>
</a>
@@ -37,7 +37,7 @@
alt="discord"
/>
</a>
- <a href="https://doc.agentscope.io/">
+ <a href="https://docs.agentscope.io/">
<img
src="https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown"
alt="docs"
@@ -55,9 +55,9 @@
<img src="https://trendshift.io/api/badge/repositories/20310" alt="agentscope-ai%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
</p>
-## What is AgentScope?
+## What is AgentScope 2.0?
-AgentScope is a production-ready, easy-to-use agent framework with essential abstractions that work with rising model capability and built-in support for finetuning.
+AgentScope 2.0 is a production-ready, easy-to-use agent framework with essential abstractions that work with rising model capability and built-in support for finetuning.
We design for increasingly agentic LLMs.
Our approach leverages the models' reasoning and tool use abilities
@@ -69,27 +69,11 @@ rather than constraining them with strict prompts and opinionated orchestrations
- **Extensible**: large number of ecosystem integrations for tools, memory and observability; built-in support for MCP and A2A; message hub for flexible multi-agent orchestration and workflows
- **Production-ready**: deploy and serve your agents locally, as serverless in the cloud, or on your K8s cluster with built-in OTel support
-
-<p align="center">
-<img src="./assets/images/agentscope.png" width="90%" />
-<br/>
-The AgentScope Ecosystem
-</p>
-
+<img src="assets/images/agentscope.png" alt="agentscope" width="100%"/>
## News
<!-- BEGIN NEWS -->
-- **[2026-03] `RELS`:** We recently developed and open sourced an AI assistant named [CoPaw](https://github.com/agentscope-ai/CoPaw) (Co Personal Agent Workstation), built upon [AgentScope](https://github.com/agentscope-ai/agentscope), [AgentScope-Runtime](https://github.com/agentscope-ai/agentscope-runtime), and [Reme](https://github.com/agentscope-ai/ReMe).
-- **[2026-02] `FEAT`:** Realtime Voice Agent support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent) | [Multi-Agent Realtime Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime) | [Tutorial](https://doc.agentscope.io/tutorial/task_realtime.html)
-- **[2026-01] `COMM`:** Biweekly Meetings launched to share ecosystem updates and development plans - join us! [Details & Schedule](https://github.com/agentscope-ai/agentscope/discussions/1126)
-- **[2026-01] `FEAT`:** Database support & memory compression in memory module. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/short_term_memory/memory_compression) | [Tutorial](https://doc.agentscope.io/tutorial/task_memory.html)
-- **[2025-12] `INTG`:** A2A (Agent-to-Agent) protocol support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/a2a_agent) | [Tutorial](https://doc.agentscope.io/tutorial/task_a2a.html)
-- **[2025-12] `FEAT`:** TTS (Text-to-Speech) support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/tts) | [Tutorial](https://doc.agentscope.io/tutorial/task_tts.html)
-- **[2025-11] `INTG`:** Anthropic Agent Skill support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_skill) | [Tutorial](https://doc.agentscope.io/tutorial/task_agent_skill.html)
-- **[2025-11] `RELS`:** Alias-Agent for diverse real-world tasks and Data-Juicer Agent for data processing open-sourced. [Alias-Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/alias) | [Data-Juicer Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/data_juicer_agent)
-- **[2025-11] `INTG`:** Agentic RL via Trinity-RFT library. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning) | [Trinity-RFT](https://github.com/agentscope-ai/Trinity-RFT)
-- **[2025-11] `INTG`:** ReMe for enhanced long-term memory. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory/reme)
-- **[2025-11] `RELS`:** agentscope-samples repository launched and agentscope-runtime upgraded with Docker/K8s deployment and VNC-powered GUI sandboxes. [Samples](https://github.com/agentscope-ai/agentscope-samples) | [Runtime](https://github.com/agentscope-ai/agentscope-runtime)
+- **[2026-05] `RELS`:** AgentScope 2.0 released! [Docs](https://docs.agentscope.io/)
<!-- END NEWS -->
[More news →](./docs/NEWS.md)
@@ -110,22 +94,8 @@ Welcome to join our community on
- [Installation](#installation)
- [From PyPI](#from-pypi)
- [From source](#from-source)
-- [Example](#example)
- - [Hello AgentScope!](#hello-agentscope)
- - [Voice Agent](#voice-agent)
- - [Realtime Voice Agent](#realtime-voice-agent)
- - [Human-in-the-loop](#human-in-the-loop)
- - [Flexible MCP Usage](#flexible-mcp-usage)
- - [Agentic RL](#agentic-rl)
- - [Multi-Agent Workflows](#multi-agent-workflows)
-- [Documentation](#documentation)
-- [More Examples & Samples](#more-examples--samples)
- - [Functionality](#functionality)
- - [Agent](#agent)
- - [Game](#game)
- - [Workflow](#workflow)
- - [Evaluation](#evaluation)
- - [Tuner](#tuner)
+- [Hello AgentScope!](#hello-agentscope)
+- [Agent Service](#agent-service)
- [Contributing](#contributing)
- [License](#license)
- [Publications](#publications)
@@ -137,18 +107,14 @@ Welcome to join our community on
### Installation
-> AgentScope requires **Python 3.10** or higher.
+> AgentScope requires **Python 3.11** or higher.
#### From PyPI
-```bash
-pip install agentscope
-```
-
-Or with uv:
-
```bash
uv pip install agentscope
+# or
+# pip install agentscope
```
#### From source
@@ -160,209 +126,93 @@ git clone -b main https://github.com/agentscope-ai/agentscope.git
# Install the package in editable mode
cd agentscope
-pip install -e .
-# or with uv:
-# uv pip install -e .
+uv pip install -e .
+# or
+# pip install -e .
```
+## Hello AgentScope!
-## Example
-
-### Hello AgentScope!
-
-Start with a conversation between user and a ReAct agent 🤖 named "Friday"!
+Start your first agent in 5 minutes with AgentScope 2.0:
```python
-from agentscope.agent import ReActAgent, UserAgent
+from agentscope.agent import Agent
+from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
+from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.tool import Toolkit, execute_python_code, execute_shell_command
-import os, asyncio
+from agentscope.message import UserMsg
+from agentscope.event import EventType
+import os, asyncio
-async def main():
- toolkit = Toolkit()
- toolkit.register_tool_function(execute_python_code)
- toolkit.register_tool_function(execute_shell_command)
- agent = ReActAgent(
+async def main() -> None:
+ agent = Agent(
name="Friday",
- sys_prompt="You're a helpful assistant named Friday.",
+ system_prompt="You're a helpful assistant named Friday.",
model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=True,
+ credential=DashScopeCredential(
+ api_key=os.environ["DASHSCOPE_API_KEY"]
+ ),
+ model="qwen3.6-plus",
+ ),
+ toolkit=Toolkit(
+ tools=[
+ Bash(),
+ Grep(),
+ Glob(),
+ Read(),
+ Write(),
+ Edit(),
+ ]
),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
)
- user = UserAgent(name="user")
-
- msg = None
- while True:
- msg = await agent(msg)
- msg = await user(msg)
- if msg.get_text_content() == "exit":
- break
+ async for evt in agent.reply_stream(UserMsg("Tony", "Hi, Friday!")):
+ # Handle the event stream, e.g., print the message, update UI, etc.
+ match evt.type:
+ case EventType.REPLY_START:
+ ...
+ case EventType.MODEL_CALL_START:
+ ...
+ case EventType.TEXT_BLOCK_START:
+ ...
+ case EventType.TEXT_BLOCK_DELTA:
+ ...
+ case EventType.TEXT_BLOCK_END:
+ ...
+
+ # Handle other event types
asyncio.run(main())
```
-### Voice Agent
-
-Create a voice-enabled ReAct agent that can understand and respond with speech, even playing a multi-agent werewolf game with voice interactions.
-
-
-https://github.com/user-attachments/assets/c5f05254-aff6-4375-90df-85e8da95d5da
-
-
-### Realtime Voice Agent
-
-Build a realtime voice agent with web interface that can interact with users via voice input and output.
-
-[Realtime chatbot](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent) | [Realtime Multi-Agent Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime)
-
-https://github.com/user-attachments/assets/1b7b114b-e995-4586-9b3f-d3bb9fcd2558
-
-
-
-### Human-in-the-loop
-
-Support realtime interruption in ReActAgent: conversation can be interrupted via cancellation in realtime and resumed
-seamlessly via robust memory preservation.
+## Agent Service
-<img src="./assets/images/realtime_steering_en.gif" alt="Realtime Steering" width="60%"/>
+An extensible FastAPI based **multi-tenancy**, **multi-session** agent service with pre-built Web UI in `examples/web_ui`
-### Flexible MCP Usage
-
-Use individual MCP tools as **local callable functions** to compose toolkits or wrap into a more complex tool.
-
-```python
-from agentscope.mcp import HttpStatelessClient
-from agentscope.tool import Toolkit
-import os
-
-async def fine_grained_mcp_control():
- # Initialize the MCP client
- client = HttpStatelessClient(
- name="gaode_mcp",
- transport="streamable_http",
- url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
- )
-
- # Obtain the MCP tool as a **local callable function**, and use it anywhere
- func = await client.get_callable_function(func_name="maps_geo")
-
- # Option 1: Call directly
- await func(address="Tiananmen Square", city="Beijing")
+```bash
+git clone https://github.com/agentscope-ai/agentscope
- # Option 2: Pass to agent as a tool
- toolkit = Toolkit()
- toolkit.register_tool_function(func)
- # ...
+cd agentscope/examples/agent_service
- # Option 3: Wrap into a more complex tool
- # ...
+# start the agent service backend
+python main.py
```
-### Agentic RL
+Then open another terminal to start the web UI:
-Train your agentic application seamlessly with Reinforcement Learning integration. We also prepare multiple sample projects covering various scenarios:
-
-| Example | Description | Model | Training Result |
-|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------|------------------------|-----------------------------|
-| [Math Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/math_agent) | Tune a math-solving agent with multi-step reasoning. | Qwen3-0.6B | Accuracy: 75% → 85% |
-| [Frozen Lake](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/frozen_lake) | Train an agent to navigate the Frozen Lake environment. | Qwen2.5-3B-Instruct | Success rate: 15% → 86% |
-| [Learn to Ask](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/learn_to_ask) | Tune agents using LLM-as-a-judge for automated feedback. | Qwen2.5-7B-Instruct | Accuracy: 47% → 92% |
-| [Email Search](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/email_search) | Improve tool-use capabilities without labeled ground truth. | Qwen3-4B-Instruct-2507 | Accuracy: 60% |
-| [Werewolf Game](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/werewolves) | Train agents for strategic multi-agent game interactions. | Qwen2.5-7B-Instruct | Werewolf win rate: 50% → 80% |
-| [Data Augment](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/data_augment) | Generate synthetic training data to enhance tuning results. | Qwen3-0.6B | AIME-24 accuracy: 20% → 60% |
-
-### Multi-Agent Workflows
-
-AgentScope provides ``MsgHub`` and pipelines to streamline multi-agent conversations, offering efficient message routing and seamless information sharing
+```bash
+cd agentscope/examples/web_ui
-```python
-from agentscope.pipeline import MsgHub, sequential_pipeline
-from agentscope.message import Msg
-import asyncio
-
-async def multi_agent_conversation():
- # Create agents
- agent1 = ...
- agent2 = ...
- agent3 = ...
- agent4 = ...
-
- # Create a message hub to manage multi-agent conversation
- async with MsgHub(
- participants=[agent1, agent2, agent3],
- announcement=Msg("Host", "Introduce yourselves.", "assistant")
- ) as hub:
- # Speak in a sequential manner
- await sequential_pipeline([agent1, agent2, agent3])
- # Dynamic manage the participants
- hub.add(agent4)
- hub.delete(agent3)
- await hub.broadcast(Msg("Host", "Goodbye!", "assistant"))
-
-asyncio.run(multi_agent_conversation())
+# start the webui
+pnpm install
+pnpm dev
```
+Experience a chat-style interface to interact with your agents.
-## Documentation
-
-- [Tutorial](https://doc.agentscope.io/tutorial/)
-- [FAQ](https://doc.agentscope.io/tutorial/faq.html)
-- [API Docs](https://doc.agentscope.io/api/agentscope.html)
-
-## More Examples & Samples
-
-### Functionality
-
-- [MCP](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/mcp)
-- [Anthropic Agent Skill](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_skill)
-- [Plan](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/plan)
-- [Structured Output](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/structured_output)
-- [RAG](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/rag)
-- [Long-Term Memory](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory)
-- [Session with SQLite](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/session_with_sqlite)
-- [Stream Printing Messages](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/stream_printing_messages)
-- [TTS](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/tts)
-- [Code-first Deployment](https://github.com/agentscope-ai/agentscope/tree/main/examples/deployment/planning_agent)
-- [Memory Compression](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/short_term_memory/memory_compression)
-
-### Agent
-
-- [ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/react_agent)
-- [Voice Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent)
-- [Deep Research Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/deep_research_agent)
-- [Browser-use Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/browser_agent)
-- [Meta Planner Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/meta_planner_agent)
-- [A2A Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/a2a_agent)
-- [Realtime Voice Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent)
-
-### Game
-
-- [Nine-player Werewolves](https://github.com/agentscope-ai/agentscope/tree/main/examples/game/werewolves)
-
-### Workflow
-
-- [Multi-agent Debate](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_debate)
-- [Multi-agent Conversation](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_conversation)
-- [Multi-agent Concurrent](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_concurrent)
-- [Multi-agent Realtime Conversation](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime)
-
-### Evaluation
-
-- [ACEBench](https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench)
-
-### Tuner
-
-- [Tune ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning)
+<img src="https://gw.alicdn.com/imgextra/i1/O1CN01vGGiBw20agWwpzmjy_!!6000000006866-2-tps-2934-1732.png" alt="Permission System" width="100%">
## Contributing
diff --git a/README_zh.md b/README_zh.md
index 3ce8d7aa4..4a5bedda4 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -8,7 +8,7 @@
<span align="center">
-[**English Homepage**](https://github.com/agentscope-ai/agentscope/blob/main/README.md) | [**Tutorial**](https://doc.agentscope.io/zh_CN/) | [**Roadmap (Jan 2026 -)**](https://github.com/agentscope-ai/agentscope/blob/main/docs/roadmap.md) | [**FAQ**](https://doc.agentscope.io/zh_CN/tutorial/faq.html)
+[**English Homepage**](https://github.com/agentscope-ai/agentscope/blob/main/README.md) | [**教程**](https://docs.agentscope.io/) | [**路线图**](https://github.com/orgs/agentscope-ai/projects/2/views/1)
</span>
@@ -21,7 +21,7 @@
</a>
<a href="https://pypi.org/project/agentscope/">
<img
- src="https://img.shields.io/badge/python-3.10+-blue?logo=python"
+ src="https://img.shields.io/badge/python-3.11+-blue?logo=python"
alt="pypi"
/>
</a>
@@ -37,7 +37,7 @@
alt="discord"
/>
</a>
- <a href="https://doc.agentscope.io/">
+ <a href="https://docs.agentscope.io/">
<img
src="https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown"
alt="docs"
@@ -55,46 +55,32 @@
<img src="https://trendshift.io/api/badge/repositories/20310" alt="agentscope-ai%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
</p>
-## What is AgentScope?
+## 什么是 AgentScope 2.0?
-AgentScope 是一款企业级开箱即用的智能体框架,提供灵活的核心抽象以适配不断进化的模型能力,并原生支持模型微调。
+AgentScope 2.0 是一款生产就绪、易于使用的智能体框架,提供与不断进化的模型能力相匹配的核心抽象,并内置对模型微调的支持。
-我们为新一代自主智能的大语言模型而生。 我们的理念是释放模型的推理与工具调用潜能,而不是用僵化的提示工程和预设流程束缚它们的手脚。
+我们为日益自主的大语言模型而设计。
+我们的方法是充分发挥模型的推理与工具调用能力,
+而不是用严格的提示词和固化的编排方式来束缚它们。
-## Why use AgentScope?
+## 为什么选择 AgentScope?
-- **简单**: 使用内置的 ReAct 智能体、工具、技能、人机协作、记忆、计划、实时语音、评估和模型微调轻松构建智能体应用
-- **可扩展**: 大量生态系统集成,包括工具、记忆和可观察性;内置 MCP 和 A2A 支持;消息中心(MsgHub)提供灵活的多智能体编排能力
-- **生产就绪**: 在本地、云端 Serverless 或 K8s 集群上轻松部署智能体应用,并内置 OTel 可观察性支持
+- **简单**:通过内置的 ReAct 智能体、工具、技能、人机协作干预、记忆、计划、实时语音、评估和模型微调,5 分钟即可开始构建你的智能体
+- **可扩展**:丰富的生态系统集成,覆盖工具、记忆和可观测性;内置 MCP 和 A2A 支持;通过消息中心(MsgHub)实现灵活的多智能体编排和工作流
+- **生产就绪**:支持本地部署、云端 Serverless 部署或 K8s 集群部署,并内置 OTel 支持
+<img src="assets/images/agentscope.png" alt="agentscope" width="100%"/>
-<p align="center">
-<img src="./assets/images/agentscope.png" width="90%" alt="AgentScope 生态系统" />
-<br/>
-AgentScope 生态
-</p>
-
-
-## 📢 新闻
+## 新闻
<!-- BEGIN NEWS -->
-- **[2026-03] `发布`:** 我们最近发布了一个名为 [CoPaw](https://github.com/agentscope-ai/CoPaw)(Co Personal Agent Workstation)的个人助理型产品,它基于 [AgentScope](https://github.com/agentscope-ai/agentscope)、[AgentScope-Runtime](https://github.com/agentscope-ai/agentscope-runtime) 和 [Reme](https://github.com/agentscope-ai/ReMe) 构建。
-- **[2026-02] `功能`:** 支持实时语音交互。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent) | [多智能体实时交互](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime) | [文档](https://doc.agentscope.io/tutorial/task_realtime.html)
-- **[2026-01] `社区`:** AgentScope 双周会议启动,分享生态更新和开发计划 - 欢迎加入![详情与安排](https://github.com/agentscope-ai/agentscope/discussions/1126)
-- **[2026-01] `功能`:** 记忆模块新增数据库支持和记忆压缩。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/short_term_memory/memory_compression) | [教程](https://doc.agentscope.io/tutorial/task_memory.html)
-- **[2025-12] `集成`:** A2A(智能体间通信)协议支持。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/a2a_agent) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_a2a.html)
-- **[2025-12] `功能`:** TTS(文本转语音)支持。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/tts) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_tts.html)
-- **[2025-11] `集成`:** Anthropic Agent Skill 支持。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_skill) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_agent_skill.html)
-- **[2025-11] `发布`:** 面向多样化真实任务的 Alias-Agent 和数据处理的 Data-Juicer Agent 开源。[Alias-Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/alias) | [Data-Juicer Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/data_juicer_agent)
-- **[2025-11] `集成`:** 通过 Trinity-RFT 库实现智能体强化学习。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning) | [Trinity-RFT](https://github.com/agentscope-ai/Trinity-RFT)
-- **[2025-11] `集成`:** ReMe 增强长期记忆。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory/reme)
-- **[2025-11] `发布`:** agentscope-samples 样例库上线,agentscope-runtime 升级支持 Docker/K8s 部署和 VNC 图形沙盒。[样例库](https://github.com/agentscope-ai/agentscope-samples) | [Runtime](https://github.com/agentscope-ai/agentscope-runtime)
+- **[2026-05] `发布`:** AgentScope 2.0 已发布![文档](https://docs.agentscope.io/)
<!-- END NEWS -->
[更多新闻 →](./docs/NEWS_zh.md)
-## 联系我们
+## 社区
-欢迎加入我们的社区!
+欢迎加入我们的社区
| [Discord](https://discord.gg/eYMpfnkG8h) | 钉钉 |
|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
@@ -108,22 +94,8 @@ AgentScope 生态
- [安装](#%E5%AE%89%E8%A3%85)
- [从 PyPI 安装](#%E4%BB%8E-pypi-%E5%AE%89%E8%A3%85)
- [从源码安装](#%E4%BB%8E%E6%BA%90%E7%A0%81%E5%AE%89%E8%A3%85)
-- [样例](#%E6%A0%B7%E4%BE%8B)
- - [Hello AgentScope!](#hello-agentscope)
- - [语音智能体](#%E8%AF%AD%E9%9F%B3%E6%99%BA%E8%83%BD%E4%BD%93)
- - [实时语音智能体](#%E5%AE%9E%E6%97%B6%E8%AF%AD%E9%9F%B3%E6%99%BA%E8%83%BD%E4%BD%93)
- - [人机协作](#%E4%BA%BA%E6%9C%BA%E5%8D%8F%E4%BD%9C)
- - [灵活的 MCP 控制](#%E7%81%B5%E6%B4%BB%E7%9A%84-mcp-%E6%8E%A7%E5%88%B6)
- - [智能体强化学习](#%E6%99%BA%E8%83%BD%E4%BD%93%E5%BC%BA%E5%8C%96%E5%AD%A6%E4%B9%A0)
- - [多智能体工作流](#%E5%A4%9A%E6%99%BA%E8%83%BD%E4%BD%93%E5%B7%A5%E4%BD%9C%E6%B5%81)
-- [文档](#%E6%96%87%E6%A1%A3)
-- [更多样例](#%E6%9B%B4%E5%A4%9A%E6%A0%B7%E4%BE%8B)
- - [功能](#%E5%8A%9F%E8%83%BD)
- - [智能体](#%E6%99%BA%E8%83%BD%E4%BD%93)
- - [游戏](#%E6%B8%B8%E6%88%8F)
- - [工作流](#%E5%B7%A5%E4%BD%9C%E6%B5%81)
- - [评估](#%E8%AF%84%E4%BC%B0)
- - [微调](#%E5%BE%AE%E8%B0%83)
+- [Hello AgentScope!](#hello-agentscope)
+- [智能体服务](#%E6%99%BA%E8%83%BD%E4%BD%93%E6%9C%8D%E5%8A%A1)
- [贡献](#%E8%B4%A1%E7%8C%AE)
- [许可](#%E8%AE%B8%E5%8F%AF)
- [论文](#%E8%AE%BA%E6%96%87)
@@ -135,18 +107,14 @@ AgentScope 生态
### 安装
-> AgentScope 需要 **Python 3.10** 或更高版本。
+> AgentScope 需要 **Python 3.11** 或更高版本。
#### 从 PyPI 安装
-```bash
-pip install agentscope
-```
-
-或使用 uv:
-
```bash
uv pip install agentscope
+# 或者
+# pip install agentscope
```
#### 从源码安装
@@ -155,214 +123,101 @@ uv pip install agentscope
# 从 GitHub 拉取源码
git clone -b main https://github.com/agentscope-ai/agentscope.git
-# 以可编辑模式安装包
+# 以可编辑模式安装
cd agentscope
-pip install -e .
-# 或使用 uv:
-# uv pip install -e .
+uv pip install -e .
+# 或者
+# pip install -e .
```
-## 样例
-
-### Hello AgentScope!
+## Hello AgentScope!
-开始与名为"Friday"的 ReAct 智能体 🤖 进行对话!
+使用 AgentScope 2.0,启动你的第一个智能体:
```python
-from agentscope.agent import ReActAgent, UserAgent
+from agentscope.agent import Agent
+from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
+from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.tool import Toolkit, execute_python_code, execute_shell_command
-import os, asyncio
+from agentscope.message import UserMsg
+from agentscope.event import EventType
+import os, asyncio
-async def main():
- toolkit = Toolkit()
- toolkit.register_tool_function(execute_python_code)
- toolkit.register_tool_function(execute_shell_command)
- agent = ReActAgent(
+async def main() -> None:
+ agent = Agent(
name="Friday",
- sys_prompt="You're a helpful assistant named Friday.",
+ system_prompt="You're a helpful assistant named Friday.",
model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=True,
+ credential=DashScopeCredential(
+ api_key=os.environ["DASHSCOPE_API_KEY"]
+ ),
+ model="qwen3.6-plus",
+ ),
+ toolkit=Toolkit(
+ tools=[
+ Bash(),
+ Grep(),
+ Glob(),
+ Read(),
+ Write(),
+ Edit(),
+ ]
),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
)
- user = UserAgent(name="user")
-
- msg = None
- while True:
- msg = await agent(msg)
- msg = await user(msg)
- if msg.get_text_content() == "exit":
- break
+ async for evt in agent.reply_stream(UserMsg("Tony", "Hi, Friday!")):
+ # 处理事件流,例如打印消息、更新 UI 等
+ match evt.type:
+ case EventType.REPLY_START:
+ ...
+ case EventType.MODEL_CALL_START:
+ ...
+ case EventType.TEXT_BLOCK_START:
+ ...
+ case EventType.TEXT_BLOCK_DELTA:
+ ...
+ case EventType.TEXT_BLOCK_END:
+ ...
+
+ # 处理其他事件类型
asyncio.run(main())
```
-### 语音智能体
-
-创建支持语音的 ReAct 智能体,能够理解语音并进行语音回复,还可以使用语音交互玩多智能体狼人杀游戏。
-
-https://github.com/user-attachments/assets/559af387-fd6f-4f0c-b882-cd4778214801
-
-
-### 实时语音智能体
-
-使用 AgentScope 轻松构建实时交互的智能体应用,提供统一的事件接口和工具调用支持。
-
-[实时语音智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent) | [多智能体实时交互](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime)
-
-https://github.com/user-attachments/assets/d9674ad5-f71d-43d5-a341-5bada318aee0
-
-
-
-### 人机协作
-
-在 ReActAgent 中支持实时打断:可以通过取消操作实时中断对话,并通过强大的记忆保留机制无缝恢复。
-
-<img src="./assets/images/realtime_steering_zh.gif" alt="Realtime Steering" width="60%"/>
+## 智能体服务
-### 灵活的 MCP 控制
+一个基于 FastAPI 的可扩展**多租户**、**多会话**智能体服务,并在 `examples/web_ui` 中提供预构建的 Web UI
-AgentScope 支持将单个 MCP 工具作为**本地可调用函数**使用,装备给智能体或封装为更复杂的工具。
-
-```python
-from agentscope.mcp import HttpStatelessClient
-from agentscope.tool import Toolkit
-import os
-
-async def fine_grained_mcp_control():
- # 以高德MCP为例,初始化MCP客户端
- client = HttpStatelessClient(
- name="gaode_mcp",
- transport="streamable_http",
- url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
- )
-
- # 将 MCP 工具获取为**本地可调用函数**,并在任何地方使用
- func = await client.get_callable_function(func_name="maps_geo")
-
- # 选项 1:直接调用
- await func(address="天安门广场", city="北京")
+```bash
+git clone https://github.com/agentscope-ai/agentscope
- # 选项 2:作为工具传递给智能体
- toolkit = Toolkit()
- toolkit.register_tool_function(func)
- # ...
+cd agentscope/examples/agent_service
- # 选项 3:包装为更复杂的工具
- # ...
+# 启动智能体服务后端
+python main.py
```
-### 智能体强化学习
-
-通过强化学习集成无缝训练智能体应用。我们还准备了涵盖各种场景的样例项目:
+然后打开另一个终端启动 Web UI:
-| 样例 | 描述 | 模型 | 训练结果 |
-|--------------------------------------------------------------------------------------------------|----------------------------|------------------------|-----------------------------|
-| [Math Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/math_agent) | 通过多步推理调优数学求解智能体。 | Qwen3-0.6B | Accuracy: 75% → 85% |
-| [Frozen Lake](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/frozen_lake) | 训练智能体进行冰湖游戏。 | Qwen2.5-3B-Instruct | Success rate: 15% → 86% |
-| [Learn to Ask](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/learn_to_ask) | 使用 LLM 作为评判获得自动反馈,从而调优智能体。 | Qwen2.5-7B-Instruct | Accuracy: 47% → 92% |
-| [Email Search](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/email_search) | 在训练数据没有标注真值的情况下提升工具使用能力。 | Qwen3-4B-Instruct-2507 | Accuracy: 60% |
-| [Werewolf Game](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/werewolves) | 训练智能体进行战略性多智能体游戏互动。 | Qwen2.5-7B-Instruct | 狼人胜率:50% → 80% |
-| [Data Augment](https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner/data_augment) | 生成合成训练数据以增强调优结果。 | Qwen3-0.6B | AIME-24 accuracy: 20% → 60% |
-
-### 多智能体工作流
-
-AgentScope 提供 ``MsgHub`` 和 pipeline 来简化多智能体对话,提供高效的消息路由和无缝信息共享
+```bash
+cd agentscope/examples/web_ui
-```python
-from agentscope.pipeline import MsgHub, sequential_pipeline
-from agentscope.message import Msg
-import asyncio
-
-async def multi_agent_conversation():
- # 创建智能体
- agent1 = ...
- agent2 = ...
- agent3 = ...
- agent4 = ...
-
- # 创建消息中心来管理多智能体对话
- async with MsgHub(
- participants=[agent1, agent2, agent3],
- announcement=Msg("Host", "请介绍一下自己。", "assistant")
- ) as hub:
- # 按顺序发言
- await sequential_pipeline([agent1, agent2, agent3])
- # 动态管理参与者
- hub.add(agent4)
- hub.delete(agent3)
- await hub.broadcast(Msg("Host", "再见!", "assistant"))
-
-asyncio.run(multi_agent_conversation())
+# 启动 webui
+pnpm install
+pnpm dev
```
+体验聊天式界面,与你的智能体进行交互。
-## 文档
-
-- [教程](https://doc.agentscope.io/zh_CN/tutorial/)
-- [常见问题](https://doc.agentscope.io/zh_CN/tutorial/faq.html)
-- [API 文档](https://doc.agentscope.io/zh_CN/api/agentscope.html)
-
-## 更多样例
-
-### 功能
-
-- [MCP](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/mcp)
-- [Anthropic 智能体技能](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_skill)
-- [计划](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/plan)
-- [结构化输出](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/structured_output)
-- [RAG](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/rag)
-- [长期记忆](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory)
-- [基于 SQLite 的会话管理](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/session_with_sqlite)
-- [流式打印消息](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/stream_printing_messages)
-- [TTS](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/tts)
-- [高代码部署](https://github.com/agentscope-ai/agentscope/tree/main/examples/deployment/planning_agent)
-- [记忆压缩](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/short_term_memory/memory_compression)
-
-### 智能体
-
-- [ReAct 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/react_agent)
-- [语音智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent)
-- [Deep Research 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/deep_research_agent)
-- [Browser-use 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/browser_agent)
-- [Meta Planner 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/meta_planner_agent)
-- [A2A 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/a2a_agent)
-- [实时语音交互智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent)
-
-### 游戏
-
-- [九人制狼人杀](https://github.com/agentscope-ai/agentscope/tree/main/examples/game/werewolves)
-
-### 工作流
-
-- [多智能体辩论](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_debate)
-- [多智能体对话](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_conversation)
-- [多智能体并发](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_concurrent)
-- [多智能体实时语音交互](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime)
-
-### 评估
-
-- [ACEBench](https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench)
-
-### 微调
-
-- [调优 ReAct 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning)
+<img src="https://gw.alicdn.com/imgextra/i1/O1CN01vGGiBw20agWwpzmjy_!!6000000006866-2-tps-2934-1732.png" alt="Permission System" width="100%">
## 贡献
-我们欢迎社区的贡献!请参阅我们的 [贡献指南](./CONTRIBUTING_zh.md) 了解如何贡献到 AgentScope。
+我们欢迎社区的贡献!请参阅我们的 [贡献指南](./CONTRIBUTING_zh.md) 了解如何贡献。
## 许可
@@ -378,7 +233,7 @@ AgentScope 基于 Apache License 2.0 发布。
```
@article{agentscope_v1,
- author = {Dawei Gao, Zitao Li, Yuexiang Xie, Weirui Kuang, Liuyi Yao, Bingchen Qian, Zhijian Ma, Yue Cui, Haohao Luo, Shen Li, Lu Yi, Yi Yu, Shiqi He, Zhiling Luo, Wenmeng Zhou, Zhicheng Zhang, Xuguang He, Ziqian Chen, Weikai Liao, Farruh Isakulovich Kushnazarov, Yaliang Li, Bolin Ding, Jingren Zhou},
+ author = {Dawei Gao, Zitao Li, Yuexiang Xie, Weirui Kuang, Liuyi Yao, Bingchen Qian, Zhijian Ma, Yue Cui, Haohao Luo, Shen Li, Lu Yi, Yi Yu, Shiqi He, Zhiling Luo, Wenmeng Zhou, Zhicheng Zhang, Xuguang He, Ziqian Chen, Weikai Liao, Farruh Isakulovich Kushnazarov, Yaliang Li, Bolin Ding, Jingren Zhou}
title = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications},
journal = {CoRR},
volume = {abs/2508.16279},
@@ -386,7 +241,7 @@ AgentScope 基于 Apache License 2.0 发布。
}
@article{agentscope,
- author = {Dawei Gao, Zitao Li, Xuchen Pan, Weirui Kuang, Zhijian Ma, Bingchen Qian, Fei Wei, Wenhao Zhang, Yuexiang Xie, Daoyuan Chen, Liuyi Yao, Hongyi Peng, Zeyu Zhang, Lin Zhu, Chen Cheng, Hongzhu Shi, Yaliang Li, Bolin Ding, Jingren Zhou},
+ author = {Dawei Gao, Zitao Li, Xuchen Pan, Weirui Kuang, Zhijian Ma, Bingchen Qian, Fei Wei, Wenhao Zhang, Yuexiang Xie, Daoyuan Chen, Liuyi Yao, Hongyi Peng, Zeyu Zhang, Lin Zhu, Chen Cheng, Hongzhu Shi, Yaliang Li, Bolin Ding, Jingren Zhou}
title = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
journal = {CoRR},
volume = {abs/2402.14034},
@@ -399,5 +254,5 @@ AgentScope 基于 Apache License 2.0 发布。
感谢所有贡献者:
<a href="https://github.com/agentscope-ai/agentscope/graphs/contributors">
- <img src="https://contrib.rocks/image?repo=agentscope-ai/agentscope&max=999&columns=12&anon=1" alt="贡献者" />
+ <img src="https://contrib.rocks/image?repo=agentscope-ai/agentscope&max=999&columns=12&anon=1" />
</a>
diff --git a/assets/images/agentscope.png b/assets/images/agentscope.png
index a34cdad78..0c02c6487 100644
Binary files a/assets/images/agentscope.png and b/assets/images/agentscope.png differ
diff --git a/assets/images/realtime_steering_en.gif b/assets/images/realtime_steering_en.gif
deleted file mode 100644
index 1e5b3846b..000000000
Binary files a/assets/images/realtime_steering_en.gif and /dev/null differ
diff --git a/assets/images/realtime_steering_zh.gif b/assets/images/realtime_steering_zh.gif
deleted file mode 100644
index 034e2591c..000000000
Binary files a/assets/images/realtime_steering_zh.gif and /dev/null differ
diff --git a/docs/FAQ.md b/docs/FAQ.md
deleted file mode 100644
index fdd5bc52b..000000000
--- a/docs/FAQ.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# AgentScope FAQ
-
----
-
-## AgentScope Core Framework
-
-### Q1: Does AgentScope's Workstation still exist?
-
-**A**: No. Since **AgentScope 1.0**, the project has fully transitioned to a **code-first development approach** and no longer maintains the earlier drag-and-drop Workstation interface. **It is not recommended to use Workstation in new projects**.
-
----
-
-### Q2: Why do different LLMs require different Formatters?
-
-**A**: Different LLM providers (e.g., OpenAI, Anthropic, DashScope) have different requirements for input message formats (such as role fields and tool call structures). AgentScope uses **Formatters to decouple model differences**, ensuring generated messages conform to each API's specifications. Even models that claim OpenAI compatibility may require separate adaptation due to version lag.
-
----
-
-### Q3: Does AgentScope support the MCP (Model Control Protocol)?
-
-**A**: Yes. AgentScope is compatible with the standard MCP protocol for integrating external tools and services. Tutorial reference: [MCP User Guide](https://docs.agentscope.io).
-
----
-
-### Q4: Are there community-developed AgentScope applications beyond the official examples?
-
-**A**: Yes! Check out the [agentscope-samples](https://github.com/agentscope-ai/agentscope-samples) repository, which contains community-contributed examples including Werewolf, debates, intelligent customer service, and more.
-
----
-
-### Q5: What is the difference between model fine-tuning and memory retrieval?
-
-**A**:
-
-* **Model fine-tuning**: Modifies model parameters through training to improve performance on specific tasks.
-
-* **Memory retrieval**: Injects relevant context during inference via vector databases or similar methods. The two are **not mutually exclusive and can even be combined** — for example, fine-tuning a model to better leverage retrieved memory information.
-
-
----
-
-### Q6: What is the relationship between AgentScope-Java and Spring AI Alibaba?
-
-**A**:
-
-* **AgentScope-Java** is the Java implementation of AgentScope, currently under development, aiming to maintain consistency with the Python version in philosophy, design, and functionality.
-
-* **Spring AI Alibaba** has **switched its underlying layer to AgentScope-Java**, focusing on Spring ecosystem integration. If you use Spring AI Alibaba's Agentic API, future upgrades will automatically provide AgentScope capabilities — **no need to separately introduce AgentScope-Java**.
-
-
----
-
-### Q7: Can AgentScope be used with AI coding assistants like Cursor or Claude Code?
-
-**A**: Absolutely! AgentScope has a clean code structure and comprehensive documentation, making it well-suited for use with AI coding assistants. It is recommended to provide AgentScope source code or tutorials as context to the AI for better results.
diff --git a/docs/FAQ_zh.md b/docs/FAQ_zh.md
deleted file mode 100644
index cead4cd71..000000000
--- a/docs/FAQ_zh.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# AgentScope 常见问题 (FAQ)
-
----
-
-## AgentScope 核心框架
-
-### Q1:AgentScope 的 Workstation(工作站)还存在吗?
-
-**A**:不存在了。从 **AgentScope 1.0 起**,项目已全面转向 **代码优先(code-first)的开发模式**,不再维护早期的拖拽式 Workstation 界面。**不建议在新项目中使用 Workstation**。
-
----
-
-### Q2:为什么不同大模型需要不同的 Formatter?
-
-**A**:不同大模型厂商(如 OpenAI、Anthropic、通义千问等)对输入消息格式(如 role 字段、工具调用结构)有不同要求。AgentScope 通过 **Formatter 解耦模型差异**,确保生成的消息符合各 API 规范。即使某些模型声称兼容 OpenAI,也可能因版本滞后需单独适配。
-
----
-
-### Q3:AgentScope 是否支持 MCP(Model Control Protocol)协议?
-
-**A**:支持。AgentScope 兼容标准 MCP 协议,可用于对接外部工具或服务。教程参考:[MCP 使用指南](https://docs.agentscope.io)。
-
----
-
-### Q4:除了官方示例,是否有社区开发的 AgentScope 应用?
-
-**A**:有!可查看 [agentscope-samples](https://github.com/agentscope-ai/agentscope-samples) 仓库,其中包含社区贡献的狼人杀、辩论、智能客服等多种场景示例。
-
----
-
-### Q5:模型微调和记忆召回有什么区别?
-
-**A**:
-
-* **模型微调**:通过训练修改模型参数,提升特定任务能力。
-
-* **记忆召回**:在推理时通过向量数据库等方式注入相关上下文。 两者**不冲突,甚至可结合使用**——例如微调一个模型使其更擅长利用召回的记忆信息。
-
-
----
-
-### Q6:AgentScope-Java 和 Spring AI Alibaba 是什么关系?
-
-**A**:
-
-* **AgentScope-Java** 是 AgentScope 的 Java 实现,目前仍在建设中,目标是与 Python 版在理念、设计和功能上保持一致。
-
-* **Spring AI Alibaba** 将**底层切换为 AgentScope-Java**,专注 Spring 生态集成。如果你使用 Spring AI Alibaba 的 Agentic API,后续升级即可自动获得 AgentScope 能力,**无需单独引入 AgentScope-Java**。
-
-
----
-
-### Q7:能否配合 Cursor、Claude Code 等 AI 编程助手使用 AgentScope?
-
-**A**:完全可以!AgentScope 代码结构清晰、文档完善,非常适合与 AI 编程助手配合。建议将 AgentScope 源码或教程作为上下文提供给 AI,效果更佳。
-
diff --git a/docs/NEWS.md b/docs/NEWS.md
index ed90cfd0e..4a39a6f4d 100644
--- a/docs/NEWS.md
+++ b/docs/NEWS.md
@@ -2,22 +2,4 @@
<!-- The first 10 items are automatically synced to README.md and README_zh.md via GitHub Actions. -->
<!-- To update news in READMEs, modify this file and push to trigger the workflow. -->
-- **[2026-02] `FEAT`:** Realtime Voice Agent support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent) | [Multi-Agent Realtime Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime) | [Tutorial](https://doc.agentscope.io/tutorial/task_realtime.html)
-- **[2026-01] `COMM`:** Biweekly Meetings launched to share ecosystem updates and development plans - join us! [Details & Schedule](https://github.com/agentscope-ai/agentscope/discussions/1126)
-- **[2026-01] `FEAT`:** Database support & memory compression in memory module. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/short_term_memory/memory_compression) | [Tutorial](https://doc.agentscope.io/tutorial/task_memory.html)
-- **[2025-12] `INTG`:** A2A (Agent-to-Agent) protocol support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/a2a_agent) | [Tutorial](https://doc.agentscope.io/tutorial/task_a2a.html)
-- **[2025-12] `FEAT`:** TTS (Text-to-Speech) support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/tts) | [Tutorial](https://doc.agentscope.io/tutorial/task_tts.html)
-- **[2025-11] `INTG`:** Anthropic Agent Skill support. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_skill) | [Tutorial](https://doc.agentscope.io/tutorial/task_agent_skill.html)
-- **[2025-11] `RELS`:** Alias-Agent for diverse real-world tasks and Data-Juicer Agent for data processing open-sourced. [Alias-Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/alias) | [Data-Juicer Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/data_juicer_agent)
-- **[2025-11] `INTG`:** Agentic RL via Trinity-RFT library. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning) | [Trinity-RFT](https://github.com/agentscope-ai/Trinity-RFT)
-- **[2025-11] `INTG`:** ReMe for enhanced long-term memory. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory/reme)
-- **[2025-11] `RELS`:** agentscope-samples repository launched and agentscope-runtime upgraded with Docker/K8s deployment and VNC-powered GUI sandboxes. [Samples](https://github.com/agentscope-ai/agentscope-samples) | [Runtime](https://github.com/agentscope-ai/agentscope-runtime)
-- **[2025-11] `DOCS`:** Contributing Guide is online - welcome to contribute! [Guide](./CONTRIBUTING.md)
-- **[2025-09] `FEAT`:** RAG module released. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/rag) | [Tutorial](https://doc.agentscope.io/tutorial/task_rag.html)
-- **[2025-09] `FEAT`:** Voice agent support - ReActAgent now supports Qwen-Omni and GPT-Audio natively. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent) | [Roadmap](https://github.com/agentscope-ai/agentscope/issues/773)
-- **[2025-09] `FEAT`:** Plan module released. [Tutorial](https://doc.agentscope.io/tutorial/task_plan.html)
-- **[2025-09] `RELS`:** AgentScope Runtime open-sourced - enabling effective agent deployment with sandboxed tool execution. [GitHub](https://github.com/agentscope-ai/agentscope-runtime)
-- **[2025-09] `RELS`:** AgentScope Studio open-sourced. [GitHub](https://github.com/agentscope-ai/agentscope-studio)
-- **[2025-08] `DOCS`:** Tutorial v1 is online. [Tutorial](https://doc.agentscope.io)
-- **[2025-08] `RELS`:** AgentScope v1 released - fully embracing asynchronous execution with many new features and improvements. [Changelog](https://github.com/agentscope-ai/agentscope/blob/main/docs/changelog.md)
-
+- **[2026-05] `RELS`:** AgentScope 2.0 released! [Docs](https://docs.agentscope.io/)
\ No newline at end of file
diff --git a/docs/NEWS_zh.md b/docs/NEWS_zh.md
index ea54d0230..9b7453e35 100644
--- a/docs/NEWS_zh.md
+++ b/docs/NEWS_zh.md
@@ -2,21 +2,4 @@
<!-- The first 10 items are automatically synced to README.md and README_zh.md via GitHub Actions. -->
<!-- To update news in READMEs, modify this file and push to trigger the workflow. -->
-- **[2026-02] `功能`:** 支持实时语音交互。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/realtime_voice_agent) | [多智能体实时交互](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_realtime) | [文档](https://doc.agentscope.io/tutorial/task_realtime.html)
-- **[2026-01] `社区`:** AgentScope 双周会议启动,分享生态更新和开发计划 - 欢迎加入![详情与安排](https://github.com/agentscope-ai/agentscope/discussions/1126)
-- **[2026-01] `功能`:** 记忆模块新增数据库支持和记忆压缩。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/short_term_memory/memory_compression) | [教程](https://doc.agentscope.io/tutorial/task_memory.html)
-- **[2025-12] `集成`:** A2A(智能体间通信)协议支持。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/a2a_agent) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_a2a.html)
-- **[2025-12] `功能`:** TTS(文本转语音)支持。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/tts) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_tts.html)
-- **[2025-11] `集成`:** Anthropic Agent Skill 支持。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_skill) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_agent_skill.html)
-- **[2025-11] `发布`:** 面向多样化真实任务的 Alias-Agent 和数据处理的 Data-Juicer Agent 开源。[Alias-Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/alias) | [Data-Juicer Agent](https://github.com/agentscope-ai/agentscope-samples/tree/main/data_juicer_agent)
-- **[2025-11] `集成`:** 通过 Trinity-RFT 库实现智能体强化学习。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning) | [Trinity-RFT](https://github.com/agentscope-ai/Trinity-RFT)
-- **[2025-11] `集成`:** ReMe 增强长期记忆。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory/reme)
-- **[2025-11] `发布`:** agentscope-samples 样例库上线,agentscope-runtime 升级支持 Docker/K8s 部署和 VNC 图形沙盒。[样例库](https://github.com/agentscope-ai/agentscope-samples) | [Runtime](https://github.com/agentscope-ai/agentscope-runtime)
-- **[2025-11] `文档`:** 贡献指南上线 - 欢迎参与贡献![指南](./CONTRIBUTING_zh.md)
-- **[2025-09] `功能`:** RAG 模块发布。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/rag) | [教程](https://doc.agentscope.io/zh_CN/tutorial/task_rag.html)
-- **[2025-09] `功能`:** 语音智能体支持 - ReActAgent 原生支持 Qwen-Omni 和 GPT-Audio。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent) | [Roadmap](https://github.com/agentscope-ai/agentscope/issues/773)
-- **[2025-09] `功能`:** Plan 模块发布。[教程](https://doc.agentscope.io/zh_CN/tutorial/task_plan.html)
-- **[2025-09] `发布`:** AgentScope Runtime 开源 - 支持沙盒化工具执行的高效智能体部署。[GitHub](https://github.com/agentscope-ai/agentscope-runtime)
-- **[2025-09] `发布`:** AgentScope Studio 开源。[GitHub](https://github.com/agentscope-ai/agentscope-studio)
-- **[2025-08] `文档`:** v1 版本教程上线。[教程](https://doc.agentscope.io/zh_CN/)
-- **[2025-08] `发布`:** AgentScope v1 发布 - 全面拥抱异步执行,诸多新功能和改进。[变更日志](https://github.com/agentscope-ai/agentscope/blob/main/docs/changelog.md)
\ No newline at end of file
+- **[2026-05] `发布`:** AgentScope 2.0 已发布![文档](https://docs.agentscope.io/)
\ No newline at end of file