Upload folder using huggingface_hub

.gemini/styleguide.md

@@ -0,0 +1,96 @@
+# AgentScope Code Review Guide
+
+You should conduct a strict code review. Each requirement is labeled with priority:
+- **[MUST]** must be satisfied or PR will be rejected
+- **[SHOULD]** strongly recommended
+- **[MAY]** optional suggestion
+
+## 1. Code Quality
+
+### [MUST] Lazy Loading
+- Third-party library dependencies should be imported at the point of use, avoid centralized imports at file top
+  - The `Third-party library` refers to libraries not included in the `dependencies` variable in `pyproject.toml`.
+- For base class imports, use factory pattern:
+```python
+def get_xxx_cls() -> "MyClass":
+    from xxx import BaseClass
+    class MyClass(BaseClass): ...
+    return MyClass
+```
+
+### [SHOULD] Code Conciseness
+After understanding the code intent, check if it can be optimized:
+- Avoid unnecessary temporary variables
+- Merge duplicate code blocks
+- Prioritize reusing existing utility functions
+
+### [MUST] Encapsulation Standards
+- All Python files under `src/agentscope` should be named with `_` prefix, and exposure controlled through `__init__.py`
+- Classes and functions used internally by the framework that don't need to be exposed to users must be named with `_` prefix
+
+## 2. [MUST] Code Security
+- Prohibit hardcoding API keys/tokens/passwords
+- Use environment variables or configuration files for management
+- Check for debug information and temporary credentials
+- Check for injection attack risks (SQL/command/code injection, etc.)
+
+## 3. [MUST] Testing & Dependencies
+- New features must include unit tests
+- New dependencies need to be added to the corresponding section in `pyproject.toml`
+- Dependencies for non-core scenarios should not be added to the minimal dependency list
+
+## 4. Code Standards
+
+### [MUST] Comment Standards
+- **Use English**
+- All classes/methods must have complete docstrings, strictly following the template:
+```python
+def func(a: str, b: int | None = None) -> str:
+    """{description}
+
+    Args:
+        a (`str`):
+            The argument a
+        b (`int | None`, optional):
+            The argument b
+
+    Returns:
+        `str`:
+            The return str
+    """
+```
+- Use reStructuredText syntax for special content:
+```python
+class MyClass:
+    """xxx
+
+    `Example link <https://xxx>`_
+
+    .. note:: Example note
+
+    .. tip:: Example tip
+
+    .. important:: Example important info
+
+    .. code-block:: python
+
+        def hello_world():
+            print("Hello world!")
+
+    """
+```
+
+### [MUST] Pre-commit Checks
+- **Strict review**: In most cases, code should be modified rather than skipping checks
+- **File-level check skipping is prohibited**
+- Only allowed skip: agent class system prompt parameters (to avoid `\n` formatting issues)
+
+---
+
+## 5. Git Standards
+
+### [MUST] PR Title
+- Follow Conventional Commits
+- Must use prefixes: `feat/fix/docs/ci/refactor/test`, etc.
+- Format: `feat(scope): description`
+- Example: `feat(memory): add redis cache support`

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/images/agentscope.png filter=lfs diff=lfs merge=lfs -text
+assets/images/bg_tool.gif filter=lfs diff=lfs merge=lfs -text
+assets/images/permission_bypass.gif filter=lfs diff=lfs merge=lfs -text
+assets/images/task.gif filter=lfs diff=lfs merge=lfs -text
+assets/images/team.gif filter=lfs diff=lfs merge=lfs -text
+scripts/model_examples/test.jpeg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,161 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+.idea/
+
+# macOS
+.DS_Store
+
+# docs
+docs/tutorial/en/build/
+docs/tutorial/zh_CN/build/
+
+# Sphinx build artifacts
+docs/tutorial/**/doctrees/
+docs/tutorial/**/.doctrees/
+*.buildinfo
+*.pickle
+
+node_modules/
+package-lock.json
+*.tsbuildinfo
+.wireit/
+.angular/
+uv.lock
+
+# JS/Node frontend (examples/web_ui)
+*.local
+.eslintcache
+.vite/
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*

.pre-commit-config.yaml

@@ -0,0 +1,116 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: check-ast
+      - id: sort-simple-yaml
+      - id: check-yaml
+        exclude: |
+          (?x)^(
+              meta.yaml
+          )$
+      - id: check-xml
+      - id: check-toml
+      - id: check-docstring-first
+      - id: check-json
+        exclude: |
+          (?x)^(
+              .*tsconfig(\.[^.]+)?\.json
+          )$
+      - id: fix-encoding-pragma
+      - id: detect-private-key
+      - id: trailing-whitespace
+  - repo: https://github.com/asottile/add-trailing-comma
+    rev: v3.1.0
+    hooks:
+      - id: add-trailing-comma
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.7.0
+    hooks:
+      - id: mypy
+        exclude:
+            (?x)(
+                pb2\.py$
+                | grpc\.py$
+                | ^docs
+                | \.html$
+            )
+        args: [ --disallow-untyped-defs,
+                --disallow-incomplete-defs,
+                --ignore-missing-imports,
+                --disable-error-code=var-annotated,
+                --disable-error-code=union-attr,
+                --disable-error-code=assignment,
+                --disable-error-code=attr-defined,
+                --disable-error-code=import-untyped,
+                --disable-error-code=truthy-function,
+                --disable-error-code=typeddict-item,
+                --follow-imports=skip,
+                --explicit-package-bases,
+                ]
+  # - repo: https://github.com/numpy/numpydoc
+  #   rev: v1.6.0
+  #   hooks:
+  #     - id: numpydoc-validation
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+    - id: black
+      args: [--line-length=79]
+  - repo: https://github.com/PyCQA/flake8
+    rev: 6.1.0
+    hooks:
+      - id: flake8
+        args: ["--extend-ignore=E203"]
+        exclude: ^docs
+  - repo: https://github.com/pylint-dev/pylint
+    rev: v3.0.2
+    hooks:
+      - id: pylint
+        exclude:
+            (?x)(
+                ^docs
+                | pb2\.py$
+                | grpc\.py$
+                | \.demo$
+                | \.md$
+                | \.html$
+                | ^examples/paper_llm_based_algorithm/
+          )
+        args: [
+          --disable=W0511,
+          --disable=W0718,
+          --disable=W0122,
+          --disable=C0103,
+          --disable=R0913,
+          --disable=E0401,
+          --disable=E1101,
+          --disable=C0415,
+          --disable=W0603,
+          --disable=R1705,
+          --disable=R0914,
+          --disable=E0601,
+          --disable=W0602,
+          --disable=W0604,
+          --disable=R0801,
+          --disable=R0902,
+          --disable=R0903,
+          --disable=C0123,
+          --disable=W0231,
+          --disable=W1113,
+          --disable=W0221,
+          --disable=R0401,
+          --disable=W0632,
+          --disable=W0123,
+          --disable=C3001,
+          --max-branches=30,
+          --max-nested-blocks=7,
+          --max-statements=100,
+          --max-returns=10,
+          --max-module-lines=3000,
+        ]
+  - repo: https://github.com/regebro/pyroma
+    rev: "5.0"
+    hooks:
+      - id: pyroma
+        args: [--min=10, .]

CONTRIBUTING.md

@@ -0,0 +1,420 @@
+# Contributing to AgentScope
+
+
+Thank you for your interest in contributing to AgentScope!
+
+As an open-source project, we warmly welcome and encourage
+contributions from the community. Whether you're fixing bugs, adding new features, improving documentation, or sharing
+ideas, your contributions help make AgentScope better for everyone.
+
+## 1. Development Roadmap and How to Get Involved
+
+To support the long-term, healthy growth of AgentScope and its open-source
+community, we keep our development plan transparent and openly tracked.
+
+**Our roadmap is public.** The AgentScope development plan is published and
+continuously updated on our [GitHub Projects page](https://github.com/orgs/agentscope-ai/projects/2).
+The roadmap reflects the technical direction set by the core team, who are
+responsible for AgentScope's overall design and quality.
+
+**Tasks open to the community.** Items labeled `help wanted` on the Projects
+page/issues are contribution opportunities open to everyone. If one of these
+interests you:
+
+- Comment on the related issue to let us know you'd like to take it on
+- This helps us avoid duplicate efforts and coordinate with you early
+
+**If you'd like to join the core development.** We warmly welcome contributors
+who want to go deeper and help shape AgentScope itself. Over time, we plan to
+gradually invite committed contributors into the core development circle.
+Before reaching out, we'd like to share a few honest expectations so you can
+decide whether it's a good fit right now:
+
+- Core development involves frequent design discussions, code reviews, and
+  iterative revisions — it asks for a sustained investment of time and energy
+- To keep AgentScope cohesive and reliable, the core team retains
+  responsibility for the project's technical direction and quality bar; core
+  contributors work within this collaborative process
+
+If this fits your situation, please reach out to the core developers — we'd
+love to talk.
+
+**Proposing something new.** If you have an idea that isn't on the roadmap
+yet, please open a new issue describing your proposal. The core team will
+respond and discuss it with you so we can find the best path forward together.
+
+## 2. Responsible Use of AI in Contributions
+
+AgentScope welcomes contributors who use AI coding assistants — Claude Code,
+Cursor, Codex, Copilot, and others. We just ask that they be used
+**responsibly**. AgentScope is sustained by reviewer time and community
+trust, and AI-assisted contributions need to honor both.
+
+A few expectations when AI is involved in your work:
+
+- **You — not the AI — are the author.** Read the diff line by line, run it,
+  and make sure you understand *what* changed and *why* before you push.
+  "Claude Code / Cursor / Codex told me to do it" is not an acceptable
+  answer in code review, and is not the kind of behavior that builds a
+  healthy open-source community. PRs whose authors cannot explain their own
+  changes will be closed.
+
+- **Review your AI-generated code before opening a PR.** Reviewer time is
+  the most precious resource in this project. Don't outsource your own
+  review to the maintainers by dumping unreviewed AI output into a PR.
+
+- **Keep PRs atomic.** Do not submit a 10K+-line PR produced by an AI in a
+  single shot. Such PRs are unreviewable and will be rejected. Break the
+  work into focused, single-purpose PRs the same way a human contributor
+  would.
+
+- **AI-assisted code follows the same rules.** All of AgentScope's
+  development principles — modularity, lazy imports, conventional commits,
+  test coverage, no surprise API breaks — apply identically to code written
+  with AI assistance. AI is not an excuse for skipping conventions.
+
+The goal is simple: AI helps you move faster, but the responsibility for
+what lands in AgentScope still rests with you as a human contributor.
+
+## 3. Contribution Workflow
+
+End-to-end, contributing a change to AgentScope looks like this.
+
+### Step 1. Claim or create an issue
+
+Before writing code, find or open the issue that frames your work.
+
+- **Working on an existing item?** Browse [Projects](https://github.com/orgs/agentscope-ai/projects/2)
+  and [Issues](https://github.com/agentscope-ai/agentscope/issues) for items
+  labeled `help wanted` (see [§1](#1-development-roadmap-and-how-to-get-involved)).
+  Comment on the issue to claim it before starting.
+- **Proposing something new?** Open a new issue describing the problem,
+  your proposed solution, and any design alternatives. Wait for feedback
+  from the core team before starting a non-trivial implementation — this
+  avoids wasted rewrites.
+
+### Step 2. Fork the repo and create a development branch
+
+1. Fork [agentscope-ai/agentscope](https://github.com/agentscope-ai/agentscope) on GitHub.
+2. Clone your fork and add the upstream remote:
+   ```bash
+   git clone https://github.com/<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.
+
+```
+<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:**
+```bash
+feat(models): add support for Claude-3 model
+fix(agent): resolve memory leak in ReActAgent
+docs(readme): update installation instructions
+refactor(formatter): simplify message formatting logic
+ci(models): add unit tests for OpenAI integration
+```
+
+**Pull request title format.** PR titles follow the same Conventional
+Commits format and are validated automatically by GitHub Actions on PRs
+against `main`. PRs with invalid titles will be blocked until corrected.
+
+```
+<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](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}
+   ```
+
+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](#examples) rather than as new classes in `agentscope.agent`.
+
+If you believe a use case genuinely requires a new top-level agent class:
+
+1. **Open an issue first** describing the use case and explaining why
+   composing existing `Agent` capabilities is insufficient.
+2. **Wait for design discussion** with the core team before starting any
+   implementation.
+3. PRs that introduce a new agent class without prior discussion will be
+   rejected.
+
+### Workspace
+
+A Workspace provides the runtime context an agent operates in (skills,
+scheduled tasks, etc.). Adding a new workspace backend requires two
+classes plus documentation:
+
+1. **Workspace class** — under `agentscope.workspace`, subclassing
+   `WorkspaceBase`. Implements the storage and lifecycle semantics of
+   your backend.
+   _Reference: `agentscope/workspace/_local_workspace.py` (`LocalWorkspace`)_
+
+2. **Workspace manager class** — alongside
+   `agentscope/app/_manager/_workspace_manager.py`, subclassing
+   `WorkspaceManagerBase`. Wires your workspace into the application
+   lifecycle.
+   _Reference: `LocalWorkspaceManager` in the same file._
+
+3. **Documentation** — open a companion PR in
+   [agentscope-ai/docs](https://github.com/agentscope-ai/docs) describing
+   how to configure and use your workspace.
+
+### Examples
+
+We highly encourage contributions of new examples that showcase
+AgentScope's capabilities.
+
+The `examples/` directory in the main repository focuses on
+**demonstrating specific features and capabilities** — concise,
+educational reference implementations. For more complete, production-style
+applications, please contribute them to
+**[agentscope-samples](https://github.com/agentscope-ai/agentscope-samples)**
+instead.
+
+A new example should live in its own subdirectory:
+
+```
+examples/
+└── <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](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.

CONTRIBUTING_zh.md

@@ -0,0 +1,298 @@
+# 为 AgentScope 做贡献
+
+感谢大家对 AgentScope 的关注！
+
+作为一个开源项目，我们欢迎并鼓励来自社区的贡献。无论是修复 bug、新增功能、完善文档，还是分享想法，每一份贡献都让 AgentScope 变得更好。
+
+## 1. 开发路线图与参与方式
+
+为了支持 AgentScope 开源社区的长期健康发展，我们将公开、透明地维护 AgentScope 的开发计划。
+
+**路线图公开**。AgentScope 的开发计划会发布在 [GitHub Projects 页面](https：//github.com/orgs/agentscope-ai/projects/2)，并持续更新。路线图会反映 AgentScope 的技术发展方向，由核心开发团队对 AgentScope 的整体设计与质量负责。
+
+**社区可认领的任务**。Projects 页面 / Issues 中标有 `help wanted` 的条目对所有人开放。如果你有兴趣参与某一项：
+
+- 请在对应 issue 下评论，告知准备认领
+- 这样可以避免重复劳动，也方便我们尽早协作
+
+**成为核心开发者**。我们欢迎想要更深入参与、共同塑造 AgentScope 的开发者。我们会在合适的时机邀请投入度高的贡献者成为核心开发者。
+成为核心开发者也意味着更频繁的参与到 AgentScope 的开发工作中，包括：
+
+- 更加频繁的设计讨论、代码评审与多轮迭代，需要持续的时间和精力投入
+- 为保证 AgentScope 的整体一致性与可靠性，核心团队保留对项目技术方向与质量标准的把控
+
+**提出新想法**。针对有路线图上还没有的想法，请新建 issue 描述提议。核心开发团队会尽可能地及时回复并一起讨论可行的推进路径。
+
+## 2. 在贡献中负责任地使用 AI
+
+AgentScope 欢迎使用 AI 编码助手的贡献者——Claude Code、Cursor、Codex、Copilot 等等。我们只要求**负责任地使用**。AgentScope 依靠评审者的时间和社区信任运转，AI 辅助的贡献需要兼顾两者。
+
+涉及 AI 时的几条要求：
+
+- **作者是人，不是 AI**。在 push 之前，请逐行阅读 diff，运行代码，确认理解了**改了什么**和**为什么改**。“Claude Code / Cursor / Codex 就是这么写的”并不是一个合适的理由，也不利于开源社区的健康发展。
+
+- **创建 PR 前先自行评审 AI 生成的代码**。所有人的事件都是宝贵的资源，请不要将没有审阅过的 AI 代码/改动直接丢给维护者评审。
+
+- **保持 PR 原子化**。不要提交 AI 一次性生成的 10K+ 行 PR，这种 PR 无法评审，会被拒绝。请把改动拆成若干个聚焦原子化功能的、具有单一目标的 PR。
+
+- **AI 生成代码遵守同样的原则**。AgentScope 的所有开发原则——模块化、惰性导入、约定式提交、测试覆盖、不破坏 API——对 AI 辅助代码同等适用。
+
+简而言之：AI 让我们的开发更快，但确保合入 AgentScope 的代码质量责任仍在贡献者本人。
+
+## 3. 贡献流程
+
+端到端的贡献流程如下。
+
+### 第 1 步：认领或创建 issue
+
+在写代码之前，先找到或创建对应的 issue。
+
+- **基于已有任务**：浏览 [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 仓库并创建开发分支
+
+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`)。
+
+```bash
+# 创建隔离环境(这里用 uv，也可用 virtualenv / conda)
+uv venv
+source .venv/bin/activate
+
+# 以可编辑模式安装 AgentScope，并带上 dev extras
+pip install -e ".[dev]"
+# 等价的 uv 写法：
+uv pip install -e ".[dev]"
+
+# 启用 git pre-commit hooks
+pre-commit install
+```
+
+`dev` extra 会拉入 `pre-commit`、`pytest`、文档工具链以及 `full` extra(包含 `models`、`service`、`storage`)。一次安装即可获得开发与运行完整测试套件所需的一切。
+
+### 第 4 步：开发
+
+写代码时遵守的几条约定：
+
+- **可选依赖必须惰性导入**。任何**未列在 `pyproject.toml` 的 `[project.dependencies]` 中**的依赖——也就是来自可选 extra(`gemini`、`ollama`、`xai`、`service`、`storage` 等)的——**必须在使用点惰性导入**，而不是放在模块顶部：
+  ```python
+  def some_function():
+      import google.genai  # 来自 `gemini` extra，惰性导入
+      # ... 在这里使用 google.genai
+  ```
+  这样保持 `import agentscope` 轻量，`ImportError` 只在实际用到该 extra 的功能时才抛出。如果改动需要引入全新的依赖，先决定它属于基础 `[project.dependencies]`(始终需要、保持精简)还是某个可选 extra，并在 issue 中讨论后再合入。
+
+- **遵守项目代码风格**。pre-commit 会自动处理格式与大部分 lint 规则，请在提交前运行 pre-commit 来修复问题。
+
+- **功能要配套写单元测试**。测试位于 `tests/` 下，沿用现有结构。依赖可选 extra 的测试(如 Redis、Ollama)在该 extra 未安装时应能干净 skip。
+
+### 第 5 步：跑 pre-commit、测试，并更新文档
+
+创建 PR 之前，请在本地运行如下的命令检查代码格式与功能：
+
+```bash
+# 自动格式化与 lint
+pre-commit run --all-files
+
+# 单元测试
+pytest tests
+```
+
+如果 pre-commit hook 失败，请修复格式问题（多数会自动修复），然后重新 commit。
+
+**改代码的同时请更新文档**。
+
+- AgentScope 文档放在独立仓库：**[agentscope-ai/docs](https：//github.com/agentscope-ai/docs)**。如果改动影响用户可见行为——新模块、新公开 API、行为变化、教程——请在该仓库同步开一个配套 PR。
+- 为新公开 API 更新 docstring 与示例片段。
+- 如果改动影响新手上手或 AgentScope 的对外宣传内容，更新 `README.md`。
+
+### 第 6 步：提交与发起 PR
+
+**Commit 信息格式**。我们遵循 [Conventional Commits](https：//www.conventionalcommits.org/) 规范，便于阅读历史与自动生成 changelog。
+
+```
+<type>(<scope>)： <subject>
+```
+
+**Type 列表：**
+- `feat：` 新功能
+- `fix：` bug 修复
+- `docs：` 仅文档变更
+- `style：` 不影响代码语义的改动(空白、格式等)
+- `refactor：` 既不是修 bug 也不是加功能的代码改动
+- `perf：` 性能优化
+- `ci：` 增补或修正测试
+- `chore：` 构建流程或辅助工具/库的变更
+
+**示例：**
+```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
+```
+
+**PR 标题格式**。PR 标题同样遵循 Conventional Commits 格式，并由 GitHub Actions 在针对 `main` 的 PR 上自动校验。标题不合规的 PR 会被阻止合入，直到修正为止。
+
+```
+<type>(<scope>)： <description>
+```
+
+**要求：**
+- 标题须以下列 type 之一开头：`feat`、`fix`、`docs`、`ci`、`refactor`、`test`、`chore`、`perf`、`style`、`build`、`revert`
+- scope 可选，建议带上
+- **scope 必须小写**——只允许小写字母、数字、连字符(`-`)和下划线(`_`)
+- description 以小写字母开头
+- 标题保持简洁、有信息量
+
+**示例：**
+```
+✅ 合规：
+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 描述里：
+
+- 关联认领的 issue(`Fixes #123` 或 `Refs #123`)
+- 概述改了什么、为什么改
+- 标注任何破坏性改动、废弃项或迁移步骤
+- 如果同时开了文档 PR，链接到 [agentscope-ai/docs](https：//github.com/agentscope-ai/docs) 的对应 PR
+
+## 4. 重要事项
+
+开始贡献前需要了解的几条横向约束。模块特定的事项见下文对应模块指南。
+
+- **非平凡改动先开 issue**。突然提交涉及大量文件、改动公开 API 或引入新模块的 PR 难以评审，多半会被拒。先在 issue 中讨论设计。
+- **PR 保持聚焦、原子**。一个 PR 一个目的。不要把重构和功能、或功能和不相干的 bug 修复混在一起。
+- **不擅自破坏公开 API**。能保持向后兼容就保持。无法避免的破坏性改动，在 PR 描述中清楚说明，并在同一个 PR 里更新受影响的示例和文档。
+- **不绕过惰性导入原则**。可选依赖必须在使用点导入，不能放在模块顶部。
+- **不随意引入依赖**。每个新依赖都是长期维护负担。如果只有一个模块用到，优先在该模块内部惰性导入。
+- **不忽视 CI 失败**。pre-commit、类型检查、测试必须通过后再��起 review，不要把修复负担推给评审者。
+- **保持尊重**。遵守行为准则。AgentScope 的评审风格直接但友善，对贡献者也是同样期待。
+
+## 5. 模块特定贡献指南
+
+下文覆盖社区贡献者最常扩展的模块。其他模块请先开 issue 协调。
+
+### Chat Model
+
+AgentScope 中的一个 chat model 不只是一个类——要在 `Agent` 中可用，需要一组上下游配套实现。一个完整的 chat model 贡献需包含**以下全部**：
+
+1. **Credential 类**——位于 `agentscope.credential`，继承 `CredentialBase`。承载 API key、endpoint 及 SDK 所需的其他鉴权字段。
+   _参考：`agentscope/credential/_anthropic.py`_
+
+2. **Chat model 类**——位于 `agentscope.model.<provider>/`，继承 `ChatModelBase`。实现需覆盖：
+   - 流式与非流式两种模式
+   - Tools API 集成(function/tool calling)
+   - `tool_choice` 参数
+   - 适用时的 reasoning 模型支持
+
+   _参考：`agentscope/model/_anthropic/`_
+
+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 场景
+
+   每个 formatter 把 `Msg` 对象转换成对应 provider API 期望的请求格式。
+   _参考：`agentscope/formatter/_anthropic_formatter.py`_
+
+> ⚠️ 只加 model 类、缺少配套 credential、model card YAML 与两种 formatter 变体的 PR 不会被合入。
+
+### Agent
+
+AgentScope 目前只维护**一个核心 agent 类**——`agentscope.agent.Agent`——它整合了 AgentScope 库的全部功能（memory、tools、MCP、formatter、model 等）。
+
+特定领域或专用 agent 请作为 [example](#examples) 贡献，而不是在 `agentscope.agent` 中新增类。
+
+如果确信某个用例需要新的顶层 agent 类：
+
+1. **先开 issue**，描述用例并说明为什么组合现有 `Agent` 能力不够。
+2. **等核心团队的设计讨论**，再开始具体的代码实现。
+3. 未经事先讨论就引入新 agent 类的 PR 会被拒绝。
+
+### Workspace
+
+Workspace 提供 agent 运行所需的运行时上下文（skills、scheduled tasks 等）。新增 workspace 后端需要两个类加配套文档：
+
+1. **Workspace 类**——位于 `agentscope.workspace`，继承 `WorkspaceBase`。实现该后端的存储与生命周期语义。
+   _参考：`agentscope/workspace/_local_workspace.py`(`LocalWorkspace`)_
+
+2. **Workspace manager 类**——位于 `agentscope/app/_manager/_workspace_manager.py`，继承 `WorkspaceManagerBase`。把 workspace 接入应用生命周期。
+   _参考：同文件中的 `LocalWorkspaceManager`_
+
+3. **文档**——在 [agentscope-ai/docs](https：//github.com/agentscope-ai/docs) 配套发起 PR，说明该 workspace 的配置与使用方式。
+
+### Examples
+
+我们非常欢迎新增展示 AgentScope 能力的 example。
+
+主仓库 `examples/` 目录聚焦于**演示具体特性与能力**——简洁、教学性的参考实现。更完整、贴近生产形态的应用，请贡献到 **[agentscope-samples](https：//github.com/agentscope-ai/agentscope-samples)**。
+
+新 example 放在自己的子目录下：
+
+```
+examples/
+└── <example-name>/
+    ├── main.py
+    ├── README.md   # 说明 example 的目的、运行方式与预期输出
+    └── ...
+```
+
+`examples/agent_service/` 是不错的参考起点。
+
+## 获取帮助
+
+需要协助或有问题，可以：
+
+- 发起 [Discussion](https：//github.com/agentscope-ai/agentscope/discussions)
+- 在 [Issues](https：//github.com/agentscope-ai/agentscope/issues) 中报告 bug
+- 通过钉钉或 Discord 联系维护者(链接见 README.md)
+
+
+---
+
+感谢您为 AgentScope 所做的贡献！每一份努力都在为社区构建更好的开源工具。

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y \
+    curl git redis-server \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && npm install -g pnpm
+
+WORKDIR /app
+COPY . .
+
+RUN pip install --no-cache-dir -e .
+RUN pip install redis uvicorn fastapi
+
+WORKDIR /app/examples/web_ui
+RUN pnpm install
+RUN pnpm build
+
+WORKDIR /app
+RUN chmod +x /app/start.sh
+
+EXPOSE 7860
+CMD ["/app/start.sh"]

LICENSE

@@ -0,0 +1,391 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Alibaba
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+
+--------------------------------------------------------------------------------
+
+
+Some codes of tests/run.py is modified from
+https://github.com/alibaba/FederatedScope/blob/master/tests/run.py, which is
+also licensed under the terms of the Apache 2.0.
+
+
+--------------------------------------------------------------------------------
+
+Code in src/agentscope/web/static/js/socket.io.js is adapted from
+https://cdnjs.cloudflare.com/ajax/libs/socket.io/3.1.3/socket.io.js (MIT License)
+
+Copyright (c) 2014-2021 Guillermo Rauch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Code in src/agentscope/web/static/js/jquery-3.3.1.min.js is adapted from
+https://code.jquery.com/jquery-3.3.1.min.js (MIT License)
+
+Copyright (c) JS Foundation and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Code in src/agentscope/web/static/js/bootstrap.bundle.min.js is adapted from
+https://cdn.jsdelivr.net/npm/bootstrap@4.3.1/dist/js/bootstrap.bundle.min.js
+ (MIT License)
+
+Copyright (c) 2011-2019 The Bootstrap Authors (https://github
+.com/twbs/bootstrap/graphs/contributors)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Code in src/agentscope/web/static/js/bootstrap-table.min.js is adapted from
+https://unpkg.com/bootstrap-table@1.18.0/dist/bootstrap-table.min.js (MIT
+License)
+
+Copyright (c) wenzhixin <wenzhixin2010@gmail.com> (http://wenzhixin.net.cn/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Code in src/agentscope/web/static/css/bootstrap.min.css is adapted from
+https://cdn.jsdelivr.net/npm/bootstrap@4.3.1/dist/css/bootstrap.min.css (MIT
+License)
+
+Copyright 2011-2019 The Bootstrap Authors
+Copyright 2011-2019 Twitter, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+--------------------------------------------------------------------------------
+
+Fonts in src/agentscope/web/static/fonts/KRYPTON.ttf is adapted from
+https://github.com/githubnext/monaspace (SIL Open Font License 1.1). These
+fonts are distributed with their original license. See https://github
+.com/githubnext/monaspace/blob/main/LICENSE for the full text of the license.
+The following font families are included:
+
+- Monaspace (with subfamilies: Krypton)
+
+Copyright (c) 2023, GitHub https://github.com/githubnext/monaspace
+with Reserved Font Name "Monaspace", including subfamilies: "Argon", "Neon",
+"Xenon", "Radon", and "Krypton"
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Fonts in src/agentscope/web/static/fonts/OSWALD.ttf is adapted from
+https://fonts.google.com/specimen/Oswald (SIL Open Font License 1.1). These
+fonts are distributed with their original license. See https://github
+.com/googlefonts/OswaldFont/blob/main/OFL.txt for the full text of the license.
+
+Copyright 2016 The Oswald Project Authors (https://github
+.com/googlefonts/OswaldFont)
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+--------------------------------------------------------------------------------

README.md

@@ -1,10 +1,274 @@
----
-title: Agentscope
-emoji: 🏆
-colorFrom: yellow
-colorTo: purple
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+  <img
+    src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg"
+    alt="AgentScope Logo"
+    width="200"
+  />
+</p>
+
+<span align="center">
+
+[**中文主页**](https://github.com/agentscope-ai/agentscope/blob/main/README_zh.md) | [**Documentation**](https://docs.agentscope.io/) | [**Roadmap**](https://github.com/orgs/agentscope-ai/projects/2/views/1)
+
+</span>
+
+<p align="center">
+    <a href="https://arxiv.org/abs/2402.14034">
+        <img
+            src="https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C"
+            alt="arxiv"
+        />
+    </a>
+    <a href="https://pypi.org/project/agentscope/">
+        <img
+            src="https://img.shields.io/badge/python-3.11+-blue?logo=python"
+            alt="pypi"
+        />
+    </a>
+    <a href="https://pypi.org/project/agentscope/">
+        <img
+            src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fagentscope%2Fjson&query=%24.info.version&prefix=v&logo=pypi&label=version"
+            alt="pypi"
+        />
+    </a>
+    <a href="https://discord.gg/eYMpfnkG8h">
+        <img
+            src="https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord&logoColor=white"
+            alt="discord"
+        />
+    </a>
+    <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"
+        />
+    </a>
+    <a href="./LICENSE">
+        <img
+            src="https://img.shields.io/badge/license-Apache--2.0-black"
+            alt="license"
+        />
+    </a>
+</p>
+
+<p align="center">
+<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 2.0?
+
+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 .
+
+- [**Event System** →](https://docs.agentscope.io/latest/en/building-blocks/message-and-event) A unified event bus to the frontend and human-in-the-loop support.
+- [**Permission System** →](https://docs.agentscope.io/latest/en/building-blocks/permission-system) Fine-grained, configurable control over tools and resources.
+- [**Multi-tenancy & Multi-session Service** →](https://docs.agentscope.io/latest/en/deploy/agent-service) Production-grade serving with isolation across tenants and sessions.
+- [**Workspace / Sandbox Support** →](https://docs.agentscope.io/latest/en/building-blocks/workspace) Run tools and code in isolated environments, with built-in backends for local, Docker, and E2B.
+- [**Extensible Middleware System** →](https://docs.agentscope.io/latest/en/building-blocks/middleware) Composable hooks to customize and extend the agent's reasoning-acting loop.
+
+We design for increasingly agentic LLMs.
+Our approach leverages the models' reasoning and tool use abilities
+rather than constraining them with strict prompts and opinionated orchestrations.
+
+<img src="assets/images/agentscope.png" alt="agentscope" width="100%"/>
+
+## News
+<!-- BEGIN NEWS -->
+- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)
+- **[2026-06] `FEAT`:** RAG supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/rag)
+- **[2026-06] `INTE`:** Mem0 supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory) | [Docs](https://docs.agentscope.io/latest/en)
+- **[2026-06] `FEAT`:** Agent Team supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)
+- **[2026-05] `RELS`:** AgentScope 2.0 released! [Docs](https://docs.agentscope.io/)
+<!-- END NEWS -->
+
+[More news →](./docs/NEWS.md)
+
+## Community
+
+Welcome to join our community on
+
+| [Discord](https://discord.gg/eYMpfnkG8h)                                                                                         | DingTalk                                                                  |
+|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="./assets/images/dingtalk_qr_code.png" width="100" height="100"> |
+
+## Quickstart
+
+### Installation
+
+> AgentScope requires **Python 3.11** or higher.
+
+#### From PyPI
+
+```bash
+uv pip install agentscope
+# or
+# pip install agentscope
+```
+
+#### From source
+
+```bash
+# Pull the source code from GitHub
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+
+# Install the package in editable mode
+cd agentscope
+
+uv pip install -e .
+# or
+# pip install -e .
+```
+
+## Hello AgentScope!
+
+Start your first agent with AgentScope 2.0:
+
+```python
+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.message import UserMsg
+from agentscope.event import EventType
+
+import os, asyncio
+
+
+async def main() -> None:
+    agent = Agent(
+        name="Friday",
+        system_prompt="You're a helpful assistant named Friday.",
+        model=DashScopeChatModel(
+            credential=DashScopeCredential(
+              api_key=os.environ["DASHSCOPE_API_KEY"]
+            ),
+            model="qwen3.6-plus",
+        ),
+        toolkit=Toolkit(
+            tools=[
+                Bash(),
+                Grep(),
+                Glob(),
+                Read(),
+                Write(),
+                Edit(),
+            ]
+        ),
+    )
+
+    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())
+```
+
+## Hello Agent Service!
+
+An extensible FastAPI based **multi-tenancy**, **multi-session** agent service with pre-built Web UI in `examples/web_ui`
+
+<table>
+  <tr>
+    <td align="center">
+      <img src="assets/images/team.gif" alt="Agent team" width="100%"/>
+      <br/>
+      <sub><b>Agent team</b> — a leader agent spawns workers and coordinates them through the built-in team tools.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="assets/images/task.gif" alt="Task planning" width="100%"/>
+      <br/>
+      <sub><b>Task planning</b> — the agent breaks complex work into a tracked plan and updates it as it goes.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="assets/images/permission_bypass.gif" alt="Permission control in bypass mode" width="100%"/>
+      <br/>
+      <sub><b>Permission control in bypass mode</b> — the agent runs end-to-end without pausing for tool-call confirmations.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="assets/images/bg_tool.gif" alt="Background task offloading" width="100%"/>
+      <br/>
+      <sub><b>Background task offloading</b> — a long-running tool moves to the background; its result later wakes the agent up and the conversation resumes.</sub>
+    </td>
+  </tr>
+</table>
+
+Run the following commands to start the agent service backend and the web UI:
+
+```bash
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+cd agentscope/examples/agent_service
+
+# start the agent service backend
+python main.py
+```
+
+Then open another terminal to start the web UI:
+
+```bash
+cd agentscope/examples/web_ui
+
+# start the webui
+pnpm install
+pnpm dev
+```
+
+
+## Contributing
+
+We welcome contributions from the community! Please refer to our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines
+on how to contribute.
+
+## License
+
+AgentScope is released under Apache License 2.0.
+
+## Publications
+
+If you find our work helpful for your research or application, please cite our papers.
+
+- [AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications](https://arxiv.org/abs/2508.16279)
+
+- [AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
+
+```
+@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}
+    title   = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications},
+    journal = {CoRR},
+    volume  = {abs/2508.16279},
+    year    = {2025},
+}
+
+@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}
+    title   = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
+    journal = {CoRR},
+    volume  = {abs/2402.14034},
+    year    = {2024},
+}
+```
+
+## Contributors
+
+All thanks to our contributors:
+
+<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" />
+</a>

README_zh.md

@@ -0,0 +1,297 @@
+<p align="center">
+  <img
+    src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg"
+    alt="AgentScope Logo"
+    width="200"
+  />
+</p>
+
+<span align="center">
+
+[**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>
+
+<p align="center">
+    <a href="https://arxiv.org/abs/2402.14034">
+        <img
+            src="https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C"
+            alt="arxiv"
+        />
+    </a>
+    <a href="https://pypi.org/project/agentscope/">
+        <img
+            src="https://img.shields.io/badge/python-3.11+-blue?logo=python"
+            alt="pypi"
+        />
+    </a>
+    <a href="https://pypi.org/project/agentscope/">
+        <img
+            src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fagentscope%2Fjson&query=%24.info.version&prefix=v&logo=pypi&label=version"
+            alt="pypi"
+        />
+    </a>
+    <a href="https://discord.gg/eYMpfnkG8h">
+      <img
+          src="https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord&logoColor=white"
+          alt="discord"
+      />
+  </a>
+    <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"
+        />
+    </a>
+    <a href="./LICENSE">
+        <img
+            src="https://img.shields.io/badge/license-Apache--2.0-black"
+            alt="license"
+        />
+    </a>
+</p>
+
+<p align="center">
+<img src="https://trendshift.io/api/badge/repositories/20310" alt="agentscope-ai%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
+</p>
+
+## 什么是 AgentScope 2.0？
+
+AgentScope 2.0 是一款面向生产、易于使用的智能体框架，提供与不断进化的模型能力相匹配的核心抽象。
+
+- [**事件系统** →](https://docs.agentscope.io/latest/zh/building-blocks/message-and-event) 统一的事件总线，服务于前端智能体应用与 human-in-the-loop 协作。
+- [**权限系统** →](https://docs.agentscope.io/latest/zh/building-blocks/permission-system) 对工具和资源进行细粒度、可配置的控制。
+- [**多租户与多会话服务** →](https://docs.agentscope.io/latest/zh/deploy/agent-service) 提供生产级服务，在租户与会话之间实现隔离。
+- [**工作区 / 沙箱支持** →](https://docs.agentscope.io/latest/zh/building-blocks/workspace) 在隔离环境中运行工具和代码，内置支持本地文件系统、Docker 和 E2B 后端。
+- [**可扩展中间件系统** →](https://docs.agentscope.io/latest/zh/building-blocks/middleware) 可组合的钩子系统，用于自定义和扩展智能体的推理-行动循环。
+
+我们为日益自主的大语言模型而设计。
+我们的方法是充分发挥模型的推理与工具调用能力，
+而不是用严格的提示词和固化的编排方式来束缚它们。
+
+## 为什么选择 AgentScope？
+
+- **简单**：通过内置的 ReAct 智能体、工具、技能、人机协作干预、记忆、计划、实时语音、评估和模型微调，5 分钟即可开始构建你的智能体
+- **可扩展**：丰富的生态系统集成，覆盖工具、记忆和可观测性；内置 MCP 和 A2A 支持；通过消息中心（MsgHub）实现灵活的多智能体编排和工作流
+- **生产就绪**：支持本地部署、云端 Serverless 部署或 K8s 集群部署，并内置 OTel 支持
+
+<img src="assets/images/agentscope.png" alt="agentscope" width="100%"/>
+
+## 新闻
+<!-- BEGIN NEWS -->
+- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)
+- **[2026-06] `功能`:** 支持多模态 RAG。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [文档](https://docs.agentscope.io/latest/en/building-blocks/rag)
+- **[2026-06] `集成`:** 集成 Mem0 长期记忆。 [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory) | [Docs](https://docs.agentscope.io/latest/zh)
+- **[2026-06] `功能`:** 支持 Agent Team。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [文档](https://docs.agentscope.io/latest/zh/deploy/agent-team)
+- **[2026-05] `发布`:** AgentScope 2.0 已发布！[文档](https://docs.agentscope.io/)
+<!-- END NEWS -->
+
+[更多新闻 →](./docs/NEWS_zh.md)
+
+## 社区
+
+欢迎加入我们的社区
+
+| [Discord](https://discord.gg/eYMpfnkG8h)                                                                                         | 钉钉                                                                        |
+|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="./assets/images/dingtalk_qr_code.png" width="100" height="100"> |
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## 📑 Table of Contents
+
+- [快速开始](#%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
+  - [安装](#%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)
+- [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)
+- [贡献者](#%E8%B4%A1%E7%8C%AE%E8%80%85)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 快速开始
+
+### 安装
+
+> AgentScope 需要 **Python 3.11** 或更高版本。
+
+#### 从 PyPI 安装
+
+```bash
+uv pip install agentscope
+# 或者
+# pip install agentscope
+```
+
+#### 从源码安装
+
+```bash
+# 从 GitHub 拉取源码
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+
+# 以可编辑模式安装
+cd agentscope
+
+uv pip install -e .
+# 或者
+# pip install -e .
+```
+
+## Hello AgentScope！
+
+使用 AgentScope 2.0，启动你的第一个智能体：
+
+```python
+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.message import UserMsg
+from agentscope.event import EventType
+
+import os, asyncio
+
+
+async def main() -> None:
+    agent = Agent(
+        name="Friday",
+        system_prompt="You're a helpful assistant named Friday.",
+        model=DashScopeChatModel(
+            credential=DashScopeCredential(
+              api_key=os.environ["DASHSCOPE_API_KEY"]
+            ),
+            model="qwen3.6-plus",
+        ),
+        toolkit=Toolkit(
+            tools=[
+                Bash(),
+                Grep(),
+                Glob(),
+                Read(),
+                Write(),
+                Edit(),
+            ]
+        ),
+    )
+
+    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())
+```
+
+## 智能体服务
+
+一个基于 FastAPI 的可扩展**多租户**、**多会话**智能体服务，并在 `examples/web_ui` 中提供预构建的 Web UI
+
+<table>
+  <tr>
+    <td align="center">
+      <img src="assets/images/team.gif" alt="智能体团队" width="100%"/>
+      <br/>
+      <sub><b>智能体团队</b> —— leader 智能体派生 worker，并通过内置的团队工具进行协调。</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="assets/images/task.gif" alt="任务规划" width="100%"/>
+      <br/>
+      <sub><b>任务规划</b> —— 智能体将复杂工作拆解为可追踪的计划，并在执行过程中持续更新。</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="assets/images/permission_bypass.gif" alt="bypass 模式下的权限控制" width="100%"/>
+      <br/>
+      <sub><b>bypass 模式下的权限控制</b> —— 智能体端到端运行，无需为工具调用确认而暂停。</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="assets/images/bg_tool.gif" alt="后台任务卸载" width="100%"/>
+      <br/>
+      <sub><b>工具后台执行</b> —— 长时间运行的工具被转入后台；其结果稍后唤醒智能体并恢复对话。</sub>
+    </td>
+  </tr>
+</table>
+
+运行以下命令启动智能体服务后端和 Web UI：
+
+```bash
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+cd agentscope/examples/agent_service
+
+# 启动智能体服务后端
+python main.py
+```
+
+然后打开另一个终端启动 Web UI：
+
+```bash
+cd agentscope/examples/web_ui
+
+# 启动 webui
+pnpm install
+pnpm dev
+```
+
+
+
+## 贡献
+
+我们欢迎社区的贡献！请参阅我们的 [贡献指南](./CONTRIBUTING_zh.md) 了解如何贡献。
+
+## 许可
+
+AgentScope 基于 Apache License 2.0 发布。
+
+## 论文
+
+如果我们的工作对您的研究或应用有帮助，请引用我们的论文。
+
+- [AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications](https://arxiv.org/abs/2508.16279)
+
+- [AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
+
+```
+@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}
+    title   = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications},
+    journal = {CoRR},
+    volume  = {abs/2508.16279},
+    year    = {2025},
+}
+
+@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}
+    title   = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
+    journal = {CoRR},
+    volume  = {abs/2402.14034},
+    year    = {2024},
+}
+```
+
+## 贡献者
+
+感谢所有贡献者：
+
+<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" />
+</a>

docs/NEWS.md

@@ -0,0 +1,10 @@
+<!-- This is the source of truth for all NEWS items. -->
+<!-- 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-06] `FEAT`:** Agentic Memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)
+- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)
+- **[2026-06] `FEAT`:** RAG supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/rag)
+- **[2026-06] `INTE`:** Mem0 supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory) | [Docs](https://docs.agentscope.io/latest/en)
+- **[2026-06] `FEAT`:** Agent Team supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)
+- **[2026-05] `RELS`:** AgentScope 2.0 released! [Docs](https://docs.agentscope.io/)

docs/NEWS_zh.md

@@ -0,0 +1,10 @@
+<!-- This is the source of truth for all NEWS items. -->
+<!-- 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-06] `功能`:** 支持 Agentic Memory。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)
+- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)
+- **[2026-06] `功能`:** 支持多模态 RAG。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [文档](https://docs.agentscope.io/latest/en/building-blocks/rag)
+- **[2026-06] `集成`:** 集成 Mem0 长期记忆。 [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory) | [Docs](https://docs.agentscope.io/latest/zh)
+- **[2026-06] `功能`:** 支持 Agent Team。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [文档](https://docs.agentscope.io/latest/zh/deploy/agent-team)
+- **[2026-05] `发布`:** AgentScope 2.0 已发布！[文档](https://docs.agentscope.io/)

docs/changelog.md

@@ -0,0 +1,98 @@
+# CHANGELOG of v1.0.0
+
+> ➡️ change; ✅ new feature; ❌ deprecate
+
+The overall changes from v0.x.x to v1.0.0 are summarized below.
+
+## Overview
+- ✅ Support asynchronous execution throughout the library
+- ✅ Support tools API thoroughly
+
+
+## ✨Session
+- ✅ Support automatic state management
+- ✅ Support session/application-level state management
+
+
+## ✨Tracing
+- ✅ Support OpenTelemetry-based tracing
+- ✅ Support third-party tracing platforms, e.g. Arize-Phoenix, Langfuse, etc.
+
+
+## ✨MCP
+- ✅ Support both client- and function-level control over MCP by a new MCP module
+- ✅ Support both "pay-as-you-go" and persistent session management
+- ✅ Support streamable HTTP, SSE and StdIO transport protocols
+
+
+## ✨Memory
+- ✅ Support long-term memory by providing a `LongTermMemoryBase` class
+- ✅ Provide a Mem0-based long-term memory implementation
+- ✅ Support both static- and agent-controlled long-term memory modes
+
+
+## Formatter
+- ✅ Support prompt construction/formatting with token count estimation
+- ✅ Support tools API in multi-agent prompt formatting
+
+
+## Model
+- ❌ Deprecate model configuration, use explicit object instantiation instead
+- ✅ Provide a new `ModelResponse` class for structured model responses
+- ✅ Support asynchronous model invocation
+- ✅ Support reasoning models
+- ✅ Support any combination of streaming/non-streaming, reasoning/non-reasoning and tools API
+
+
+## Agent
+- ❌ Deprecate `DialogAgent`, `DictDialogAgent` and prompt-based ReAct agent class
+- ➡️ Expose memory, formatter interfaces to the agent's constructor in ReActAgent
+- ➡️ Unify the signature of pre- and post- agent hooks
+- ✅ Support pre-/post-reasoning and pre-/post-acting hooks in ReActAgent class
+- ✅ Support asynchronous agent execution
+- ✅ Support interrupting agent's replying and customized interruption handling
+- ✅ Support automatic state management
+- ✅ Support parallel tool calls
+- ✅ Support two-modes long-term memory in ReActAgent class
+
+
+## Tool
+- ✅ Provide a more powerful `Toolkit` class for tools management
+- ✅ Provide a new `ToolResponse` class for structured and multimodal tool responses
+- ✅ Support group-wise tool management
+- ✅ Support agent to manage tools by itself
+- ✅ Support post-processing of tool responses
+- Tool function
+  - ✅ Support both async and sync functions
+  - ✅ Support both streaming and non-streaming return
+
+
+## Evaluation
+- ✅ Support ReAct agent-oriented evaluation
+- ✅ Support Ray-based distributed and concurrent evaluation
+- ✅ Support statistical analysis over evaluation results
+
+
+## AgentScope Studio
+- ✅ Support runtime tracing
+- ✅ Provide a built-in copilot agent named Friday
+
+
+## Logging
+- ❌ Deprecate `loguru` and use Python native `logging` module instead
+
+
+## Distribution
+- ❌ Deprecate distribution functionality momentarily, a new distribution module is coming soon
+
+
+## RAG
+- ❌ Deprecate RAG functionality momentarily, a new RAG module is coming soon
+
+
+## Parsers
+- ❌ Deprecate parsers module
+
+
+## WebBrowser
+- ❌ Deprecate the `WebBrowser` class and shift to MCP-based web browsing

docs/roadmap.md

@@ -0,0 +1,121 @@
+# Roadmap
+
+## Long-term Goals
+
+Offering **agent-oriented programming (AOP)** as a new programming paradigm to organize the design and implementation of next-generation LLM-empowered applications.
+
+## Current Focus (January 2026 - )
+
+### 🎙️ Voice Agent
+
+**Voice agents** are a domain we are highly focused on, and AgentScope will continue to invest in this direction.
+
+AgentScope aims to build **production-ready** voice agents rather than demonstration prototypes. This means our voice agents will:
+
+- Support **production-grade** deployment, including seamless frontend integration
+- Support **tool invocation**, not just voice conversations
+- Support **multi-agent** voice interactions
+
+#### Development Roadmap
+
+Our development strategy for voice agents consists of **three progressive milestones**:
+
+1. **TTS Models** → 2. **Multimodal Models** → 3. **Real-time Multimodal Models**
+
+---
+
+#### Phase 1: TTS (Text-to-Speech) Models
+
+- **Build TTS model base class infrastructure**
+  - Design and implement a unified TTS model base class
+  - Establish standardized interfaces for TTS model integration
+
+- **Horizontal API expansion**
+  - Support mainstream TTS APIs (e.g., OpenAI TTS, Google TTS, Azure TTS, ElevenLabs, etc.)
+  - Ensure consistent behavior across different TTS providers
+
+---
+
+#### Phase 2: Multimodal Models (Non-Realtime)
+
+- **Enable ReAct agents with multimodal support**
+  - Integrate multimodal models (e.g., qwen3-omni, gpt-audio) into existing ReAct agent framework
+  - Support audio input/output in non-realtime mode
+
+- **Advanced multimodal agent capabilities**
+  - Enable tool invocation within multimodal conversations
+  - Support multi-agent workflows with multimodal communication
+
+---
+
+#### Phase 3: Real-time Multimodal Models
+
+
+- **Beyond request-response**: Explore streaming, interrupt handling, and concurrent multimodal processing
+- **New programming paradigms**: Design agent programming models specifically tailored for real-time interactions
+- **Production readiness**: Ensure low-latency performance, stability, and scalability for production deployment
+
+### 🛠️ Agent Skill
+
+Provide **production-ready** agent skill integration solutions.
+
+### 🌐 Ecosystem Expansion
+
+- **A2UI (Agent-to-UI)**: Enable seamless agent-to-user interface interactions
+- **A2A (Agent-to-Agent)**: Enhance agent-to-agent communication capabilities
+
+### 🚀 Agentic RL
+
+- Support using [Tinker](https://tinker-docs.thinkingmachines.ai/) backend to tune agent applications on devices without GPU.
+- Support tuning agent applications based on their run history.
+- Integrate with AgentScope Runtime to provide better environment abstraction.
+- Add more tutorials and examples on how to build complex judge functions with the help of evaluation module.
+- Add more tutorials and examples on data selection and augmentation.
+
+### 📈 Code Quality
+
+Continuous refinement and improvement of code quality and maintainability.
+
+# Completed Milestones
+
+### AgentScope V1.0.0 Roadmap
+
+We are deeply grateful for the continuous support from the open-source community that has witnessed AgentScope's
+growth. Throughout our journey, we have maintained **developer-centric transparency** as our core principle,
+which will continue to guide our future development.
+
+As the AI agent ecosystem rapidly evolves, we recognize the need to adapt AgentScope to meet emerging trends and
+requirements. We are excited to announce the upcoming release of AgentScope v1.0.0, which marks a significant shift
+towards deployment-focused and secondary development direction. This new version will provide comprehensive support for agent developers
+with enhanced deployment capabilities and practical features. Specifically, the update will include:
+
+- ✨New Features
+  - 🛠️ Tool/MCP
+    - Support both sync/async tool functions
+    - Support streaming tool function
+    - Support parallel execution of tool functions
+    - Provide more flexible support for the MCP server
+
+  - 💾 Memory
+    - Enhance the existing short-term memory
+    - Support long-term memory
+
+  - 🤖 Agent
+    - Provide powerful ReAct-based out-of-the-box agents
+
+- 👨‍💻 Development
+  - Provide enhanced AgentScope Studio with visual components for developing, tracing and debugging
+  - Provide a built-in copilot for developing/drafting AgentScope applications
+
+- 🔍 Evaluation
+  - Provide built-in benchmarking and evaluation toolkit for agents
+  - Support result visualization
+
+- 🏗️ Deployment
+  - Support asynchronous agent execution
+  - Support session/state management
+  - Provide sandbox for tool execution
+
+Stay tuned for our detailed release notes and beta version, which will be available soon. Follow our GitHub
+repository and official channels for the latest updates. We look forward to your valuable feedback and continued
+support in shaping the future of AgentScope.

examples/agent_service/README.md

@@ -0,0 +1,78 @@
+# Agent Service
+
+Agent service is a FastAPI-based, multi-tenant and multi-session service built with AgentScope 2.0.
+
+This example demonstrates
+
+- how to set up the agent service with Redis storage, and
+- how to launch the service and its companion Web UI
+
+Details about the agent service please refer to the [tutorial](https://docs.agentscope.io/latest/en/deploy/agent-service).
+
+## Prerequisites
+
+- Python ≥ 3.11
+- Node.js ≥ 20 with `npx`
+- [optional] Gaode/AMap API key in `AMAP_API_KEY` (for the `amap` MCP)
+
+## Quickstart
+
+Install AgentScope from PyPI or source:
+
+```bash
+uv pip install agentscope[full]
+# or
+# uv pip install -e [full]
+```
+
+Install Redis and start it as backend storage:
+
+```bash
+# macOS (Homebrew)
+brew install redis
+brew services start redis
+
+# Linux (systemd)
+sudo apt install redis-server
+sudo systemctl start redis-server
+
+# Docker (cross-platform)
+docker run --rm -p 6379:6379 redis:7
+```
+
+Start the agent service:
+
+```bash
+cd examples/agent_service
+
+python main.py
+```
+
+Launch the Web UI in a separate terminal to experience a chat-style interface:
+
+```bash
+cd examples/web_ui/
+
+pnpm install
+# or npm install
+
+# Run in dev mode
+pnpm dev
+```
+
+After that, you can set the API endpoint `http://localhost:8000` in the Web UI and start experiencing the agent service.
+
+<img src="https://gw.alicdn.com/imgextra/i2/O1CN01Phmg1G1brIVC8WXyU_!!6000000003518-2-tps-2938-1736.png" alt="Web UI Screenshot" width="100%">
+
+## What Next
+
+- You can customize the service in `main.py` by adding your own MCPs, middlewares, or workspace manager implementations.
+
+- Experience the agent service, including
+    - human-in-the-loop interactions & permission system
+<img src="https://gw.alicdn.com/imgextra/i1/O1CN01vGGiBw20agWwpzmjy_!!6000000006866-2-tps-2934-1732.png" alt="Permission System" width="100%">
+
+    - schedule tasks
+<img src="https://gw.alicdn.com/imgextra/i1/O1CN01Xi3Qw71E2haKKu4z0_!!6000000000294-2-tps-2932-1738.png" alt="Schedule Tasks" width="100%">
+
+    - and more! (stay tuned for future updates)

examples/agent_service/main.py

@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""The example script to start the agent service."""
+import os
+
+import uvicorn
+from fastapi.middleware import Middleware
+from fastapi.middleware.cors import CORSMiddleware
+
+from agentscope.app import create_app, SubAgentTemplate
+from agentscope.app.message_bus import InMemoryMessageBus
+from agentscope.app.rag.knowledge_base_manager import CollectionPerKbManager
+from agentscope.app.storage import RedisStorage
+from agentscope.app.workspace_manager import LocalWorkspaceManager
+from agentscope.mcp import MCPClient, StdioMCPConfig, HttpMCPConfig
+from agentscope.permission import PermissionContext, PermissionMode
+from agentscope.rag import QdrantStore
+
+default_mcps = [
+    MCPClient(
+        name="browser-use",
+        mcp_config=StdioMCPConfig(
+            command="npx",
+            args=["@playwright/mcp@latest"],
+        ),
+        is_stateful=True,
+    ),
+]
+
+if os.getenv("AMAP_API_KEY"):
+    default_mcps.append(
+        MCPClient(
+            name="amap",
+            mcp_config=HttpMCPConfig(
+                url=f"https://mcp.amap.com/mcp?key="
+                f"{os.environ['AMAP_API_KEY']}",
+            ),
+            is_stateful=False,
+        ),
+    )
+
+storage = RedisStorage(
+    host="localhost",
+    port=6379,
+)
+
+vector_store = QdrantStore(location=":memory:")
+
+app = create_app(
+    storage=storage,
+    message_bus=InMemoryMessageBus(),
+    # -- To use a Redis-backed message bus instead (recommended for
+    # -- multi-process / production deployments), uncomment the lines
+    # -- below and replace the InMemoryMessageBus() above:
+    #
+    # from agentscope.app.message_bus import RedisMessageBus
+    # message_bus=RedisMessageBus(
+    #     host="localhost",
+    #     port=6379,
+    # ),
+    workspace_manager=LocalWorkspaceManager(
+        basedir=os.path.join(
+            os.path.dirname(os.path.abspath(__file__)),
+            "workspaces",
+        ),
+        # The default MCP servers that will be added into the workspace
+        default_mcps=default_mcps,
+    ),
+    # Knowledge base feature — backed by an in-memory Qdrant store. The
+    # CollectionPerKbManager allocates one collection per knowledge base,
+    # so any embedding dimension is allowed.
+    knowledge_base_manager=CollectionPerKbManager(
+        storage=storage,
+        vector_store=vector_store,
+    ),
+    # Customize your own subagent templates
+    custom_subagent_templates=[
+        SubAgentTemplate(
+            type="explorer",
+            description=(
+                "Read-only agents specialized in exploration tasks. It can "
+                "read files but cannot modify, create, or delete them. Use "
+                "this agent type when you need to investigate the codebase, "
+                "understand its structure, or gather information from files "
+                "to support planning—without making any changes."
+            ),
+            system_prompt_template="""You are {member_name}, an explorer \
+agent in team '{team_name}' led by {leader_name}.
+
+Team purpose: {team_description}
+
+Your role: {member_description}
+
+## Responsibilities
+- Complete the exploration tasks assigned by the team leader.
+- You are read-only: you may inspect files and the codebase, but you must \
+never modify, create, or delete anything.
+
+## Reporting
+- Always report the task result back to {leader_name} using the TeamSay \
+tool, whether the task succeeds or fails.
+- Keep your private reasoning private; only share conclusions and findings \
+that the leader needs.
+
+Note: `TeamSay` is your ONLY channel to communicate with {leader_name} and \
+the other team members. Any other output you produce is invisible to them, \
+so anything you want them to see MUST be sent through `TeamSay`.""",
+            permission_context=PermissionContext(
+                # Read-only
+                mode=PermissionMode.EXPLORE,
+            ),
+        ),
+    ],
+    extra_middlewares=[
+        Middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_methods=["*"],
+            allow_headers=["*"],
+        ),
+    ],
+)
+
+
+if __name__ == "__main__":
+    # Start the service
+    uvicorn.run(
+        "main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+    )

examples/long_term_memory/agentic_memory/README.md

@@ -0,0 +1,83 @@
+# Agentic Memory Middleware
+
+This example demonstrates `AgenticMemoryMiddleware`, a long-term memory middleware backed by human-readable Markdown files.
+
+No vector database or embedding model is required.
+
+## What the demo shows
+
+`main.py` runs a single Agent against one workspace directory for two turns:
+
+1. **Turn 1 — persist**
+   - Receives mock user input containing durable user information.
+   - Is explicitly asked to remember that information.
+   - Uses the built-in `Read` / `Write` tools to create or update files under `demo_workspace/Memory`.
+
+2. **Turn 2 — recall**
+   - The same Agent instance is asked about the earlier user information.
+   - Answers from the Markdown memory files persisted on disk by the middleware.
+
+After the first turn, the script prints the generated Markdown files so you can inspect exactly what was persisted.
+
+## Quickstart
+
+Install the dependencies by the following commands:
+
+```bash
+git clone -b main https://github.com/agentscope-ai/agentscope
+
+uv pip install agentscope
+# or from source
+# uv pip install -e .
+```
+
+Run the example with the commands:
+
+```bash
+cd agentscope/examples/long_term_memory/agentic_memory
+export DASHSCOPE_API_KEY=sk-...; python main.py
+```
+
+The demo workspace is created at:
+
+```text
+examples/long_term_memory/agentic_memory/demo_workspace/
+```
+
+## Markdown layout
+
+The middleware creates this directory automatically:
+
+```text
+<workdir>/Memory/
+`-- MEMORY.md
+```
+
+The Agent should write each durable memory into its own Markdown file with frontmatter, then add a short pointer to `MEMORY.md`:
+
+```markdown
+---
+name: User profile
+description: User lives in Hangzhou and prefers concise Chinese answers
+type: user
+---
+
+Alice Chen lives in Hangzhou and prefers concise Chinese answers.
+```
+
+`MEMORY.md` is an index, not the memory body:
+
+```markdown
+- [User profile](user_profile.md) — User location and answer-style preference.
+```
+
+On future turns, `MEMORY.md` is always included in the system prompt. The middleware can then select relevant topic files by filename and frontmatter description and inject their contents as a hint.
+
+## Notes
+
+- Memory is workspace-scoped: reuse the same `workdir` to reuse the same Markdown memory.
+- A fresh Agent instance can still recall previous facts because they are stored on disk, not in `Agent.state`.
+- The Agent is responsible for deciding what to save when the user asks it to remember something.
+- `MEMORY.md` should stay concise because it is included in every system prompt.
+- Topic files are ordinary Markdown and can be inspected, edited, committed, copied, or deleted with normal filesystem tools.
+

examples/long_term_memory/agentic_memory/main.py

@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+"""AgenticMemoryMiddleware end-to-end demo.
+
+The demo uses a single Agent with the filesystem-backed long-term memory
+middleware and the built-in ``Read`` / ``Write`` tools across two turns:
+
+1. The Agent receives mock user input that explicitly asks it to remember
+   durable user information. The middleware injects memory instructions and the
+   Agent writes Markdown files under ``demo_workspace/Memory``.
+2. The same Agent is then asked to recall the earlier user information. The
+   answer is grounded by the Markdown files persisted on disk by the
+   middleware.
+
+Requires:
+    pip install agentscope
+    export DASHSCOPE_API_KEY=sk-...
+"""
+import asyncio
+import os
+import shutil
+from pathlib import Path
+
+from pydantic import SecretStr
+
+from agentscope.agent import Agent
+from agentscope.credential import DashScopeCredential
+from agentscope.event import (
+    TextBlockDeltaEvent,
+    ToolCallDeltaEvent,
+    ToolCallStartEvent,
+    ToolResultEndEvent,
+    ToolResultTextDeltaEvent,
+)
+from agentscope.message import UserMsg
+from agentscope.middleware import AgenticMemoryMiddleware
+from agentscope.model import DashScopeChatModel
+from agentscope.permission import AdditionalWorkingDirectory, PermissionMode
+from agentscope.tool import Read, Toolkit, Write
+
+
+RESET_DEMO_WORKSPACE = True
+DEMO_ROOT = Path(__file__).with_name("demo_workspace")
+
+FIRST_USER_MESSAGE = """
+Please remember these durable facts for future conversations in this
+workspace:
+
+- My name is Alice Chen.
+- I live in Hangzhou.
+- I prefer concise Chinese answers.
+- When evaluating examples, I like seeing a fresh Agent instance prove that
+  long-term memory was persisted outside the current conversation state.
+
+Use the filesystem memory instructions in your system prompt: create or update
+a topic Markdown memory file with frontmatter, and update MEMORY.md with a
+short pointer to that file. Read MEMORY.md first if you need to update it.
+""".strip()
+
+SECOND_USER_MESSAGE = """
+What do you remember about my name, location, answer style, and how I like
+examples to demonstrate long-term memory? Read the relevant memory files if
+you need details before answering.
+""".strip()
+
+
+def _configure_demo_permissions(agent: Agent, workspace_root: Path) -> None:
+    """Allow the demo Agent to read and write inside the demo workspace.
+
+    Args:
+        agent (`Agent`):
+            The Agent whose permission context should be configured.
+        workspace_root (`Path`):
+            The directory containing the demo memory files.
+    """
+    agent.state.permission_context.mode = PermissionMode.ACCEPT_EDITS
+    agent.state.permission_context.working_directories[
+        str(workspace_root)
+    ] = AdditionalWorkingDirectory(
+        path=str(workspace_root),
+        source="file-system-memory-demo",
+    )
+
+
+def _build_agent(model: DashScopeChatModel, workspace_root: Path) -> Agent:
+    """Build a fresh Agent attached to one filesystem memory workspace.
+
+    Args:
+        model (`DashScopeChatModel`):
+            The chat model used by both the Agent and memory relevance
+            selection.
+        workspace_root (`Path`):
+            The directory that stores ``Memory/MEMORY.md`` and topic files.
+
+    Returns:
+        `Agent`:
+            A newly initialized Agent instance.
+    """
+    memory = AgenticMemoryMiddleware(workdir=str(workspace_root))
+    agent = Agent(
+        name="memory_assistant",
+        system_prompt=(
+            "You are a concise assistant. When the user asks you to remember "
+            "durable preferences or profile facts, persist them using the "
+            "filesystem memory instructions. Use the Read and Write tools for "
+            "memory files."
+        ),
+        model=model,
+        toolkit=Toolkit(tools=[Read(), Write()]),
+        middlewares=[memory],
+    )
+    _configure_demo_permissions(agent, workspace_root)
+    return agent
+
+
+async def _run_turn(agent: Agent, text: str) -> str:
+    """Run one streamed turn and print tool activity.
+
+    Args:
+        agent (`Agent`):
+            The Agent to run.
+        text (`str`):
+            The user message.
+
+    Returns:
+        `str`:
+            The concatenated assistant text response.
+    """
+    tool_names: dict[str, str] = {}
+    tool_args: dict[str, str] = {}
+    tool_results: dict[str, str] = {}
+    reply_parts: list[str] = []
+
+    async for event in agent.reply_stream(UserMsg("alice", text)):
+        if isinstance(event, ToolCallStartEvent):
+            tool_names[event.tool_call_id] = event.tool_call_name
+            tool_args[event.tool_call_id] = ""
+            tool_results[event.tool_call_id] = ""
+        elif isinstance(event, ToolCallDeltaEvent):
+            tool_args[event.tool_call_id] += event.delta
+        elif isinstance(event, ToolResultTextDeltaEvent):
+            tool_results[event.tool_call_id] += event.delta
+        elif isinstance(event, ToolResultEndEvent):
+            tool_id = event.tool_call_id
+            name = tool_names.pop(tool_id, "<unknown>")
+            arguments = tool_args.pop(tool_id, "")
+            result = tool_results.pop(tool_id, "")
+            print(f"[tool] {name}({arguments}) -> {event.state}")
+            for line in result.splitlines():
+                print(f"  {line}")
+        elif isinstance(event, TextBlockDeltaEvent):
+            reply_parts.append(event.delta)
+
+    return "".join(reply_parts)
+
+
+def _print_memory_files(workspace_root: Path) -> None:
+    """Print the Markdown files persisted by the memory middleware.
+
+    Args:
+        workspace_root (`Path`):
+            The demo workspace root.
+    """
+    memory_root = workspace_root / "Memory"
+    print(f"\n[Markdown memory files] {memory_root}")
+    if not memory_root.exists():
+        print("  The Memory directory has not been created yet.")
+        return
+
+    for path in sorted(memory_root.rglob("*.md")):
+        relative = path.relative_to(workspace_root)
+        print(f"\n--- {relative} ---")
+        print(path.read_text(encoding="utf-8").strip())
+
+
+def _print_soft_verification(workspace_root: Path) -> None:
+    """Print a lightweight check that expected memory keywords were saved.
+
+    Args:
+        workspace_root (`Path`):
+            The demo workspace root.
+    """
+    memory_root = workspace_root / "Memory"
+    combined = (
+        "\n".join(
+            path.read_text(encoding="utf-8", errors="replace")
+            for path in sorted(memory_root.rglob("*.md"))
+        )
+        if memory_root.exists()
+        else ""
+    )
+    checks = {
+        "MEMORY.md exists": (memory_root / "MEMORY.md").exists(),
+        "mentions Alice Chen": "Alice Chen" in combined,
+        "mentions Hangzhou": "Hangzhou" in combined,
+        "mentions concise Chinese answers": (
+            "concise Chinese" in combined or "Chinese answers" in combined
+        ),
+    }
+
+    print("\n[Soft verification]")
+    for label, ok in checks.items():
+        print(f"  {'PASS' if ok else 'WARN'} - {label}")
+
+
+async def main() -> None:
+    """Run the agentic memory demo."""
+    api_key = os.environ["DASHSCOPE_API_KEY"]
+
+    if RESET_DEMO_WORKSPACE:
+        print(f"=== resetting demo workspace: {DEMO_ROOT} ===")
+        shutil.rmtree(DEMO_ROOT, ignore_errors=True)
+    else:
+        print(f"=== reusing demo workspace: {DEMO_ROOT} ===")
+    DEMO_ROOT.mkdir(parents=True, exist_ok=True)
+
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(api_key=SecretStr(api_key)),
+        model="qwen3.7-max",
+        stream=False,
+    )
+
+    print("\n=== Turn 1: ask the Agent to persist user memory ===")
+    agent = _build_agent(model, DEMO_ROOT)
+    print(f"[user]\n{FIRST_USER_MESSAGE}\n")
+    first_reply = await _run_turn(agent, FIRST_USER_MESSAGE)
+    print(f"\n[assistant]\n{first_reply}")
+
+    _print_memory_files(DEMO_ROOT)
+    _print_soft_verification(DEMO_ROOT)
+
+    print("\n=== Turn 2: ask the same Agent to recall memory ===")
+    print(f"[user]\n{SECOND_USER_MESSAGE}\n")
+    second_reply = await _run_turn(agent, SECOND_USER_MESSAGE)
+    print(f"\n[assistant]\n{second_reply}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/long_term_memory/mem0/README.md

@@ -0,0 +1,387 @@
+# mem0 middleware example
+
+One runnable demo (`oss_demo.py`) showing the
+[mem0](https://github.com/mem0ai/mem0) middleware plugged into an
+`agentscope.agent.Agent`. Drives two consecutive agent sessions for
+the same `user_id` so mem0's cross-session memory effect is visible,
+and prints each middleware contribution (retrieval / tool call /
+write-back) inline so you can see when each path fires.
+
+The demo defaults to the **OSS backend** (open-source mem0,
+self-hosted via local Qdrant) with mem0 driven by AgentScope's own
+DashScope chat + embedding model — no separate OpenAI key needed
+by mem0. To run it against the hosted **mem0
+Platform** instead, swap the `Mem0Middleware(...)` construction for
+the alternative shown inline (look for the
+``# For the hosted mem0 Platform, swap …`` comment in `oss_demo.py`)
+— the rest of the demo is identical.
+
+## Install
+
+```bash
+# mem0 is an optional AgentScope dependency — pull it via the extra:
+pip install "agentscope[mem0]"      # resolves to mem0ai>=2.0.0,<3.0.0
+# (equivalent to `pip install agentscope mem0ai>=2.0.0,<3.0.0`)
+
+export DASHSCOPE_API_KEY=sk-...     # OSS path
+# Platform path (only if you switch):
+# export MEM0_API_KEY=m0-...
+# export OPENAI_API_KEY=sk-...      # only needed if your agent's chat model is OpenAI
+```
+
+## Import path
+
+`Mem0Middleware` is exported from the middleware package:
+
+```python
+from agentscope.middleware import Mem0Middleware
+from agentscope.tool import Toolkit
+```
+
+## Three construction paths
+
+```python
+# 1. Models — build a local OSS AsyncMemory wired to your AgentScope
+#    chat + embedding model. mem0 defaults for everything else.
+Mem0Middleware(
+    user_id="alice",
+    chat_model=my_chat_model,
+    embedding_model=my_embedding_model,
+    mode="both",
+)
+
+# 2. Models + custom mem0_config — same as (1), but start from your
+#    customized MemoryConfig (custom vector store, history DB,
+#    reranker, ...). `chat_model` / `embedding_model` always WIN:
+#    if mem0_config already specifies an .llm or .embedder, it gets
+#    OVERWRITTEN by the AgentScope adapter built from your model.
+#    Every other field of mem0_config (vector_store, history_db_path,
+#    reranker, etc.) is preserved as-is.
+Mem0Middleware(
+    user_id="alice",
+    chat_model=my_chat_model,
+    embedding_model=my_embedding_model,
+    mem0_config=MemoryConfig(
+        vector_store=VectorStoreConfig(
+            provider="qdrant",
+            config={"host": "my-qdrant", "port": 6333},
+        ),
+        history_db_path="/data/mem0_history.db",
+    ),
+    mode="both",
+)
+
+# 3. Client — bring your own pre-built mem0 client. Accepts EITHER
+#    backend: `mem0.AsyncMemory` (open-source / self-hosted) or
+#    `mem0.AsyncMemoryClient` (hosted Platform). Use this when you
+#    want full control over the mem0 setup — custom subclass, a
+#    pre-warmed client shared across many agents, exotic config
+#    that doesn't fit the `build_mem0_config` helper, etc.
+#
+# OSS backend (you assemble the AsyncMemory yourself):
+Mem0Middleware(
+    user_id="alice",
+    client=AsyncMemory(),  # or AsyncMemory.from_config({...})
+    mode="both",
+)
+
+# Hosted Platform backend:
+Mem0Middleware(
+    user_id="alice",
+    client=AsyncMemoryClient(api_key="m0-..."),
+    mode="both",
+)
+```
+
+Precedence and validation matrix:
+
+| `client` | `mem0_config` | `chat_model` | `embedding_model` | Behavior |
+|:-:|:-:|:-:|:-:|---|
+| ✓ | — | — | — | Use `client` as-is. |
+| ✓ | any | any | any | Use `client`; the other three are ignored, and a `WARNING` log lists which kwargs got dropped. |
+| — | ✓ | — | — | Wrap `mem0_config` in an `AsyncMemory`, no overrides. |
+| — | ✓ | ✓ | — | Wrap + override `.llm` with the AgentScope adapter; keep `.embedder` from `mem0_config`. |
+| — | ✓ | — | ✓ | Wrap + override `.embedder` only; keep `.llm` from `mem0_config`. |
+| — | ✓ | ✓ | ✓ | Wrap + override both `.llm` and `.embedder` (other fields of `mem0_config` preserved). |
+| — | — | ✓ | ✓ | Build a fresh `MemoryConfig` (mem0 defaults for vector store / history DB) with the AgentScope adapters wired in. |
+| — | — | ✓ | — | ❌ `ValueError` — `chat_model` and `embedding_model` must be passed together when `mem0_config` is omitted. |
+| — | — | — | ✓ | ❌ Same. |
+| — | — | — | — | ❌ `ValueError` — need one of: `client`, `mem0_config`, or both `chat_model` + `embedding_model`. |
+
+Why the "client wins" and "config override" paths exist:
+
+- **`client` wins** lets one `Mem0Middleware(...)` call
+  shape work for both library callers (who pass AgentScope models)
+  and production setups (who supply a pre-built `client`). The
+  `WARNING` log makes any mismatch visible without crashing.
+- **Config override of `mem0_config.llm` / `.embedder`** lets you
+  keep one canonical `MemoryConfig` template (custom vector store,
+  history DB, reranker, …) and swap just the LLM / embedder per
+  call site by passing `chat_model` / `embedding_model`.
+
+## How the middleware controls memory
+
+The `mode` parameter selects one of three patterns. They differ by
+**what the LLM sees** and **what fires automatically**:
+
+### `static_control`
+The middleware does the work, the agent is unaware. Mirroring
+AgentScope 1.x's `ReActAgent._retrieve_from_long_term_memory`:
+
+1. **`on_reply` (pre)** queries mem0 with the latest user message
+   and pre-fetches the results.
+2. **At `ReplyStartEvent`** — which fires right after the agent has
+   ingested the new user input into `state.context` and before the
+   reasoning loop starts — the middleware appends an
+   `AssistantMsg(name="memory", ...)` to `state.context`. This puts
+   the memory note IMMEDIATELY after the user's new message, matching
+   v1's placement (it ran right after `self.memory.add(msg)`).
+3. **`on_reply` (post)** writes the new `(user, assistant)` exchange
+   back to mem0.
+
+The injected memory message **persists** in the agent's context
+across turns. Long sessions accumulate one per turn that retrieved
+anything; if that becomes a token concern, post-process with
+`compress_context` or write your own middleware to pop them.
+
+### `agent_control`
+The middleware lists two tools — `search_memory(keywords, limit)` and
+`add_memory(thinking, content)` — and otherwise stays out of the way.
+Pass them into the agent's toolkit explicitly when constructing the
+agent:
+
+```python
+mw = Mem0Middleware(..., mode="agent_control")
+agent = Agent(
+    ...,
+    toolkit=Toolkit(tools=await mw.list_tools()),
+    middlewares=[mw],
+)
+```
+
+The system prompt gets a short nudge telling the agent that memory
+tools exist; the actual per-tool usage guidance comes through the
+standard tool schema. No automatic retrieval or write-back.
+
+### `both` (default)
+Both patterns are active simultaneously: memories are auto-retrieved
+and appended to the agent's context as an assistant note, AND the
+tools (with their system-prompt hint) are exposed for explicit
+on-demand search / save. This matches AgentScope 1.x's
+`ReActAgent.long_term_memory_mode` default.
+
+## Sharing one middleware across agents
+
+The local OSS mem0 backend uses on-disk Qdrant by default, and Qdrant
+takes an **exclusive lock** on the storage folder
+(``/tmp/qdrant`` by default). Two ``Mem0Middleware`` instances each
+built from ``chat_model`` + ``embedding_model`` would each construct
+their own ``AsyncMemory`` → second one crashes on the lock:
+
+```
+RuntimeError: Storage folder /tmp/qdrant is already accessed by
+another instance of Qdrant client.
+```
+
+Fix: build **one** ``Mem0Middleware`` instance and pass it to every
+agent that should share the same memory namespace:
+
+```python
+mw = Mem0Middleware(
+    user_id="alice",
+    chat_model=chat_model,
+    embedding_model=embedding_model,
+    mode="both",
+)
+agent_a = Agent(
+    ...,
+    toolkit=Toolkit(tools=await mw.list_tools()),
+    middlewares=[mw],
+)
+agent_b = Agent(
+    ...,
+    toolkit=Toolkit(tools=await mw.list_tools()),
+    middlewares=[mw],
+)
+```
+
+This is what the demo does. The memory tools receive the live
+`AgentState` at call time, and the middleware resolves the active
+agent by `state.session_id`, so sharing one middleware across agents
+is safe.
+
+If you genuinely need a separate Qdrant store per agent, pass a
+``mem0_config`` with a distinct ``vector_store.config.path`` or
+``collection_name`` for each one.
+
+### Recommended: run Qdrant in Docker (especially on Windows)
+
+The local on-disk Qdrant works for single-process demos but is
+brittle in real deployments — and **outright painful on Windows**,
+where the filesystem-lock semantics differ from Unix and the
+exclusive-lock failure mode is harder to recover from. For anything
+beyond a single-process Linux/macOS sandbox, run Qdrant as a service:
+
+```bash
+docker run -p 6333:6333 -p 6334:6334 \
+    -v $(pwd)/qdrant_storage:/qdrant/storage \
+    qdrant/qdrant
+```
+
+Then point mem0 at it instead of the on-disk path:
+
+```python
+from mem0.configs.base import MemoryConfig
+from mem0.vector_stores.configs import VectorStoreConfig
+
+mem0_cfg = MemoryConfig(
+    vector_store=VectorStoreConfig(
+        provider="qdrant",
+        config={
+            "collection_name": "mem0",
+            "host": "localhost",     # the Docker container
+            "port": 6333,
+            "embedding_model_dims": 1536,
+        },
+    ),
+)
+Mem0Middleware(
+    user_id="alice",
+    chat_model=chat_model,
+    embedding_model=embedding_model,
+    mem0_config=mem0_cfg,
+)
+```
+
+Benefits over on-disk:
+
+- No file-lock contention — multiple Python processes can connect.
+- Survives across runs without manual file cleanup.
+- Same shape works for remote Qdrant (Qdrant Cloud, your own
+  Kubernetes deployment) — just change ``host`` / ``port`` /
+  ``api_key``.
+
+## Memory scoping (`user_id` × `agent_id`)
+
+mem0 tags every stored memory with the `user_id` and `agent_id`
+filter values passed at `add` time, and searches by AND-matching those
+tags. The middleware exposes the agent dimension via the
+`scope_search_by_agent` flag (default `True`):
+
+| `scope_search_by_agent` | What `add` tags the memory with | What `search` filters by | Effect |
+| --- | --- | --- | --- |
+| `True` (default) | `user_id` + `agent_id` | `user_id` + `agent_id` | Strict per-agent silos. Agent A's memories invisible to agent B for the same user. |
+| `False` | `user_id` + `agent_id` (unchanged) | `user_id` only | Read-broad, write-narrow. All agents for the same user share a memory pool, but each memory still records which agent wrote it (visible in mem0 metadata). |
+
+`agent_id` defaults to `agent.name`. Override via `agent_id="..."` or
+`agent_id=lambda agent: ...` on the middleware constructor.
+
+When to relax `scope_search_by_agent`:
+
+- One user has multiple specialized agents (research / coding /
+  scheduling) that should benefit from each other's discoveries about
+  the user.
+- An agent's `name` might change across deployments but you want the
+  memory to persist across name changes.
+
+### A note on agent-centric extraction (currently unreachable)
+
+mem0 v2's extraction prompt
+([`ADDITIVE_EXTRACTION_PROMPT`](https://github.com/mem0ai/mem0/blob/main/mem0/configs/prompts.py))
+has a conditional suffix that switches framing from user-centric
+("User stated X") to **agent-centric** ("Agent was informed of X" /
+"Agent recommended Y"). It's gated on
+`is_agent_scoped = bool(filters.agent_id) and not filters.user_id` —
+i.e. only when `agent_id` is provided *without* `user_id`. The
+middleware always passes `user_id` (it's a required constructor arg),
+so this agent-centric suffix is unreachable through `Mem0Middleware`
+today. In practice that's fine — agent persona / configuration is
+usually expressed via system prompt rather than long-term memory.
+
+## Service-mode integration (`agentscope.app`)
+
+The demos above use the **library mode** — you construct `Agent`
+yourself and pass `Mem0Middleware` into its `middlewares=[...]`. For
+production deployments via `agentscope.app` (the FastAPI service
+layer), the `user_id` already flows through the framework from the
+`X-User-ID` HTTP header. Hook in through the
+[`extra_agent_middlewares`](../../../../src/agentscope/app/_types.py)
+factory:
+
+```python
+from agentscope.app import create_app
+from agentscope.middleware import Mem0Middleware
+from agentscope.middleware._longterm_memory._mem0._agentscope_adapter \
+    import build_mem0_config
+from mem0 import AsyncMemory
+
+# Build the mem0 client ONCE at module scope — local OSS Qdrant
+# takes an exclusive lock on its storage folder; per-request
+# construction would deadlock under concurrent traffic.
+chat_model = ...     # shared AgentScope ChatModelBase
+emb_model  = ...     # shared AgentScope EmbeddingModelBase
+mem0_client = AsyncMemory(
+    config=build_mem0_config(
+        chat_model=chat_model,
+        embedding_model=emb_model,
+    ),
+)
+
+
+async def long_term_memory_factory(
+    user_id: str,         # ← from the authenticated X-User-ID header
+    agent_id: str,
+    session_id: str,
+) -> list:
+    return [
+        Mem0Middleware(
+            user_id=user_id,
+            client=mem0_client,    # shared across all requests
+            mode="both",
+        ),
+    ]
+
+
+app = create_app(
+    ...,
+    extra_agent_middlewares=long_term_memory_factory,
+)
+```
+
+Key points:
+
+- The factory is `async (user_id, agent_id, session_id) ->
+  list[MiddlewareBase]`, called **once per agent assembly**
+  (i.e. per chat turn / scheduled trigger). It returns fresh
+  `Mem0Middleware` instances each time, but they share a single
+  underlying mem0 client.
+- `user_id` is the authenticated caller, injected by `agentscope.app`
+  via `get_current_user_id` (currently from `X-User-ID` header; will
+  become JWT-based when auth lands upstream). You forward it straight
+  to `Mem0Middleware(user_id=user_id, ...)` — no resolver callable
+  needed.
+- For hosted mem0 Platform, swap the `AsyncMemory(config=...)`
+  construction for `AsyncMemoryClient(api_key=...)` — same factory
+  shape, no Qdrant lock concern.
+
+## Notes on the AgentScope-as-mem0-backend path
+
+When you pass `chat_model` + `embedding_model`, the middleware
+internally:
+
+1. Registers `AgentScopeLLM` / `AgentScopeEmbedding` in mem0's factory
+   dicts under provider name `"agentscope"`.
+2. Substitutes `LlmConfig` / `EmbedderConfig` with subclasses whose
+   validator allows `"agentscope"` (mem0's stock validator hardcodes a
+   whitelist that doesn't include us). Other providers continue to be
+   rejected with mem0's original error.
+3. Builds an `AsyncMemory` whose `.llm` and `.embedding_model` route
+   through the AgentScope adapters.
+4. Bridges mem0's sync API onto AgentScope's async models via a
+   persistent background event loop, so async clients (e.g. Ollama's
+   `AsyncClient`) keep their connection pool across calls.
+
+Your embedding model's `dimensions` must match the vector store's
+expected dim — mem0's default Qdrant expects 1536, which matches
+DashScope's `text-embedding-v2` at `dimensions=1536` (the value used
+in `oss_demo.py`).

examples/long_term_memory/mem0/oss_demo.py

@@ -0,0 +1,325 @@
+# -*- coding: utf-8 -*-
+"""Mem0 middleware demo (open-source mem0, AgentScope-driven).
+
+Drives two independent agent sessions for the same ``user_id`` so
+mem0's cross-session memory effect is visible. Each turn streams
+events from ``agent.reply_stream`` and prints the ones that matter:
+
+- ``[mem0 → context (static)]`` — the memory note the middleware
+  appended to ``state.context`` (fires at ``ReplyStartEvent``, before
+  any tool call, so the output order matches the data flow)
+- ``[tool call (agent)]`` — each ``search_memory`` / ``add_memory``
+  invocation the agent makes on its own
+- ``[assistant]`` — the assistant's reply, concatenated from the
+  ``TextBlockDeltaEvent`` stream
+- ``[context → mem0 (static)]`` — facts the middleware wrote back
+  after the turn
+
+The mode tag (``static`` / ``agent``) on each line tells you which
+control path produced it.
+
+Starts each run from a clean mem0 store (for ``user_id``) so the
+demo is reproducible.
+
+Requires:
+    pip install agentscope mem0ai
+    export DASHSCOPE_API_KEY=sk-...
+"""
+import asyncio
+import logging
+import os
+import shutil
+
+from mem0 import AsyncMemory
+from mem0.configs.base import MemoryConfig
+from mem0.vector_stores.configs import VectorStoreConfig
+
+from agentscope.agent import Agent
+from agentscope.credential import DashScopeCredential
+from agentscope.embedding import DashScopeEmbeddingModel
+from agentscope.event import (
+    ReplyStartEvent,
+    TextBlockDeltaEvent,
+    ToolCallDeltaEvent,
+    ToolCallStartEvent,
+    ToolResultEndEvent,
+    ToolResultTextDeltaEvent,
+)
+from agentscope.message import UserMsg
+from agentscope.middleware import Mem0Middleware
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+
+
+MODE = "both"  # try "static_control" or "agent_control" too
+
+
+# Silence mem0's noisy init warnings (qdrant migration notice, spaCy
+# missing, fastembed missing) — they're informational, not actionable.
+logging.getLogger("mem0").setLevel(logging.ERROR)
+
+
+async def _facts_in_mem0(client: AsyncMemory, user_id: str) -> list[str]:
+    """Return mem0's current facts for ``user_id`` as plain strings."""
+    res = await client.get_all(filters={"user_id": user_id})
+    items = res.get("results", res) if isinstance(res, dict) else res
+    out: list[str] = []
+    for m in items:
+        if isinstance(m, dict):
+            text = m.get("memory")
+            if isinstance(text, str) and text:
+                out.append(text)
+    return out
+
+
+def _injected_memory_bullets(agent: Agent) -> list[str]:
+    """Extract the bullet lines from the memory note the middleware
+    appended to ``agent.state.context`` (if any) — strips the section
+    header and intro so we see only the actual retrieved facts."""
+    for msg in agent.state.context:
+        if getattr(msg, "name", None) != "memory":
+            continue
+        hint_text = "\n".join(
+            block.hint for block in msg.get_content_blocks("hint")
+        )
+        return [
+            line[2:].strip()
+            for line in hint_text.splitlines()
+            if line.startswith("- ")
+        ]
+    return []
+
+
+async def _run_turn(agent: Agent, user_msg: UserMsg) -> str:
+    """Drive one reply turn through ``agent.reply_stream`` and print
+    each middleware contribution as it happens, in the order it
+    happens:
+
+    1. ``ReplyStartEvent`` fires right after the agent ingests the new
+       user input AND the middleware has appended any retrieved memory
+       note to ``state.context`` (static path) — so this is the right
+       place to surface ``[mem0 → context]``.
+    2. ``ToolCallStartEvent`` / ``ToolResultEndEvent`` bracket each
+       ``search_memory`` / ``add_memory`` invocation the agent makes
+       on its own (agent path).
+    3. ``TextBlockDeltaEvent`` carries the assistant's streamed reply
+       text — concatenating every delta yields the final message
+       content (there is no separate "final Msg" reply_stream
+       withholds).
+
+    Each printed line is tagged with the mem0 control path that
+    produced it (``static`` vs ``agent``) so the demo stays readable
+    in any of the three modes.
+    """
+    pending_args: dict[str, str] = {}
+    pending_names: dict[str, str] = {}
+    pending_results: dict[str, str] = {}
+    text_parts: list[str] = []
+    memory_announced = False
+
+    async for ev in agent.reply_stream(inputs=user_msg):
+        if isinstance(ev, ReplyStartEvent) and not memory_announced:
+            injected = _injected_memory_bullets(agent)
+            print(
+                f"[mem0 → context (static)] retrieved "
+                f"{len(injected)} memory note(s):",
+            )
+            for b in injected:
+                print(f"  ← {b}")
+            memory_announced = True
+        elif isinstance(ev, ToolCallStartEvent):
+            pending_names[ev.tool_call_id] = ev.tool_call_name
+            pending_args[ev.tool_call_id] = ""
+            pending_results[ev.tool_call_id] = ""
+        elif isinstance(ev, ToolCallDeltaEvent):
+            pending_args[ev.tool_call_id] += ev.delta
+        elif isinstance(ev, ToolResultTextDeltaEvent):
+            pending_results[ev.tool_call_id] += ev.delta
+        elif isinstance(ev, ToolResultEndEvent):
+            name = pending_names.pop(ev.tool_call_id, "<unknown>")
+            args = pending_args.pop(ev.tool_call_id, "")
+            result = pending_results.pop(ev.tool_call_id, "")
+            # ev.state is a StrEnum at the type level but pydantic
+            # may have deserialized it to a plain str; f-string both
+            # cases yields the same value string.
+            print(f"[tool call (agent)] {name}({args})  → state={ev.state}")
+            for line in result.splitlines() or [""]:
+                if line:
+                    print(f"  → {line}")
+        elif isinstance(ev, TextBlockDeltaEvent):
+            text_parts.append(ev.delta)
+
+    return "".join(text_parts)
+
+
+async def main() -> None:
+    """Drive two cross-session agent turns and print middleware effects."""
+    api_key = os.environ["DASHSCOPE_API_KEY"]
+    user_id = "alice"
+
+    # Wipe mem0's local files BEFORE constructing the client so each
+    # demo run starts clean. We don't use ``mem0_client.delete_all()``
+    # because qdrant-client's local SQLite layer has a race under
+    # mem0's parallel ``asyncio.gather`` deletes (sqlite3.InterfaceError).
+    qdrant_path = "/tmp/qdrant"  # matches the vector_store config below
+    history_db = os.path.expanduser("~/.mem0/history.db")
+    print("=== resetting mem0 local state ===")
+    print(f"  rm -rf {qdrant_path}")
+    shutil.rmtree(qdrant_path, ignore_errors=True)
+    print(f"  rm -f  {history_db}")
+    try:
+        os.remove(history_db)
+    except FileNotFoundError:
+        pass
+
+    # `stream` can be True or False — the AgentScope→mem0 adapter
+    # drains an async generator and uses the last chunk (which carries
+    # the full accumulated content per AgentScope's streaming contract).
+    # The agent's own `reply_stream` still emits per-delta events
+    # regardless of this setting, so streaming-mode does not change the
+    # demo's printed output shape.
+    chat_model = DashScopeChatModel(
+        credential=DashScopeCredential(api_key=api_key),
+        model="qwen3.7-max",
+        stream=False,
+    )
+    embedding_model = DashScopeEmbeddingModel(
+        credential=DashScopeCredential(api_key=api_key),
+        model="text-embedding-v4",
+        dimensions=1536,  # matches mem0's Qdrant default
+    )
+
+    # Explicit vector-store config (here we just spell out mem0's
+    # default local Qdrant — collection ``mem0``, on-disk at
+    # ``/tmp/qdrant``, 1536-d vectors). Override any of these for
+    # remote Qdrant, alternate collection names, etc. Pass the
+    # ``MemoryConfig`` through ``mem0_config=`` and the middleware
+    # keeps everything you set, only swapping ``.llm`` and
+    # ``.embedder`` to route through your AgentScope models.
+    #
+    # Recommended for Windows users and any production setup: run
+    # Qdrant in Docker and connect over the network instead of using
+    # the local on-disk backend. Local on-disk Qdrant takes an
+    # exclusive file lock that's brittle on Windows (different
+    # filesystem-lock semantics) and breaks under concurrent agent
+    # instances. To switch:
+    #
+    #   docker run -p 6333:6333 -p 6334:6334 \\
+    #       -v $(pwd)/qdrant_storage:/qdrant/storage \\
+    #       qdrant/qdrant
+    #
+    #   vector_store=VectorStoreConfig(
+    #       provider="qdrant",
+    #       config={
+    #           "collection_name": "mem0",
+    #           "host": "localhost",   # Docker container
+    #           "port": 6333,
+    #           "embedding_model_dims": 1536,
+    #       },
+    #   )
+    #
+    # (You'd also drop the ``shutil.rmtree(qdrant_path)`` wipe above —
+    # state lives in the Docker volume, not the local filesystem.)
+    mem0_cfg = MemoryConfig(
+        vector_store=VectorStoreConfig(
+            provider="qdrant",
+            config={
+                "collection_name": "mem0",
+                "path": qdrant_path,
+                "embedding_model_dims": 1536,
+                "on_disk": False,
+            },
+        ),
+    )
+
+    mw = Mem0Middleware(
+        user_id=user_id,
+        agent_id="datascope_assistant",
+        chat_model=chat_model,
+        embedding_model=embedding_model,
+        mem0_config=mem0_cfg,
+        mode=MODE,
+        top_k=5,
+    )
+    # For the hosted mem0 Platform, swap the construction above for:
+    #
+    # from mem0 import AsyncMemoryClient
+    # mw = Mem0Middleware(
+    #       user_id=user_id,
+    #       client=AsyncMemoryClient(api_key=os.environ["MEM0_API_KEY"]),
+    #       mode=MODE,
+    #   )
+    #
+    # No local Qdrant / vector_store config needed — extraction and
+    # storage all happen in mem0's cloud service.
+    # pylint: disable-next=protected-access
+    mem0_client: AsyncMemory = mw._client  # demo only — peek at the
+    # constructed client to inspect mem0 state between turns.
+
+    # =================================================================
+    # SESSION 1
+    # =================================================================
+    print(f"\n=== SESSION 1 (mode={MODE!r}) ===")
+    user_msg_1 = (
+        "Hi! For any chart, please default to dark mode and use "
+        "matplotlib. Also I'm based in Hangzhou."
+    )
+    print(f"\n[user] {user_msg_1}\n")
+
+    before = await _facts_in_mem0(mem0_client, user_id)
+
+    agent = Agent(
+        name="datascope_assistant",
+        system_prompt=(
+            "You are a helpful data-analysis assistant. Be concise. "
+            "If you learn a durable user preference, save it with "
+            "the add_memory tool when one is available."
+        ),
+        model=chat_model,
+        toolkit=Toolkit(tools=await mw.list_tools()),
+        middlewares=[mw],
+    )
+    reply_text = await _run_turn(agent, UserMsg("alice", user_msg_1))
+    print(f"\n[assistant] {reply_text}")
+
+    after = await _facts_in_mem0(mem0_client, user_id)
+    new = [f for f in after if f not in before]
+    print(f"\n[context → mem0 (static)] extracted {len(new)} new fact(s):")
+    for f in new:
+        print(f"  + {f}")
+
+    # =================================================================
+    # SESSION 2 — fresh Agent, empty chat context. mem0 should bridge.
+    # =================================================================
+    print(f"\n=== SESSION 2 (fresh agent, mem0 bridges; mode={MODE!r}) ===")
+    user_msg_2 = (
+        "Plot me a bar chart of monthly sales — pick reasonable "
+        "defaults for theme and library."
+    )
+    print(f"\n[user] {user_msg_2}\n")
+
+    before = await _facts_in_mem0(mem0_client, user_id)
+
+    agent = Agent(
+        name="datascope_assistant",
+        system_prompt=(
+            "You are a helpful data-analysis assistant. Be concise. "
+            "If you learn a durable user preference, save it with "
+            "the add_memory tool when one is available."
+        ),
+        model=chat_model,
+        toolkit=Toolkit(tools=await mw.list_tools()),
+        middlewares=[mw],
+    )
+    reply_text = await _run_turn(agent, UserMsg("alice", user_msg_2))
+    print(f"\n[assistant] {reply_text}")
+
+    after = await _facts_in_mem0(mem0_client, user_id)
+    new = [f for f in after if f not in before]
+    print(f"\n[context → mem0 (static)] extracted {len(new)} new fact(s):")
+    for f in new:
+        print(f"  + {f}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/rag/README.md

@@ -0,0 +1,36 @@
+# RAG Examples
+
+Two library-mode walk-throughs of `agentscope.rag` — no FastAPI service, no manager, no message bus. Each script wires the building blocks (parser, chunker, embedding model, vector store, `KnowledgeBase` handle) by hand so the data flow is visible end-to-end.
+
+| Script | What it shows |
+| --- | --- |
+| [`index_and_search.py`](./index_and_search.py) | The minimal pipeline: parse → chunk → embed → insert, then `KnowledgeBase.search`. Start here. |
+| [`integrate_with_agent.py`](./integrate_with_agent.py) | Attaches the same `KnowledgeBase` to an `Agent` via `RAGMiddleware`, in both `static` (auto-inject) and `agentic` (tool-driven) modes. |
+
+Both examples use an in-memory Qdrant store (`location=":memory:"`) and the DashScope `text-embedding-v4` model, so no external services are required.
+
+## Install
+
+```bash
+# From PyPI
+uv pip install "agentscope[rag]"
+
+# Or from source (repo root)
+uv pip install -e ".[rag]"
+```
+
+`integrate_with_agent.py` additionally uses `DashScopeChatModel`, which is already in the base `agentscope` dependencies.
+
+## Run
+
+```bash
+export DASHSCOPE_API_KEY=sk-...
+
+python examples/rag/index_and_search.py
+python examples/rag/integrate_with_agent.py
+```
+
+## Service mode
+
+The two scripts above are library-mode — you drive the pipeline yourself in a single process. For the full service-mode experience (FastAPI endpoints for knowledge base CRUD, document upload, indexing workers, and search), see [`examples/agent_service`](../agent_service) for the backend and [`examples/web_ui`](../web_ui) for the chat-style UI.
+

examples/rag/index_and_search.py

@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+"""Library-mode RAG walk-through — no FastAPI service, no manager.
+
+End-to-end demo of the building blocks in :mod:`agentscope.rag`:
+
+1. **Vector store** — :class:`QdrantStore` (in-memory here; swap to
+   ``url=...`` for a real Qdrant server).
+2. **Parser** — :class:`TextParser` turning raw bytes into ``Section``
+   objects.
+3. **Chunker** — :class:`ApproxTokenChunker` splitting sections into
+   ``Chunk`` objects (the indexable unit).
+4. **Embedding** — any :class:`EmbeddingModelBase` subclass; we use the
+   DashScope text-embedding model.
+5. **KnowledgeBase** — the runtime handle that ties (embedding, vector
+   store, collection) together and exposes
+   ``insert_document`` / ``search`` / ``list_documents`` /
+   ``delete_document``.  This is what :class:`RAGMiddleware` consumes.
+
+The pipeline:
+
+    bytes ── parser ──► Section[] ── chunker ──► Chunk[]
+                                                  │
+                                                  ▼
+                                   knowledge.insert_document(chunks)
+                                                  │
+                                                  ▼
+                            embed → store on the bound collection
+
+Search mirrors the same shape: hand the query to
+``knowledge.search(...)``, get ``VectorSearchResult`` back.
+
+Run with::
+
+    DASHSCOPE_API_KEY=sk-... python examples/rag/index_and_search.py
+"""
+import asyncio
+import os
+
+from agentscope.credential import DashScopeCredential
+from agentscope.embedding import DashScopeEmbeddingModel
+from agentscope.message import TextBlock
+from agentscope.rag import (
+    ApproxTokenChunker,
+    KnowledgeBase,
+    QdrantStore,
+    TextParser,
+)
+
+
+COLLECTION = "demo-kb"
+
+# A toy corpus inlined as bytes so the example has no on-disk
+# dependencies. In real use these would come from uploaded files or
+# blob-store reads.
+DOCUMENTS: dict[str, bytes] = {
+    "cats.md": (
+        b"# Cats\n\n"
+        b"Cats are small carnivorous mammals. They are popular as pets "
+        b"because of their playful and affectionate nature.\n\n"
+        b"Domestic cats sleep around 12-16 hours per day. They are most "
+        b"active at dawn and dusk (crepuscular behaviour).\n"
+    ),
+    "agentscope.md": (
+        b"# AgentScope\n\n"
+        b"AgentScope is a developer-centric framework for building "
+        b"multi-agent LLM applications. It emphasises transparency, "
+        b"controllability, and a clear separation between agent logic "
+        b"and infrastructure.\n\n"
+        b"Its RAG module ships a parser/chunker/embedding/vector-store "
+        b"pipeline that can be wired up without the FastAPI service.\n"
+    ),
+}
+
+
+async def build_index(
+    knowledge: KnowledgeBase,
+    parser: TextParser,
+    chunker: ApproxTokenChunker,
+) -> None:
+    """Parse → chunk → insert for every demo document.
+
+    Embedding and vector-store insertion are encapsulated inside
+    ``knowledge.insert_document`` — caller side only has to bring
+    pre-chunked content.
+    """
+    for filename, file_bytes in DOCUMENTS.items():
+        # 1. Parse: bytes → list[Section]
+        sections = await parser.parse(file=file_bytes, filename=filename)
+
+        # 2. Chunk: list[Section] → list[Chunk]
+        chunks = await chunker.chunk(sections)
+
+        # 3. Insert: embeds every chunk under one document id.  The
+        #    returned id is yours to keep for later
+        #    ``delete_document``.
+        document_id = await knowledge.insert_document(
+            chunks,
+            document_metadata={"filename": filename},
+        )
+        print(
+            f"  indexed {filename!r} as document_id={document_id} "
+            f"({len(chunks)} chunk(s))",
+        )
+
+
+async def search(
+    knowledge: KnowledgeBase,
+    query: str,
+    top_k: int = 3,
+) -> None:
+    """Run a search via the :class:`KnowledgeBase` handle and print hits."""
+    results = await knowledge.search(queries=[query], top_k=top_k)
+
+    print(f"\nQuery: {query!r}")
+    if not results:
+        print("  (no hits)")
+        return
+    for rank, result in enumerate(results, start=1):
+        # Only text chunks are printable as-is.
+        snippet = (
+            result.chunk.content.text
+            if isinstance(result.chunk.content, TextBlock)
+            else "<non-text chunk>"
+        )
+        snippet = snippet.replace("\n", " ").strip()
+        if len(snippet) > 120:
+            snippet = snippet[:117] + "..."
+        print(
+            f"  [{rank}] score={result.score:.4f} "
+            f"source={result.chunk.source} "
+            f"document_id={result.document_id}\n"
+            f"      {snippet}",
+        )
+
+
+async def main() -> None:
+    """The main entry point of the example."""
+    api_key = os.environ.get("DASHSCOPE_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "Set DASHSCOPE_API_KEY before running this example.",
+        )
+
+    # The building blocks. All of these are also what the service-mode
+    # (``create_app``) wiring uses internally — the only difference is
+    # that here you drive them yourself.
+    embedding_model = DashScopeEmbeddingModel(
+        credential=DashScopeCredential(api_key=api_key),
+        model="text-embedding-v4",
+        dimensions=1024,
+    )
+    parser = TextParser()
+    chunker = ApproxTokenChunker(chunk_size=256, overlap=32)
+    store = QdrantStore(location=":memory:")
+
+    # ``QdrantStore`` is an async context manager — entering it opens
+    # the client connection; exiting closes it.
+    async with store:
+        # One :class:`KnowledgeBase` handle bundles (embedding, vector
+        # store, collection) together so the rest of this example
+        # never has to repeat the wiring.  The collection is created
+        # lazily on the first operation (`build_index`).
+        knowledge = KnowledgeBase(
+            name="demo-kb",
+            description="A toy corpus on cats and AgentScope.",
+            embedding_model=embedding_model,
+            vector_store=store,
+            collection=COLLECTION,
+        )
+
+        print("Indexing demo corpus ...")
+        await build_index(knowledge, parser, chunker)
+
+        # A couple of search queries that demonstrate scoring.
+        await search(knowledge, "When are cats most active?")
+        await search(
+            knowledge,
+            "What framework lets me build multi-agent apps?",
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/rag/integrate_with_agent.py

@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+"""Wire :class:`RAGMiddleware` into an :class:`Agent` — library mode.
+
+The middleware in :mod:`agentscope.middleware._rag` is the agent-side
+half of RAG: given one or more :class:`~agentscope.rag.KnowledgeBase`
+handles (each pairing an embedding model with a vector-store
+collection), the middleware drives search on each new user turn and
+feeds the matched chunks into the model context.
+
+This example reuses the indexing pipeline shown in ``index_and_search.py``
+(parse → chunk → embed → insert) and then attaches the same knowledge base
+to two agents — one per mode:
+
+- ``"static"``: on the first reasoning step of a reply, embed the
+  user's question, search, and inject the top hits as a one-shot
+  :class:`HintBlock` into the agent's context. The model sees the
+  matched snippets but never "decides" to search.
+- ``"agentic"`` (the default): expose a ``search_knowledge`` tool. The
+  model decides when (and what) to search, the same way it decides any
+  other tool call.
+
+Run with::
+
+    DASHSCOPE_API_KEY=sk-... python examples/rag/integrate_with_agent.py
+"""
+import asyncio
+import os
+
+from agentscope.agent import Agent
+from agentscope.credential import DashScopeCredential
+from agentscope.embedding import DashScopeEmbeddingModel
+from agentscope.message import UserMsg
+from agentscope.middleware import RAGMiddleware
+from agentscope.model import DashScopeChatModel
+from agentscope.rag import (
+    ApproxTokenChunker,
+    KnowledgeBase,
+    QdrantStore,
+    TextParser,
+)
+from agentscope.tool import Toolkit
+
+
+COLLECTION = "demo-kb"
+
+KNOWLEDGE: dict[str, bytes] = {
+    "company-policy.md": (
+        b"# Acme Remote Work Policy\n\n"
+        b"Employees may work remotely up to three days per week. "
+        b"Wednesdays are mandatory in-office days for the whole "
+        b"engineering org so cross-team syncs land on a predictable "
+        b"day.\n\n"
+        b"Equipment stipend: each new hire receives a USD 1,500 "
+        b"one-off stipend for a home-office setup. Receipts must be "
+        b"submitted within 90 days of the start date.\n"
+    ),
+    "release-notes.md": (
+        b"# AgentScope 3.0 release notes\n\n"
+        b"- New ``agentscope.rag`` module: pluggable parser, chunker, "
+        b"embedding, and vector-store backends.\n"
+        b"- ``RAGMiddleware`` ships in two modes -- ``static`` for "
+        b"automatic injection, ``agentic`` for tool-driven search.\n"
+        b"- Knowledge base service supports embedded and dedicated "
+        b"worker deployments through a single message-bus channel.\n"
+    ),
+}
+
+
+async def index_corpus(knowledge: KnowledgeBase) -> None:
+    """Index the demo corpus into the knowledge base.
+
+    Identical pipeline to ``examples/rag/index_and_search.py`` — extracted
+    as a helper here so the agent-side wiring stays the focus.  Each source
+    file becomes one logical document; ``KnowledgeBase.insert_document``
+    embeds and inserts every chunk in a single batch.
+    """
+    parser = TextParser()
+    chunker = ApproxTokenChunker(chunk_size=256, overlap=32)
+    for filename, file_bytes in KNOWLEDGE.items():
+        sections = await parser.parse(file=file_bytes, filename=filename)
+        chunks = await chunker.chunk(sections)
+        await knowledge.insert_document(
+            chunks,
+            document_metadata={"filename": filename},
+        )
+
+
+def build_agent(
+    name: str,
+    *,
+    chat_model: DashScopeChatModel,
+    rag_mw: RAGMiddleware,
+) -> Agent:
+    """Construct an :class:`Agent` with the RAG middleware attached.
+
+    The middleware is just one entry in the ``middlewares=`` list; it
+    composes with every other middleware (tool offload, mem0, ...) the
+    agent uses.
+    """
+    return Agent(
+        name=name,
+        system_prompt=(
+            "You are a concise assistant. Use matched context when "
+            "available; if you don't know, say so."
+        ),
+        model=chat_model,
+        toolkit=Toolkit(),
+        middlewares=[rag_mw],
+    )
+
+
+async def ask(agent: Agent, question: str) -> None:
+    """Run one reply and print the final assistant message."""
+    print(f"\n[{agent.name}] user: {question}")
+    reply = await agent.reply(UserMsg(name="user", content=question))
+    print(f"[{agent.name}] assistant: {reply.get_text_content()}")
+
+
+async def main() -> None:
+    """The main entry point of the example."""
+    api_key = os.environ.get("DASHSCOPE_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "Set DASHSCOPE_API_KEY before running this example.",
+        )
+
+    credential = DashScopeCredential(api_key=api_key)
+    chat_model = DashScopeChatModel(
+        credential=credential,
+        model="qwen-plus",
+        stream=False,
+    )
+    embedding_model = DashScopeEmbeddingModel(
+        credential=credential,
+        model="text-embedding-v4",
+        dimensions=1024,
+    )
+
+    store = QdrantStore(location=":memory:")
+    async with store:
+        # One :class:`KnowledgeBase` handle binds embedding + vector store +
+        # collection together.  ``insert_document`` / ``search`` /
+        # ``list_documents`` all go through it, and the backing
+        # collection is created lazily on first use.
+        knowledge = KnowledgeBase(
+            name="acme-handbook",
+            description="Acme HR policies and AgentScope 3.0 release notes.",
+            embedding_model=embedding_model,
+            vector_store=store,
+            collection=COLLECTION,
+        )
+
+        await index_corpus(knowledge)
+
+        # ---- Mode 1: static ----
+        # Search is automatic on the first reasoning step. The injected
+        # ``HintBlock`` is one-shot (removed after the model call) so it
+        # doesn't poison the next turn.
+        static_mw = RAGMiddleware(
+            knowledge_bases=[knowledge],
+            parameters=RAGMiddleware.Parameters(
+                mode="static",
+                top_k=3,
+                emit_hint_event=False,
+            ),
+        )
+        static_agent = build_agent(
+            "rag-static-agent",
+            chat_model=chat_model,
+            rag_mw=static_mw,
+        )
+        await ask(
+            static_agent,
+            "How many remote days per week does Acme allow?",
+        )
+
+        # ---- Mode 2: agentic ----
+        # The middleware exposes a ``search_knowledge`` tool instead of
+        # auto-injecting. The model decides when to call it; it may
+        # also pass ``knowledge_bases=[...]`` to scope the search when
+        # multiple knowledge bases are bound.
+        agentic_mw = RAGMiddleware(
+            knowledge_bases=[knowledge],
+            parameters=RAGMiddleware.Parameters(mode="agentic", top_k=3),
+        )
+        agentic_agent = build_agent(
+            "rag-agentic-agent",
+            chat_model=chat_model,
+            rag_mw=agentic_mw,
+        )
+        await ask(
+            agentic_agent,
+            "Summarise what's new in the AgentScope 3.0 release notes.",
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/web_ui/.gitignore

@@ -0,0 +1,42 @@
+/tmp
+/out-tsc
+
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+/.pnp
+.pnp.js
+
+.vscode/*
+
+# OS files
+.DS_Store
+
+dist
+build
+out
+.eslintcache
+*.log*
+
+.env
+.env.*
+__pycache__/
+*.db
+*.sqlite
+*.sqlite3
+
+.idea/
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Mintlify
+docs/.mintlify
+docs/node_modules
+docs/.next
+docs/.cache
+docs/api-reference/generated

examples/web_ui/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

examples/web_ui/.prettierignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules
+pnpm-lock.yaml
+
+# Build outputs
+dist
+build
+.next
+out
+
+# Cache
+.cache
+.turbo
+.vite
+
+# Logs
+*.log
+logs
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode
+.idea
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Generated files
+coverage
+*.min.js
+*.min.css
+
+# Claude
+.claude

examples/web_ui/.prettierrc

@@ -0,0 +1,10 @@
+{
+	"useTabs": true,
+	"tabWidth": 4,
+	"singleQuote": true,
+	"semi": true,
+	"trailingComma": "all",
+	"printWidth": 100,
+	"bracketSpacing": true,
+	"arrowParens": "always"
+}

examples/web_ui/backend/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "backend",
+	"version": "1.0.0",
+	"private": true,
+	"scripts": {
+		"dev": "nodemon --watch src --ext ts --exec ts-node src/index.ts",
+		"build": "tsc",
+		"start": "node dist/index.js"
+	},
+	"dependencies": {
+		"express": "^4.19.2",
+		"cors": "^2.8.5"
+	},
+	"devDependencies": {
+		"@types/express": "^4.17.21",
+		"@types/cors": "^2.8.17",
+		"@types/node": "^20.14.0",
+		"nodemon": "^3.1.4",
+		"ts-node": "^10.9.2",
+		"typescript": "^5.5.2"
+	}
+}

examples/web_ui/backend/src/index.ts

@@ -0,0 +1,16 @@
+import express from 'express';
+import cors from 'cors';
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+app.use(cors());
+app.use(express.json());
+
+app.get('/api/health', (_req, res) => {
+	res.json({ status: 'ok' });
+});
+
+app.listen(PORT, () => {
+	console.log(`Server running on http://localhost:${PORT}`);
+});

