> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Release Notes

> Version history of AgentScope 2.x, including new features, changes, and bug fixes grouped by module for each release.

<Tip>
  For the full commit-level history and contributor list, see the [GitHub releases page](https://github.com/agentscope-ai/agentscope/releases).
</Tip>

## v2.0.2

*Released on 2026-06-16.*

### Added

**Agent Service & Team**

* **Custom subagent templates** can now be registered in the agent service, so a team leader can spawn workers from user-defined templates instead of being limited to the built-in ones. ([#1833](https://github.com/agentscope-ai/agentscope/pull/1833))
* **Custom agent classes** are now accepted by the agent service, allowing users to plug their own `Agent` subclasses into the FastAPI runtime. ([#1838](https://github.com/agentscope-ai/agentscope/pull/1838))

**Tool**

* **`Bash` tool now accepts a `cwd` argument**, letting agents scope shell execution to a specific working directory instead of always running from the workspace root. ([#1822](https://github.com/agentscope-ai/agentscope/pull/1822))

**Model & Multimodality**

* **Streaming audio + live captions** for DashScope/OpenAI omni-modal models — audio chunks and caption events are now emitted incrementally during a single reply. ([#1701](https://github.com/agentscope-ai/agentscope/pull/1701))

**TTS**

* **New `tts` module** with a DashScope backend and a streaming middleware that turns the agent's textual replies into spoken audio as tokens arrive. ([#1832](https://github.com/agentscope-ai/agentscope/pull/1832))

**WebUI**

* **Credential sidebar** is now grouped by provider, making it easier to find and manage keys across many vendors. ([#1829](https://github.com/agentscope-ai/agentscope/pull/1829))
* **CI for WebUI**: added format and build checks so frontend regressions are caught at PR time. ([#1821](https://github.com/agentscope-ai/agentscope/pull/1821))

### Changed

**Agent Service Infrastructure**

* **Embedding model layer refactored** for the agent service: the legacy single-file `_dashscope_embedding.py` / `_dashscope_multimodal_embedding.py` were replaced by a new `embedding/_dashscope/` package with per-model YAML cards (`text-embedding-v3/v4`, `qwen2.5-vl-embedding`, `qwen3-vl-embedding`, `multimodal-embedding-v1`, `tongyi-embedding-vision-flash/plus`), a new `EmbeddingModelCard` type, and a service-level `_embedding.py` endpoint. ([#1852](https://github.com/agentscope-ai/agentscope/pull/1852))
* **Background task manager refactored** to support multi-process and distributed deployment. The single-process scheduler was replaced by a message-bus based architecture (`message_bus/_base.py` + `_redis_message_bus.py`), and the cancel/wake-up dispatchers were rewritten to coordinate over the bus. ([#1849](https://github.com/agentscope-ai/agentscope/pull/1849))

### Fixed

**Model**

* **Tool-choice fallback in thinking mode**: when an OpenAI-compatible structured output call rejects a forced `tool_choice` because thinking mode is on, the call now transparently falls back to `auto` instead of erroring out. ([#1830](https://github.com/agentscope-ai/agentscope/pull/1830))
* **Qwen thinking toggle** is now forwarded correctly to DashScope. ([#1774](https://github.com/agentscope-ai/agentscope/pull/1774))
* **Ollama embedding client** is created per call instead of being cached, avoiding "event loop is closed" errors when the embedding client outlives its original loop. ([#1836](https://github.com/agentscope-ai/agentscope/pull/1836))

**Permission & Team**

* **Workspace MCP loader** now skips invalid MCP config entries with a warning instead of aborting initialization. ([#1819](https://github.com/agentscope-ai/agentscope/pull/1819))
* **Workspace root** is included in the permission context, so path-rule evaluation correctly resolves relative paths. ([#1823](https://github.com/agentscope-ai/agentscope/pull/1823))
* **Worker agents inherit leader permission rules**: `AgentCreate` is now state-injected, and a worker session is constructed by deep-copying the leader's working directories and allow/deny/ask rules. Previously workers received a blank `PermissionContext`, losing every user-confirmed directory and rule. ([#1815](https://github.com/agentscope-ai/agentscope/pull/1815))

**Tool**

* **Glob patterns** now accept Windows-style separators. ([#1809](https://github.com/agentscope-ai/agentscope/pull/1809))

**Storage & Message Bus**

* **Redis session IDs**: explicit session IDs are preserved instead of being overwritten with auto-generated ones. ([#1786](https://github.com/agentscope-ai/agentscope/pull/1786))
* **Redis message bus timeout** bug fixed so long-running tasks no longer drop their result messages. ([#1853](https://github.com/agentscope-ai/agentscope/pull/1853))

**WebUI**

* Fixed nested `<button>` HTML inside the sidebar group action. ([#1769](https://github.com/agentscope-ai/agentscope/pull/1769))
* Non-previewable file attachments now render properly, and media size is constrained to avoid blowing out the chat layout. ([#1768](https://github.com/agentscope-ai/agentscope/pull/1768))
* The chat session sidebar is now a mobile overlay drawer instead of taking up screen real estate on small viewports. ([#1772](https://github.com/agentscope-ai/agentscope/pull/1772))
* Added a route-level error boundary with a friendly error page. ([#1828](https://github.com/agentscope-ai/agentscope/pull/1828))
* Fixed a rendering bug on the chat page. ([#1867](https://github.com/agentscope-ai/agentscope/pull/1867))
* Corrected a typo in the Chinese setup hint copy. ([#1766](https://github.com/agentscope-ai/agentscope/pull/1766))

## v2.0.1

*Released on 2026-06-05.*

<Note>
  **Highlight**: the **Agent Team** feature is now supported on top of the agent service, making it easy to compose multiple subagents under a leader.
</Note>

### Added

**Agent Service & Team**

* **Agent Team** is built into the agent service: the service is refactored so multiple subagents can be created and coordinated by a leader agent. ([#1776](https://github.com/agentscope-ai/agentscope/pull/1776))
* **Pluggable tools and middlewares** can now be passed into the service at startup via dependency injection, instead of being baked into the default toolkit. ([#1709](https://github.com/agentscope-ai/agentscope/pull/1709))

**Permission**

* **Permission system overhaul**: the per-tool `_check_permission` hooks in `Edit` and `Write` were collapsed into the shared `_engine.py`, and `_decision.py` / `_types.py` were expanded with a richer rule model. The change is covered by a new 895-line `permission_mode_test.py` exercising the `default`, `explore`, `accept_edits`, and `ask` modes end-to-end. ([#1767](https://github.com/agentscope-ai/agentscope/pull/1767))

**Model**

* **Per-call `client_kwargs`** can now be forwarded to the underlying provider client, useful for proxies, custom transports, or per-call tracing. ([#1659](https://github.com/agentscope-ai/agentscope/pull/1659))
* **15 new YAML model cards** for mainstream providers: Anthropic (`claude-opus-4-5`, `claude-opus-4-6`, `claude-sonnet-4-5`), DashScope (`qwen-max`, `qwen-max-2025-01-25`, `qwen-turbo`, `qwen-long`), OpenAI Chat (`gpt-4o`, `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-4.1-nano`), OpenAI Response (`gpt-4.1`, `gpt-4.1-mini`), and xAI (`grok-3`, `grok-3-fast`). ([#1731](https://github.com/agentscope-ai/agentscope/pull/1731))

**RAG**

* **Basic `rag` module skeleton** introduced — base classes only; concrete retrievers will land in later releases. ([#1746](https://github.com/agentscope-ai/agentscope/pull/1746))

**Event**

* **`metadata` field on `EventBase`**, allowing producers to attach arbitrary structured data that downstream consumers (tracing, hooks, middlewares) can read. ([#1788](https://github.com/agentscope-ai/agentscope/pull/1788))

**WebUI**

* **Fallback model** can now be configured from the Web UI, so a session automatically rolls over when the primary model is unavailable. ([#1699](https://github.com/agentscope-ai/agentscope/pull/1699))

**Dependencies**

* **`ripgrep` is now an optional dependency** so deployments that don't need the built-in `grep` tool can stay leaner. ([#1740](https://github.com/agentscope-ai/agentscope/pull/1740))

### Changed

**Docs**

* README updated to cover the new agent service feature. ([#1789](https://github.com/agentscope-ai/agentscope/pull/1789))

### Fixed

**Formatter & Model**

* **Anthropic formatter** now drops thinking blocks that have no signature, preventing API rejections. ([#1668](https://github.com/agentscope-ai/agentscope/pull/1668))
* **Retry logic unified** across providers: a shared retry helper was added to anthropic / dashscope / deepseek / gemini / moonshot / ollama / openai\_chat / openai\_response / xai, so transient failures are now retried consistently everywhere. ([#1730](https://github.com/agentscope-ai/agentscope/pull/1730))
* **Ollama and Gemini** now honour an explicit `thinking_enable=False` instead of silently re-enabling thinking when the model supports it. ([#1784](https://github.com/agentscope-ai/agentscope/pull/1784))

**Tool**

* **`FunctionTool`** now accepts plain (non-`ToolResponse`) return values and wraps them automatically. ([#1703](https://github.com/agentscope-ai/agentscope/pull/1703))
* **Built-in `Read` tool** now invalidates its file cache when the underlying file is modified. ([#1735](https://github.com/agentscope-ai/agentscope/pull/1735))
* **Bash subprocess windows** are now hidden on Windows. ([#1717](https://github.com/agentscope-ai/agentscope/pull/1717))
* **Tool-group skills** are now correctly included when resolving the active toolset. ([#1732](https://github.com/agentscope-ai/agentscope/pull/1732))

**MCP**

* **MCPTool names** are now sanitized so providers (notably OpenAI) that reject characters like `:` or `/` accept them as tool names. ([#1787](https://github.com/agentscope-ai/agentscope/pull/1787))

**Workspace & Storage**

* **`LocalWorkspace`** adds locks around MCP and skill operations to prevent races during concurrent registration/teardown. ([#1710](https://github.com/agentscope-ai/agentscope/pull/1710))
* **Redis message lists** now have an expiry so per-session message logs are no longer kept forever. ([#1734](https://github.com/agentscope-ai/agentscope/pull/1734))

**WebUI**

* Frontend now builds cleanly with the current dependency set. ([#1708](https://github.com/agentscope-ai/agentscope/pull/1708))
* `Button` tooltip trigger uses `asChild` to avoid nested `<button>` elements. ([#1770](https://github.com/agentscope-ai/agentscope/pull/1770))
* Dialogs now ship with descriptions for screen reader accessibility. ([#1771](https://github.com/agentscope-ai/agentscope/pull/1771))
* Added missing files in the Web UI example. ([#1661](https://github.com/agentscope-ai/agentscope/pull/1661))

**Docs**

* DingTalk group QR code refreshed. ([#1662](https://github.com/agentscope-ai/agentscope/pull/1662))

## v2.0.0

*Released on 2026-05-25.*

<Note>
  **Highlight**: AgentScope 2.0 is released! This is a major architectural overhaul — message, tool, workspace, permission, middleware and service layers are all rebuilt from the ground up. See the [docs](https://docs.agentscope.io) for the new building blocks.
</Note>

### Added

**Agent Core**

* **Permission checking inside the `Agent` class**: large rewrite of `_agent.py` (+1534/-388) integrating the new permission engine, event types, exception hierarchy, and message blocks. The agent now consults the permission system on every tool call. ([#1518](https://github.com/agentscope-ai/agentscope/pull/1518))
* **Context compression** in the `Agent` class: a new `AgentConfig` exposes compression knobs, model providers gain compression entry points, and the new `offload/` and `storage/` base modules persist compressed history. Covered by a 564-line `context_compression_test.py`. ([#1544](https://github.com/agentscope-ai/agentscope/pull/1544))
* **Tool-result compaction** in the `Agent` class so large tool outputs are summarized before being re-fed to the model. ([#1585](https://github.com/agentscope-ai/agentscope/pull/1585))

**Permission System**

* **New `tool/_permission/` package** providing the basic permission classes, including a 1026-LOC `_engine.py`, a 589-LOC `_bash_parser.py` that statically analyses shell pipelines, plus `_context.py`, `_decision.py`, `_rule.py`, and `_types.py`. Backed by \~1.6k LOC of unit tests. ([#1486](https://github.com/agentscope-ai/agentscope/pull/1486))

**Tool**

* **Built-in tools rebuilt on `ToolBase`**: brand-new `_bash`, `_edit`, `_glob`, `_grep`, `_read`, and `_write` implementations, plus `_meta` and `_constants`, all sharing the new tool base class. ([#1502](https://github.com/agentscope-ai/agentscope/pull/1502))
* **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/versions/2.0.4dev/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549))
* **Tool + Workspace integration**: the toolkit and the workspace module are now wired into the `Agent` class so file/shell tools execute inside the agent's workspace. ([#1642](https://github.com/agentscope-ai/agentscope/pull/1642))

**Workspace**

* **New `workspace/` module** built for 2.0, with a `_base.py` interface and a 789-LOC `_local_workspace.py` implementation. The old `offload/_base.py` was removed in the process. ([#1586](https://github.com/agentscope-ai/agentscope/pull/1586))

**Service**

* **FastAPI-based agent service** introduced as the canonical way to expose agents over HTTP. ([#1568](https://github.com/agentscope-ai/agentscope/pull/1568))

**Middleware & Tracing**

* **2.0 middleware system** added to the `Agent` class: a 179-LOC `middleware/_base.py`, a new `AgentConfig` slot for middleware registration, and a 752-LOC test suite. ([#1565](https://github.com/agentscope-ai/agentscope/pull/1565))
* **Tracing as a middleware**: the previously bolt-on tracing logic is now packaged as a middleware under `middleware/_tracing/` (extractor + converter + setup + 846-LOC test suite). ([#1633](https://github.com/agentscope-ai/agentscope/pull/1633))

**Model**

* **`cache_creation_input_tokens` and `cache_input_tokens`** added to `ChatUsage` for prompt-cache aware billing/telemetry. ([#1602](https://github.com/agentscope-ai/agentscope/pull/1602))
* **Uniform thinking tag**: standardized handling of `<thinking>` tags across DeepSeek, Moonshot, OpenAI Chat, OpenAI Response and xAI so downstream code no longer needs per-provider branching. ([#1622](https://github.com/agentscope-ai/agentscope/pull/1622))
* **Audio output for OpenAI** models is now handled end-to-end. ([#1623](https://github.com/agentscope-ai/agentscope/pull/1623))
* **DashScope structured output** fixed and accompanied by usage examples. ([#1651](https://github.com/agentscope-ai/agentscope/pull/1651))

**Message & Event**

* **`Msg` type rules and constraints** formalized, with a comprehensive test suite that pins down what content blocks are allowed where. ([#1454](https://github.com/agentscope-ai/agentscope/pull/1454))
* **`usage` field on `Msg`** exposes token usage at the message level. ([#1639](https://github.com/agentscope-ai/agentscope/pull/1639))

**Scripts**

* **Model-call helper scripts** added under `scripts/model_examples/` for quick provider sanity checks. ([#1604](https://github.com/agentscope-ai/agentscope/pull/1604))

### Changed

**Message & Event**

* **Core building blocks simplified** and the `Msg` class restructured. The legacy `a2a/` package (`a2a_base`, `file_resolver`, `nacos_resolver`, `well_known_resolver`) and `formatter/_a2a_formatter.py` were removed; a unified `event/` package (`_event.py`, 421 LOC) was introduced. ([#1440](https://github.com/agentscope-ai/agentscope/pull/1440))

**Tool**

* **Tool module refactored** with a new base class and toolkit logic; the legacy MCP `client_base` was dropped and tutorials updated to match. ([#1493](https://github.com/agentscope-ai/agentscope/pull/1493))
* **Skill loader refactor**: a new `tool/_skill/` package (`_base.py` + 171-LOC `_local_loader.py`) replaces the inline skill logic in the toolkit, and a built-in `_skill.py` tool exposes skills to agents. ([#1513](https://github.com/agentscope-ai/agentscope/pull/1513))
* **`tool_choice` argument** refactored to expose modes (`auto`, `none`, `required`, etc.) as typed objects in `tool/_types.py`, enabling advanced prompt cache in the OpenAI Response API. Updated across every provider model. ([#1524](https://github.com/agentscope-ai/agentscope/pull/1524))

**Model & Formatter**

* **Chat model implementation refactored**: a new `credential/` package (`_base`, `_anthropic`, `_dashscope`, `_deepseek`, `_gemini`, `_kimi`, `_ollama`, `_openai`, `_xai`) decouples API keys/auth from the chat model classes, and every provider's formatter was rewritten on top of it. ([#1564](https://github.com/agentscope-ai/agentscope/pull/1564))
* **DashScope made OpenAI-compatible**: the DashScope model now reuses the OpenAI chat client path instead of carrying its own response parser. ([#1617](https://github.com/agentscope-ai/agentscope/pull/1617))
* **`kimi` renamed to `moonshot`** to match the provider's branding. ([#1609](https://github.com/agentscope-ai/agentscope/pull/1609))

**MCP**

* **Unified `MCPClient` class** (`_mcp_client.py`, 347 LOC) replaces the previous family of stateful, stateless, stdio, SSE, and streamable-HTTP clients. A small `_config.py` holds connection configs. ([#1572](https://github.com/agentscope-ai/agentscope/pull/1572))
* **MCP tools are renamed** when registered into the toolkit, ensuring no collisions across servers. ([#1552](https://github.com/agentscope-ai/agentscope/pull/1552))
* **MCP unit tests** refactored for the new version. ([#1505](https://github.com/agentscope-ai/agentscope/pull/1505))

**Tracing**

* **Tracing module moved under `middleware/_tracing/`**: the single 360-line `_extractor.py` was split into `_trace.py`, `_converter.py`, and a slimmer `_extractor.py`, and registration was simplified. ([#1579](https://github.com/agentscope-ai/agentscope/pull/1579))

**Workspace**

* **e2b and Docker workspaces** added alongside the local workspace, each with its own manager. The release also ships a full WebUI scaffold under `examples/web_ui/`. ([#1650](https://github.com/agentscope-ai/agentscope/pull/1650))

**Project**

* **Temporary deprecations**: `evaluate`, `module`, `rag`, `tts`, and `realtime` modules are removed pending refactor; the corresponding examples (a2a/a2ui agents, etc.) are deleted from the tree. ([#1438](https://github.com/agentscope-ai/agentscope/pull/1438))

**Docs**

* README and tutorials updated for the 2.0 release. ([#1657](https://github.com/agentscope-ai/agentscope/pull/1657))

### Fixed

**Model**

* **DashScope `KeyError`** when the response payload omits an expected field. ([#1615](https://github.com/agentscope-ai/agentscope/pull/1615))
* **`_format_tools`** refined for the OpenAI response model. ([#1635](https://github.com/agentscope-ai/agentscope/pull/1635))

**Formatter**

* **Formatters and unit tests** refined across providers. ([#1621](https://github.com/agentscope-ai/agentscope/pull/1621))
* **Moonshot**: remote image URLs are now downloaded and re-uploaded as base64 since the API does not accept URL references. ([#1653](https://github.com/agentscope-ai/agentscope/pull/1653))

**MCP**

* **`$defs` preserved** in MCPTool input schemas and `title` keys stripped recursively, fixing schema validation with strict LLM providers. ([#1595](https://github.com/agentscope-ai/agentscope/pull/1595))

**Tool**

* **`.env` bypass closed**: `Write`, `Edit`, and `Bash` no longer let agents read or modify `.env` (or other dangerous paths) through canonical-path tricks; the dangerous-path API was refined accordingly. ([#1656](https://github.com/agentscope-ai/agentscope/pull/1656))

**Scripts**

* Helper scripts now assign a list of `TextBlock` to `content` instead of a raw string. ([#1629](https://github.com/agentscope-ai/agentscope/pull/1629))