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

# 更新日志

> AgentScope 版本改动和更新日志。

<Tip>
  如需查看完整的提交历史与贡献者名单，请访问 [GitHub Releases 页面](https://github.com/agentscope-ai/agentscope/releases)。
</Tip>

## v2.0.2

*发布于 2026-06-16。*

### 新增

**Agent 服务与 Team**

* **自定义子智能体模板**：现在可以在 Agent 服务中注册自定义的子智能体模板，团队 Leader 可以基于用户自定义的模板创建 Worker，不再局限于内置模板。([#1833](https://github.com/agentscope-ai/agentscope/pull/1833))
* **自定义 Agent 类**：Agent 服务现在支持注册用户自定义的 `Agent` 子类，由 FastAPI 运行时实例化。([#1838](https://github.com/agentscope-ai/agentscope/pull/1838))

**Tool**

* **`Bash` 工具新增 `cwd` 参数**：智能体现在可以将 Shell 命令限定在指定的工作目录中执行，而不必每次都从工作区根目录运行。([#1822](https://github.com/agentscope-ai/agentscope/pull/1822))

**Model 与多模态**

* **流式音频 + 实时字幕**：DashScope/OpenAI 全模态模型现在能够在单次回复内增量地输出音频块和字幕事件。([#1701](https://github.com/agentscope-ai/agentscope/pull/1701))

**TTS**

* **全新 `tts` 模块**：内置 DashScope 后端与流式中间件，能够在 Token 到达时实时将智能体的文本回复转换为语音输出。([#1832](https://github.com/agentscope-ai/agentscope/pull/1832))

**WebUI**

* **凭据侧边栏**：现在按 Provider 分组展示凭据，便于在多家厂商之间查找和管理 API Key。([#1829](https://github.com/agentscope-ai/agentscope/pull/1829))
* **WebUI 的 CI**：新增了格式检查和构建检查，前端回归在 PR 阶段即可被发现。([#1821](https://github.com/agentscope-ai/agentscope/pull/1821))

### 变更

**Agent 服务基础设施**

* **Embedding 模型层重构**：原先单文件实现的 `_dashscope_embedding.py` / `_dashscope_multimodal_embedding.py` 被替换为新的 `embedding/_dashscope/` 包，每个模型都对应一份 YAML 模型卡（`text-embedding-v3/v4`、`qwen2.5-vl-embedding`、`qwen3-vl-embedding`、`multimodal-embedding-v1`、`tongyi-embedding-vision-flash/plus`），并新增 `EmbeddingModelCard` 类型以及服务层 `_embedding.py` 端点。([#1852](https://github.com/agentscope-ai/agentscope/pull/1852))
* **后台任务管理器重构**：原本基于单进程的调度器被替换为基于消息总线的架构（`message_bus/_base.py` + `_redis_message_bus.py`），并重写了 cancel/wake-up 调度器以便通过消息总线协同，支持多进程与分布式部署。([#1849](https://github.com/agentscope-ai/agentscope/pull/1849))

### 修复

**Model**

* **思考模式下的 tool\_choice 回退**：当 OpenAI 兼容的结构化输出调用因开启思考模式而拒绝强制 `tool_choice` 时，现在会自动回退到 `auto` 而不是直接报错。([#1830](https://github.com/agentscope-ai/agentscope/pull/1830))
* **Qwen 思考开关**：正确地将 thinking 开关参数透传给 DashScope。([#1774](https://github.com/agentscope-ai/agentscope/pull/1774))
* **Ollama Embedding 客户端**：改为每次调用都新建客户端，避免 Embedding 客户端跨事件循环复用时出现 "event loop is closed" 错误。([#1836](https://github.com/agentscope-ai/agentscope/pull/1836))

**Permission 与 Team**

* **Workspace MCP 加载器**：遇到非法的 MCP 配置项时会跳过并打印告警，而不是直接中断初始化。([#1819](https://github.com/agentscope-ai/agentscope/pull/1819))
* **Workspace 根路径**：被纳入到 Permission Context 中，路径规则评估时能够正确解析相对路径。([#1823](https://github.com/agentscope-ai/agentscope/pull/1823))
* **Worker Agent 继承 Leader 的权限规则**：`AgentCreate` 现在改为 state-injected，Worker 会话通过深拷贝 Leader 的工作目录以及 allow/deny/ask 规则来构建。此前 Worker 总是拿到一个空的 `PermissionContext`，导致所有用户已确认过的目录和规则都丢失。([#1815](https://github.com/agentscope-ai/agentscope/pull/1815))

**Tool**

* **Glob 模式**：现在能够正确识别 Windows 风格的路径分隔符。([#1809](https://github.com/agentscope-ai/agentscope/pull/1809))

**Storage 与 Message Bus**

* **Redis 会话 ID**：显式传入的 Session ID 不再被自动生成的 ID 覆盖。([#1786](https://github.com/agentscope-ai/agentscope/pull/1786))
* **Redis Message Bus 超时 Bug**：修复后长耗时任务不会再丢失结果消息。([#1853](https://github.com/agentscope-ai/agentscope/pull/1853))

**WebUI**

* 修复了侧边栏 group action 中 `<button>` 嵌套的 HTML 结构问题。([#1769](https://github.com/agentscope-ai/agentscope/pull/1769))
* 不可预览的文件附件现在能够正常渲染，并对媒体尺寸做了约束，避免撑破聊天布局。([#1768](https://github.com/agentscope-ai/agentscope/pull/1768))
* 聊天会话侧边栏在移动端改为浮层抽屉，避免在小屏上抢占空间。([#1772](https://github.com/agentscope-ai/agentscope/pull/1772))
* 新增了路由级别的错误边界，配套友好的错误页面。([#1828](https://github.com/agentscope-ai/agentscope/pull/1828))
* 修复了聊天页面的一个渲染 Bug。([#1867](https://github.com/agentscope-ai/agentscope/pull/1867))
* 修正了中文版引导提示文案中的一处错别字。([#1766](https://github.com/agentscope-ai/agentscope/pull/1766))

## v2.0.1

*发布于 2026-06-05。*

<Note>
  **版本亮点**：**Agent Team** 特性现已在 Agent 服务中支持，可以方便地在一个 Leader 下组合多个子 Agent。
</Note>

### 新增

**Agent 服务与 Team**

* **Agent Team** 内置于 Agent 服务中：重构后的服务允许由 Leader Agent 创建并协同多个子 Agent。([#1776](https://github.com/agentscope-ai/agentscope/pull/1776))
* **可插拔的工具与中间件**：现在可以在服务启动时通过依赖注入向其传入额外的工具和中间件，而不必将其硬编码在默认工具包中。([#1709](https://github.com/agentscope-ai/agentscope/pull/1709))

**Permission**

* **权限系统的整体优化**：将 `Edit` 与 `Write` 各自的 `_check_permission` 钩子收敛到共享的 `_engine.py` 中，并扩展了 `_decision.py` / `_types.py` 中的规则模型。改动配套新增了 895 行的 `permission_mode_test.py`，端到端地覆盖 `default`、`explore`、`accept_edits`、`ask` 四种模式。([#1767](https://github.com/agentscope-ai/agentscope/pull/1767))

**Model**

* **逐次调用的 `client_kwargs`**：可以将额外的客户端参数透传给底层 Provider Client，便于配合代理、自定义 Transport 或单次调用级别的 Tracing 使用。([#1659](https://github.com/agentscope-ai/agentscope/pull/1659))
* **15 份主流模型的 YAML 模型卡**：覆盖 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`）以及 xAI（`grok-3`、`grok-3-fast`）。([#1731](https://github.com/agentscope-ai/agentscope/pull/1731))

**RAG**

* **`rag` 模块基础类骨架**：仅包含基类，具体的 Retriever 实现将在后续版本中陆续提供。([#1746](https://github.com/agentscope-ai/agentscope/pull/1746))

**Event**

* **`EventBase` 新增 `metadata` 字段**：允许事件生产者附带任意结构化数据，下游的 Tracing、Hook、Middleware 等可以直接读取。([#1788](https://github.com/agentscope-ai/agentscope/pull/1788))

**WebUI**

* **Fallback 模型**：现在可以在 Web UI 中配置 Fallback 模型，当主模型不可用时会话会自动切换。([#1699](https://github.com/agentscope-ai/agentscope/pull/1699))

**Dependencies**

* **`ripgrep` 改为可选依赖**：不需要内置 `grep` 工具的部署可以保持更精简的依赖。([#1740](https://github.com/agentscope-ai/agentscope/pull/1740))

### 变更

**Docs**

* 更新了 README，介绍新的 Agent 服务能力。([#1789](https://github.com/agentscope-ai/agentscope/pull/1789))

### 修复

**Formatter 与 Model**

* **Anthropic Formatter**：现在会丢弃没有 signature 的 thinking block，避免 API 调用失败。([#1668](https://github.com/agentscope-ai/agentscope/pull/1668))
* **统一的重试逻辑**：anthropic / dashscope / deepseek / gemini / moonshot / ollama / openai\_chat / openai\_response / xai 现在共享同一份重试辅助逻辑，瞬时失败的处理在各家 Provider 之间保持一致。([#1730](https://github.com/agentscope-ai/agentscope/pull/1730))
* **Ollama 与 Gemini**：会真正遵循显式传入的 `thinking_enable=False`，不再因为模型本身支持思考就强行开启。([#1784](https://github.com/agentscope-ai/agentscope/pull/1784))

**Tool**

* **`FunctionTool`**：现在接受普通返回值（而非 `ToolResponse`），会自动包装。([#1703](https://github.com/agentscope-ai/agentscope/pull/1703))
* **内置 `Read` 工具**：在底层文件被修改时会失效原有的文件缓存。([#1735](https://github.com/agentscope-ai/agentscope/pull/1735))
* **Bash 子进程窗口**：在 Windows 平台上现在会被隐藏。([#1717](https://github.com/agentscope-ai/agentscope/pull/1717))
* **Tool Group 的 Skills**：在解析当前可用工具集时会被正确地包含进去。([#1732](https://github.com/agentscope-ai/agentscope/pull/1732))

**MCP**

* **MCPTool 名称**：会被规范化处理，避免出现 `:`、`/` 等字符时被部分 Provider（尤其是 OpenAI）拒绝。([#1787](https://github.com/agentscope-ai/agentscope/pull/1787))

**Workspace 与 Storage**

* **`LocalWorkspace`**：为 MCP 与 Skill 的操作加锁，避免并发注册/销毁时的竞态。([#1710](https://github.com/agentscope-ai/agentscope/pull/1710))
* **Redis 消息列表**：现在会设置过期时间，会话级的消息日志不再无限堆积。([#1734](https://github.com/agentscope-ai/agentscope/pull/1734))

**WebUI**

* 在当前依赖下前端能够正常构建。([#1708](https://github.com/agentscope-ai/agentscope/pull/1708))
* `Button` 的 tooltip 触发器使用 `asChild`，避免出现嵌套的 `<button>`。([#1770](https://github.com/agentscope-ai/agentscope/pull/1770))
* 对话框新增了用于读屏软件的 description，提升无障碍体验。([#1771](https://github.com/agentscope-ai/agentscope/pull/1771))
* 补全了 Web UI 示例中缺失的文件。([#1661](https://github.com/agentscope-ai/agentscope/pull/1661))

**Docs**

* 更新了 README 中的钉钉群二维码。([#1662](https://github.com/agentscope-ai/agentscope/pull/1662))

## v2.0.0

*发布于 2026-05-25。*

<Note>
  **版本亮点**：AgentScope 2.0 正式发布！本次发布是一次大规模架构重构 —— Message、Tool、Workspace、Permission、Middleware 与 Service 等核心层全部重写。请参考 [新文档](https://docs.agentscope.io) 了解全新的构建块。
</Note>

### 新增

**Agent 核心**

* **`Agent` 类中内置权限检查**：`_agent.py` 进行了大规模重写（+1534/-388），集成了新的权限引擎、事件类型、异常体系以及消息块。Agent 在每次工具调用前都会咨询权限系统。([#1518](https://github.com/agentscope-ai/agentscope/pull/1518))
* **`Agent` 类支持上下文压缩**：新的 `AgentConfig` 暴露压缩相关配置，各 Provider 提供压缩入口，新增的 `offload/` 与 `storage/` 基础模块用于持久化压缩后的历史。配套 564 行的 `context_compression_test.py`。([#1544](https://github.com/agentscope-ai/agentscope/pull/1544))
* **工具结果压缩**：`Agent` 类支持对大体积的工具输出在回灌给模型前进行摘要压缩。([#1585](https://github.com/agentscope-ai/agentscope/pull/1585))

**权限系统**

* **全新 `tool/_permission/` 包**：提供完整的权限基础类，包含 1026 行的 `_engine.py`、589 行用于静态分析 Shell 管道的 `_bash_parser.py`，以及 `_context.py`、`_decision.py`、`_rule.py`、`_types.py`，并搭配约 1.6k 行的单元测试。([#1486](https://github.com/agentscope-ai/agentscope/pull/1486))

**Tool**

* **基于 `ToolBase` 重建内置工具**：全新的 `_bash`、`_edit`、`_glob`、`_grep`、`_read`、`_write` 实现，以及共享的 `_meta` 与 `_constants`，全部基于新的工具基类。([#1502](https://github.com/agentscope-ai/agentscope/pull/1502))
* **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/versions/2.0.4dev/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549))
* **Tool 与 Workspace 集成**：工具包与 Workspace 模块被打通进 `Agent` 类，文件/Shell 工具现在统一在 Agent 的 Workspace 中执行。([#1642](https://github.com/agentscope-ai/agentscope/pull/1642))

**Workspace**

* **全新 `workspace/` 模块**：包含 `_base.py` 接口与 789 行的 `_local_workspace.py` 实现，旧的 `offload/_base.py` 同时被移除。([#1586](https://github.com/agentscope-ai/agentscope/pull/1586))

**Service**

* **基于 FastAPI 的 Agent 服务**：作为通过 HTTP 暴露 Agent 的标准方式被正式引入。([#1568](https://github.com/agentscope-ai/agentscope/pull/1568))

**Middleware 与 Tracing**

* **2.0 中间件机制**：在 `Agent` 类中引入新的中间件机制，包含 179 行的 `middleware/_base.py`、`AgentConfig` 中的中间件注册槽位，以及 752 行的测试用例。([#1565](https://github.com/agentscope-ai/agentscope/pull/1565))
* **Tracing 作为中间件**：原本作为外挂逻辑存在的 Tracing 现在被打包成一个中间件，位于 `middleware/_tracing/`，包含 extractor + converter + setup 以及 846 行的测试。([#1633](https://github.com/agentscope-ai/agentscope/pull/1633))

**Model**

* **`ChatUsage` 新增 `cache_creation_input_tokens` 与 `cache_input_tokens`** 字段，用于支撑感知 Prompt Cache 的计费与可观测性。([#1602](https://github.com/agentscope-ai/agentscope/pull/1602))
* **统一的 thinking tag 处理**：在 DeepSeek、Moonshot、OpenAI Chat、OpenAI Response 与 xAI 之间统一了 `<thinking>` 标签的处理逻辑，下游代码不再需要按 Provider 分支。([#1622](https://github.com/agentscope-ai/agentscope/pull/1622))
* **OpenAI 音频输出**：端到端支持 OpenAI 模型的音频输出。([#1623](https://github.com/agentscope-ai/agentscope/pull/1623))
* **DashScope 结构化输出**：修复后并配套提供使用示例。([#1651](https://github.com/agentscope-ai/agentscope/pull/1651))

**Message 与 Event**

* **正式定义 `Msg` 的类型规则与约束**：通过完整的测试套件明确不同位置允许出现的内容块类型。([#1454](https://github.com/agentscope-ai/agentscope/pull/1454))
* **`Msg` 新增 `usage` 字段**：在消息粒度暴露 Token 使用量。([#1639](https://github.com/agentscope-ai/agentscope/pull/1639))

**Scripts**

* **模型调用辅助脚本**：在 `scripts/model_examples/` 下新增了一批脚本，用于快速验证各家 Provider。([#1604](https://github.com/agentscope-ai/agentscope/pull/1604))

### 变更

**Message 与 Event**

* **核心构建块简化、`Msg` 结构重组**：旧的 `a2a/` 包（`a2a_base`、`file_resolver`、`nacos_resolver`、`well_known_resolver`）以及 `formatter/_a2a_formatter.py` 被移除；新增了统一的 `event/` 包（`_event.py`，421 行）。([#1440](https://github.com/agentscope-ai/agentscope/pull/1440))

**Tool**

* **Tool 模块重构**：提供新的基类与工具包逻辑，移除了遗留的 MCP `client_base`，相关教程也同步更新。([#1493](https://github.com/agentscope-ai/agentscope/pull/1493))
* **Skill Loader 重构**：新增 `tool/_skill/` 包（`_base.py` + 171 行的 `_local_loader.py`），替换原先内联在 Toolkit 中的 Skill 逻辑；同时新增内置 `_skill.py` 工具，将 Skill 暴露给 Agent。([#1513](https://github.com/agentscope-ai/agentscope/pull/1513))
* **`tool_choice` 参数重构**：将各种模式（`auto`、`none`、`required` 等）改为 `tool/_types.py` 中的类型化对象，从而能够支持 OpenAI Response API 的高级 Prompt Cache，所有 Provider 的实现同步更新。([#1524](https://github.com/agentscope-ai/agentscope/pull/1524))

**Model 与 Formatter**

* **Chat 模型实现重构**：新增 `credential/` 包（`_base`、`_anthropic`、`_dashscope`、`_deepseek`、`_gemini`、`_kimi`、`_ollama`、`_openai`、`_xai`），将 API Key/鉴权从 Chat 模型类中解耦，所有 Provider 的 Formatter 也在其基础上重写。([#1564](https://github.com/agentscope-ai/agentscope/pull/1564))
* **DashScope 兼容 OpenAI**：DashScope 模型现在复用 OpenAI Chat 客户端的调用路径，不再维护单独的响应解析。([#1617](https://github.com/agentscope-ai/agentscope/pull/1617))
* **`kimi` 重命名为 `moonshot`**：与该 Provider 的官方品牌保持一致。([#1609](https://github.com/agentscope-ai/agentscope/pull/1609))

**MCP**

* **统一的 `MCPClient` 类**：`_mcp_client.py`（347 行）替代了原先一系列 stateful、stateless、stdio、SSE 与 streamable-HTTP 的客户端，连接配置统一收敛到 `_config.py` 中。([#1572](https://github.com/agentscope-ai/agentscope/pull/1572))
* **MCP 工具注册时会被重命名**：避免不同 MCP Server 之间的工具名冲突。([#1552](https://github.com/agentscope-ai/agentscope/pull/1552))
* **MCP 单元测试**：按新版 API 进行了重构。([#1505](https://github.com/agentscope-ai/agentscope/pull/1505))

**Tracing**

* **Tracing 模块迁移至 `middleware/_tracing/`**：原先约 360 行的 `_extractor.py` 被拆分为 `_trace.py`、`_converter.py` 以及更精简的 `_extractor.py`，注册流程也得到简化。([#1579](https://github.com/agentscope-ai/agentscope/pull/1579))

**Workspace**

* **新增 e2b 与 Docker Workspace**：与本地 Workspace 并列提供，各自配套 Manager。本次发布同时在 `examples/web_ui/` 下提供了完整的 WebUI 脚手架。([#1650](https://github.com/agentscope-ai/agentscope/pull/1650))

**项目层面**

* **临时弃用**：`evaluate`、`module`、`rag`、`tts`、`realtime` 等模块在重构期间被移除，对应的示例（a2a/a2ui 智能体等）也从代码树中删除。([#1438](https://github.com/agentscope-ai/agentscope/pull/1438))

**Docs**

* 为 2.0 版本更新了 README 与教程。([#1657](https://github.com/agentscope-ai/agentscope/pull/1657))

### 修复

**Model**

* **DashScope `KeyError`**：当响应体缺失预期字段时不再抛出 `KeyError`。([#1615](https://github.com/agentscope-ai/agentscope/pull/1615))
* **`_format_tools`**：针对 OpenAI Response 模型做了进一步打磨。([#1635](https://github.com/agentscope-ai/agentscope/pull/1635))

**Formatter**

* **各 Provider 的 Formatter 与单元测试**：进行了系统化的打磨。([#1621](https://github.com/agentscope-ai/agentscope/pull/1621))
* **Moonshot**：远端图片 URL 现在会被下载后以 base64 形式上传，因为该 API 不支持直接传 URL。([#1653](https://github.com/agentscope-ai/agentscope/pull/1653))

**MCP**

* **MCPTool 输入 Schema 保留 `$defs`**：递归地剥除 `title` 字段，修复了与严格的 LLM Provider 配合时的 Schema 校验问题。([#1595](https://github.com/agentscope-ai/agentscope/pull/1595))

**Tool**

* **关闭 `.env` 绕过通道**：`Write`、`Edit`、`Bash` 不再允许 Agent 通过正规化路径技巧读写 `.env`（以及其他危险路径），危险路径检测 API 同步收紧。([#1656](https://github.com/agentscope-ai/agentscope/pull/1656))

**Scripts**

* 辅助脚本现在会将 `TextBlock` 列表赋值给 `content`，而不是直接传一个字符串。([#1629](https://github.com/agentscope-ai/agentscope/pull/1629))