examples/web_ui/backend/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "commonjs",
+		"lib": ["ES2020"],
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true
+	},
+	"include": ["src"],
+	"exclude": ["node_modules", "dist"]
+}

examples/web_ui/frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+	globalIgnores(['dist']),
+	{
+		files: ['**/*.{ts,tsx}'],
+		extends: [
+			// Other configs...
+
+			// Remove tseslint.configs.recommended and replace with this
+			tseslint.configs.recommendedTypeChecked,
+			// Alternatively, use this for stricter rules
+			tseslint.configs.strictTypeChecked,
+			// Optionally, add this for stylistic rules
+			tseslint.configs.stylisticTypeChecked,
+
+			// Other configs...
+		],
+		languageOptions: {
+			parserOptions: {
+				project: ['./tsconfig.node.json', './tsconfig.app.json'],
+				tsconfigRootDir: import.meta.dirname,
+			},
+			// other options...
+		},
+	},
+]);
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x';
+import reactDom from 'eslint-plugin-react-dom';
+
+export default defineConfig([
+	globalIgnores(['dist']),
+	{
+		files: ['**/*.{ts,tsx}'],
+		extends: [
+			// Other configs...
+			// Enable lint rules for React
+			reactX.configs['recommended-typescript'],
+			// Enable lint rules for React DOM
+			reactDom.configs.recommended,
+		],
+		languageOptions: {
+			parserOptions: {
+				project: ['./tsconfig.node.json', './tsconfig.app.json'],
+				tsconfigRootDir: import.meta.dirname,
+			},
+			// other options...
+		},
+	},
+]);
+```

examples/web_ui/frontend/components.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "radix-nova",
+	"rsc": false,
+	"tsx": true,
+	"tailwind": {
+		"config": "",
+		"css": "src/index.css",
+		"baseColor": "neutral",
+		"cssVariables": true,
+		"prefix": ""
+	},
+	"iconLibrary": "lucide",
+	"rtl": false,
+	"aliases": {
+		"components": "@/components",
+		"utils": "@/lib/utils",
+		"ui": "@/components/ui",
+		"lib": "@/lib",
+		"hooks": "@/hooks"
+	},
+	"menuColor": "default",
+	"menuAccent": "subtle",
+	"registries": {}
+}

examples/web_ui/frontend/eslint.config.js

@@ -0,0 +1,53 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import importX from 'eslint-plugin-import-x';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+import { defineConfig, globalIgnores } from 'eslint/config';
+
+export default defineConfig([
+	globalIgnores(['dist']),
+	{
+		files: ['**/*.{ts,tsx}'],
+		plugins: {
+			'import-x': importX,
+		},
+		extends: [
+			js.configs.recommended,
+			tseslint.configs.recommended,
+			reactHooks.configs.flat.recommended,
+			reactRefresh.configs.vite,
+		],
+		languageOptions: {
+			globals: globals.browser,
+		},
+		rules: {
+			'import-x/order': [
+				'error',
+				{
+					groups: ['builtin', 'external', 'internal', 'index'],
+					'newlines-between': 'always',
+					alphabetize: {
+						order: 'asc',
+						caseInsensitive: true,
+					},
+				},
+			],
+			'react-hooks/set-state-in-effect': 'off',
+			'react-refresh/only-export-components': 'warn',
+			'@typescript-eslint/no-unused-expressions': 'off',
+			'@typescript-eslint/only-throw-error': 'off',
+			'preserve-caught-error': 'off',
+		},
+	},
+	{
+		files: ['**/components/ui/**/*.{ts,tsx}'],
+		rules: {
+			'@typescript-eslint/no-explicit-any': 'off',
+			'@typescript-eslint/no-unused-vars': 'off',
+			'react-refresh/only-export-components': 'off',
+			'import-x/order': 'off',
+		},
+	},
+]);

examples/web_ui/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<link rel="icon" type="image/svg+xml" href="/agentscope.svg" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>AgentScope</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

examples/web_ui/frontend/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "frontend",
+	"private": true,
+	"version": "0.0.0",
+	"type": "module",
+	"scripts": {
+		"dev": "vite",
+		"build": "tsc -b && vite build",
+		"lint": "eslint .",
+		"lint:fix": "eslint . --fix",
+		"preview": "vite preview"
+	},
+	"dependencies": {
+		"@agentscope-ai/agentscope": "^0.0.12",
+		"@fontsource-variable/geist": "^5.2.8",
+		"@tailwindcss/vite": "^4.3.0",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"cron-parser": "^5.5.0",
+		"date-fns": "^4.1.0",
+		"framer-motion": "^12.40.0",
+		"i18next": "^26.2.0",
+		"i18next-browser-languagedetector": "^8.2.1",
+		"lucide": "^1.3.0",
+		"lucide-react": "^1.16.0",
+		"mime-types": "^3.0.2",
+		"next-themes": "^0.4.6",
+		"onborda": "^1.2.5",
+		"radix-ui": "^1.4.3",
+		"react": "^19.2.6",
+		"react-day-picker": "^10.0.1",
+		"react-diff-view": "^3.3.3",
+		"react-dom": "^19.2.6",
+		"react-i18next": "^17.0.8",
+		"react-markdown": "^10.1.0",
+		"react-resizable-panels": "^4.11.2",
+		"react-router-dom": "^7.15.1",
+		"remark-gfm": "^4.0.1",
+		"shadcn": "^4.7.0",
+		"shadcn-prose": "^1.2.1",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.6.0",
+		"tailwindcss": "^4.3.0",
+		"tw-animate-css": "^1.4.0",
+		"unidiff": "^1.0.4",
+		"vaul": "^1.1.2"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@tailwindcss/typography": "^0.5.19",
+		"@types/mime-types": "^3.0.1",
+		"@types/node": "^24.12.3",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.1",
+		"eslint": "^10.3.0",
+		"eslint-plugin-import-x": "^4.16.2",
+		"eslint-plugin-react-hooks": "^7.1.1",
+		"eslint-plugin-react-refresh": "^0.5.2",
+		"globals": "^17.6.0",
+		"typescript": "~6.0.2",
+		"typescript-eslint": "^8.59.2",
+		"vite": "^8.0.12",
+		"vite-plugin-svgr": "^5.2.0"
+	}
+}

examples/web_ui/frontend/src/App.tsx

@@ -0,0 +1,84 @@
+import { Onborda, OnbordaProvider } from 'onborda';
+import { useMemo, useState } from 'react';
+import { createBrowserRouter, Navigate, RouterProvider, useNavigate } from 'react-router-dom';
+import { Toaster } from 'sonner';
+
+import { RouteError } from '@/components/error/RouteError';
+import { AppLayout } from '@/components/layout/AppLayout';
+import { buildChatTour } from '@/components/tour/chatTourSteps';
+import { TourCard } from '@/components/tour/TourCard';
+import { UploadProvider } from '@/context/UploadContext';
+import { useTranslation } from '@/i18n/useI18n';
+import { ChatPage } from '@/pages/chat';
+import { CredentialPage } from '@/pages/credential';
+import { KnowledgePage } from '@/pages/knowledge';
+import { SchedulePage } from '@/pages/schedule';
+import { SetupPage } from '@/pages/setup';
+
+function SetupPageRoute() {
+	const navigate = useNavigate();
+	return (
+		<>
+			<div className="h-screen">
+				<SetupPage onComplete={() => navigate('/')} />
+			</div>
+			<Toaster richColors position="top-right" />
+		</>
+	);
+}
+
+const router = createBrowserRouter([
+	{
+		element: <AppLayout />,
+		errorElement: <RouteError />,
+		children: [
+			{
+				// Content-level boundary: a crash in a page replaces only
+				// the Outlet area, so AppLayout (the icon rail / nav) stays
+				// usable. The parent route keeps its own errorElement as a
+				// last-resort catch-all for AppLayout/AppSidebar crashes.
+				errorElement: <RouteError />,
+				children: [
+					{ path: '/', element: <Navigate to="/chat" replace /> },
+					{
+						path: '/chat/:agentId?/:sessionId?/:memberId?',
+						element: <ChatPage />,
+					},
+					{ path: '/schedule', element: <SchedulePage /> },
+					{ path: '/credential', element: <CredentialPage /> },
+					{ path: '/knowledge', element: <KnowledgePage /> },
+					{ path: '/knowledge/:kbId', element: <KnowledgePage /> },
+				],
+			},
+		],
+	},
+	{ path: '/setup', element: <SetupPageRoute />, errorElement: <RouteError /> },
+]);
+
+function App() {
+	const { t } = useTranslation();
+	const [setupComplete, setSetupComplete] = useState(() => !!localStorage.getItem('server_url'));
+	const tours = useMemo(() => [buildChatTour(t)], [t]);
+
+	if (!setupComplete) {
+		return <SetupPage onComplete={() => setSetupComplete(true)} />;
+	}
+
+	return (
+		<OnbordaProvider>
+			<Onborda
+				steps={tours}
+				cardComponent={TourCard}
+				shadowOpacity="0.6"
+				cardTransition={{ type: 'spring', duration: 0.4 }}
+			>
+				<UploadProvider>
+					<RouterProvider router={router} />
+				</UploadProvider>
+				<Toaster richColors position="top-right" />
+			</Onborda>
+		</OnbordaProvider>
+	);
+}
+
+export default App;

examples/web_ui/frontend/src/api/agent.ts

@@ -0,0 +1,22 @@
+import { client } from './client';
+import type {
+	AgentListResponse,
+	AgentRecord,
+	AgentSchemaResponse,
+	CreateAgentRequest,
+	CreateAgentResponse,
+	UpdateAgentRequest,
+} from './types';
+
+export const agentApi = {
+	list: () => client.get<AgentListResponse>('/agent/'),
+
+	getSchema: () => client.get<AgentSchemaResponse>('/agent/schema'),
+
+	create: (body: CreateAgentRequest) => client.post<CreateAgentResponse>('/agent/', body),
+
+	update: (agentId: string, body: UpdateAgentRequest) =>
+		client.patch<AgentRecord>(`/agent/${agentId}`, body),
+
+	delete: (agentId: string) => client.delete(`/agent/${agentId}`),
+};

examples/web_ui/frontend/src/api/chat.ts

@@ -0,0 +1,25 @@
+import { client } from './client';
+import type { ChatRequest } from './types';
+
+/**
+ * Chat API — fire-and-forget trigger for chat runs.
+ *
+ * Events produced by the run are delivered via the session's SSE
+ * stream endpoint (``GET /sessions/{sid}/stream``), not in the
+ * response body of this POST.
+ */
+export const chatApi = {
+	/**
+	 * Trigger a chat run for the specified session.
+	 *
+	 * Accepts user messages, human-in-the-loop confirmation events,
+	 * or ``null`` (continue from current state). Returns immediately;
+	 * the caller should already be subscribed to the session's SSE
+	 * stream to receive the resulting events.
+	 *
+	 * @param body - The chat request payload.
+	 * @returns A confirmation object ``{ status, session_id }``.
+	 */
+	trigger: (body: ChatRequest) =>
+		client.post<{ status: string; session_id: string }>('/chat/', body),
+};

examples/web_ui/frontend/src/api/client.ts

@@ -0,0 +1,111 @@
+import { toast } from 'sonner';
+
+export const getBaseUrl = () => localStorage.getItem('server_url') ?? '';
+export const getUserId = () => localStorage.getItem('username') ?? '';
+
+/**
+ * Structured error thrown for non-2xx HTTP responses.
+ * `message` contains the human-readable detail extracted from the backend.
+ */
+export class ApiError extends Error {
+	readonly status: number;
+	readonly detail: string;
+
+	constructor(status: number, detail: string) {
+		super(detail);
+		this.name = 'ApiError';
+		this.status = status;
+		this.detail = detail;
+	}
+}
+
+interface RequestOptions {
+	method?: string;
+	body?: unknown;
+	params?: Record<string, string>;
+	/** When true, suppresses the automatic error toast. Useful when the caller shows its own inline error UI. */
+	silent?: boolean;
+}
+
+function buildHeaders(hasBody: boolean): Record<string, string> {
+	const headers: Record<string, string> = { 'X-User-ID': getUserId() };
+	if (hasBody) headers['Content-Type'] = 'application/json';
+	return headers;
+}
+
+/** Parse the response body and extract the `detail` field if the backend returned JSON. */
+async function extractErrorDetail(res: Response): Promise<string> {
+	const text = await res.text();
+	try {
+		const json = JSON.parse(text) as { detail?: unknown };
+		if (typeof json.detail === 'string') return json.detail;
+		if (json.detail !== undefined) return JSON.stringify(json.detail);
+	} catch {
+		// not JSON – fall through
+	}
+	return text || res.statusText;
+}
+
+async function request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+	const { method = 'GET', body, params, silent = false } = options;
+	const url = new URL(path, getBaseUrl());
+	if (params) {
+		Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+	}
+
+	const res = await fetch(url.toString(), {
+		method,
+		headers: buildHeaders(body !== undefined),
+		body: body ? JSON.stringify(body) : undefined,
+	});
+
+	if (!res.ok) {
+		const detail = await extractErrorDetail(res);
+		const error = new ApiError(res.status, detail);
+		if (!silent) toast.error(detail);
+		throw error;
+	}
+
+	if (res.status === 204) return undefined as T;
+	return res.json() as Promise<T>;
+}
+
+async function streamRequest(
+	path: string,
+	options: RequestOptions & { signal?: AbortSignal } = {},
+): Promise<Response> {
+	const { method = 'GET', body, params, signal, silent = false } = options;
+	const url = new URL(path, getBaseUrl());
+	if (params) {
+		Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+	}
+
+	const res = await fetch(url.toString(), {
+		method,
+		headers: buildHeaders(body !== undefined),
+		body: body ? JSON.stringify(body) : undefined,
+		signal,
+	});
+
+	if (!res.ok) {
+		const detail = await extractErrorDetail(res);
+		const error = new ApiError(res.status, detail);
+		if (!silent) toast.error(detail);
+		throw error;
+	}
+
+	return res;
+}
+
+export const client = {
+	get: <T>(path: string, params?: Record<string, string>) =>
+		request<T>(path, { method: 'GET', params }),
+	post: <T>(path: string, body?: unknown, params?: Record<string, string>) =>
+		request<T>(path, { method: 'POST', body, params }),
+	patch: <T>(path: string, body?: unknown, params?: Record<string, string>) =>
+		request<T>(path, { method: 'PATCH', body, params }),
+	delete: <T = void>(path: string, params?: Record<string, string>) =>
+		request<T>(path, { method: 'DELETE', params }),
+	stream: (path: string, options?: RequestOptions & { signal?: AbortSignal }) =>
+		streamRequest(path, options),
+};

examples/web_ui/frontend/src/api/credential.ts

@@ -0,0 +1,23 @@
+import { client } from './client';
+import type {
+	CreateCredentialRequest,
+	CreateCredentialResponse,
+	CredentialListResponse,
+	CredentialRecord,
+	CredentialSchemasResponse,
+	UpdateCredentialRequest,
+} from './types';
+
+export const credentialApi = {
+	list: () => client.get<CredentialListResponse>('/credential/'),
+
+	schemas: () => client.get<CredentialSchemasResponse>('/credential/schemas'),
+
+	create: (body: CreateCredentialRequest) =>
+		client.post<CreateCredentialResponse>('/credential/', body),
+
+	update: (credentialId: string, body: UpdateCredentialRequest) =>
+		client.patch<CredentialRecord>(`/credential/${credentialId}`, body),
+
+	delete: (credentialId: string) => client.delete(`/credential/${credentialId}`),
+};

examples/web_ui/frontend/src/api/index.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export { agentApi } from './agent';
+export { sessionApi } from './session';
+export { credentialApi } from './credential';
+export { chatApi } from './chat';
+export { workspaceApi } from './workspace';
+export { scheduleApi } from './schedule';
+export { modelApi, ttsModelApi } from './model';
+export { knowledgeBaseApi } from './knowledgeBase';

examples/web_ui/frontend/src/api/knowledgeBase.ts

@@ -0,0 +1,179 @@
+import { ApiError, client, getBaseUrl, getUserId } from './client';
+import type {
+	CreateKnowledgeBaseRequest,
+	CreateKnowledgeBaseResponse,
+	KbMiddlewareParametersSchemaResponse,
+	KnowledgeBaseView,
+	ListKbEmbeddingModelsResponse,
+	ListKnowledgeBasesResponse,
+	ListKnowledgeDocumentsResponse,
+	ListKnowledgeDocumentStatusResponse,
+	ListSupportedContentTypesResponse,
+	SearchKnowledgeBaseRequest,
+	SearchKnowledgeBaseResponse,
+	UpdateKnowledgeBaseRequest,
+	UploadKnowledgeDocumentResponse,
+} from './types';
+
+/**
+ * Callback invoked while bytes are pushed across the wire.
+ *
+ * - `loaded` — bytes already sent.
+ * - `total` — total bytes (may be 0 when the browser cannot compute it,
+ *   e.g. for chunked encodings).
+ */
+export interface UploadProgress {
+	loaded: number;
+	total: number;
+}
+
+export interface UploadDocumentOptions {
+	/** Fired with byte-level progress while the body is streamed. */
+	onProgress?: (progress: UploadProgress) => void;
+	/**
+	 * Caller-supplied abort signal. Aborting before the server has
+	 * responded rejects the returned promise with a `DOMException` of
+	 * `name === "AbortError"`; aborting after a response has come back
+	 * is a no-op.
+	 */
+	signal?: AbortSignal;
+}
+
+/**
+ * XHR-based upload — `fetch` does not surface byte-level send
+ * progress in any current browser, so multipart uploads that drive a
+ * progress UI have to fall back to XMLHttpRequest.
+ */
+function uploadDocumentXhr(
+	knowledgeBaseId: string,
+	file: File,
+	options: UploadDocumentOptions = {},
+): Promise<UploadKnowledgeDocumentResponse> {
+	const { onProgress, signal } = options;
+	const formData = new FormData();
+	formData.append('file', file);
+
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DOMException('Aborted', 'AbortError'));
+			return;
+		}
+
+		const xhr = new XMLHttpRequest();
+		const url = new URL(`/knowledge_bases/${knowledgeBaseId}/documents`, getBaseUrl());
+		xhr.open('POST', url.toString(), true);
+		xhr.setRequestHeader('X-User-ID', getUserId());
+
+		const onAbort = () => xhr.abort();
+		signal?.addEventListener('abort', onAbort, { once: true });
+
+		const cleanup = () => signal?.removeEventListener('abort', onAbort);
+
+		if (xhr.upload && onProgress) {
+			xhr.upload.onprogress = (e) => {
+				onProgress({
+					loaded: e.loaded,
+					total: e.lengthComputable ? e.total : 0,
+				});
+			};
+		}
+
+		xhr.onload = () => {
+			cleanup();
+			if (xhr.status >= 200 && xhr.status < 300) {
+				try {
+					resolve(JSON.parse(xhr.responseText) as UploadKnowledgeDocumentResponse);
+				} catch (e) {
+					reject(e);
+				}
+				return;
+			}
+			let detail = xhr.responseText || xhr.statusText;
+			try {
+				const json = JSON.parse(xhr.responseText) as {
+					detail?: unknown;
+				};
+				if (typeof json.detail === 'string') detail = json.detail;
+				else if (json.detail !== undefined) detail = JSON.stringify(json.detail);
+			} catch {
+				// keep raw text
+			}
+			reject(new ApiError(xhr.status, detail));
+		};
+		xhr.onerror = () => {
+			cleanup();
+			reject(new ApiError(0, 'Network error'));
+		};
+		xhr.onabort = () => {
+			cleanup();
+			reject(new DOMException('Aborted', 'AbortError'));
+		};
+
+		xhr.send(formData);
+	});
+}
+
+/**
+ * Client for the `/knowledge_bases` router.
+ */
+export const knowledgeBaseApi = {
+	list: () => client.get<ListKnowledgeBasesResponse>('/knowledge_bases/'),
+
+	listEmbeddingModels: () =>
+		client.get<ListKbEmbeddingModelsResponse>('/knowledge_bases/embedding_models'),
+
+	/** Fetch the JSON Schema describing the KB middleware's tunable params. */
+	middlewareParametersSchema: () =>
+		client.get<KbMiddlewareParametersSchemaResponse>(
+			'/knowledge_bases/middleware/parameters_schema',
+		),
+
+	/** List the union of media types + extensions every parser accepts. */
+	supportedContentTypes: () =>
+		client.get<ListSupportedContentTypesResponse>('/knowledge_bases/supported_content_types'),
+
+	create: (body: CreateKnowledgeBaseRequest) =>
+		client.post<CreateKnowledgeBaseResponse>('/knowledge_bases/', body),
+
+	update: (knowledgeBaseId: string, body: UpdateKnowledgeBaseRequest) =>
+		client.patch<KnowledgeBaseView>(`/knowledge_bases/${knowledgeBaseId}`, body),
+
+	delete: (knowledgeBaseId: string) => client.delete(`/knowledge_bases/${knowledgeBaseId}`),
+
+	/** List every document registered against a knowledge base. */
+	listDocuments: (knowledgeBaseId: string) =>
+		client.get<ListKnowledgeDocumentsResponse>(`/knowledge_bases/${knowledgeBaseId}/documents`),
+
+	/**
+	 * Batch-query lifecycle status for a list of documents.
+	 *
+	 * Missing ids are silently omitted by the server, so the response
+	 * may be shorter than the input. An empty `ids` short-circuits
+	 * locally — the backend treats an empty list as a 200 with
+	 * `items: []`, but skipping the round-trip is friendlier to the
+	 * polling loop.
+	 */
+	getDocumentStatus: (knowledgeBaseId: string, ids: string[]) => {
+		if (ids.length === 0) {
+			return Promise.resolve<ListKnowledgeDocumentStatusResponse>({
+				items: [],
+			});
+		}
+		return client.get<ListKnowledgeDocumentStatusResponse>(
+			`/knowledge_bases/${knowledgeBaseId}/documents/status`,
+			{ ids: ids.join(',') },
+		);
+	},
+
+	uploadDocument: (knowledgeBaseId: string, file: File, options?: UploadDocumentOptions) =>
+		uploadDocumentXhr(knowledgeBaseId, file, options),
+
+	deleteDocument: (knowledgeBaseId: string, documentId: string) =>
+		client.delete(`/knowledge_bases/${knowledgeBaseId}/documents/${documentId}`),
+
+	search: (knowledgeBaseId: string, body: SearchKnowledgeBaseRequest) =>
+		client.post<SearchKnowledgeBaseResponse>(
+			`/knowledge_bases/${knowledgeBaseId}/search`,
+			body,
+		),
+};

examples/web_ui/frontend/src/api/model.ts

@@ -0,0 +1,10 @@
+import { client } from './client';
+import type { ListModelResponse, ListTTSModelResponse } from './types';
+
+export const modelApi = {
+	list: (provider: string) => client.get<ListModelResponse>('/model/', { provider }),
+};
+
+export const ttsModelApi = {
+	list: (provider: string) => client.get<ListTTSModelResponse>('/tts-model/', { provider }),
+};