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

# V1 迁移指南

> 从 AgentScope Java 1.x 升级到 2.0 的完整迁移指南

<Tip>
  如果你在找各版本的具体变更记录，请见 [Release Notes](/v2/zh/docs/others/release-notes)。
</Tip>

AgentScope Java 2.0 版本尽量保持了对 1.x 版本的兼容，确保大部分用户的平滑升级，但同时 2.0 版本也带来了 API 层面的不兼容变更。本页分为两部分：

* **迁移指南** —— 对 1.x 的变更，按紧迫度再分两层：
  * **Part A · 必须迁移** —— 不改会编译失败或运行抛异常
  * **Part B · 推荐迁移** —— 当前仍可调用，但已标 `@Deprecated(forRemoval = true)`；为保证平滑升级，这些 API 在 2.0.x 期间会持续保留，将在未来大版本（如 2.1）中逐步清理
* **新增内容** —— 不在迁移指南中覆盖的增量功能

## 迁移指南

### Part A —— 必须迁移（不迁移会编译失败或运行抛异常）

本节列出的 API 已被删除、重命名或语义收紧。1.x 中能编译运行的代码到 2.0 上会直接报错。

#### A.1 已删除的 `ReActAgent.Builder` 方法

| 2.0 中已删除                                              | 替代方案                           |
| ----------------------------------------------------- | ------------------------------ |
| `.memory(Memory)`                                     | `.stateStore(AgentStateStore)` |
| `.statePersistence(StatePersistence)`                 | `.stateStore(AgentStateStore)` |
| `.structuredOutputReminder(StructuredOutputReminder)` | 不再需要，模型层原生支持                   |

详见 → [上下文](/v2/zh/docs/building-blocks/context)

#### A.2 已删除的包 / 类

| 2.0 中已删除                                                                                               | 替代方案                                         |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `io.agentscope.core.session.SessionManager`                                                            | `.stateStore(AgentStateStore)`               |
| `io.agentscope.core.pipeline.*`（`Pipeline`、`Pipelines`、`SequentialPipeline`、`FanoutPipeline`、`MsgHub`） | middleware + 子 agent + event stream          |
| `io.agentscope.core.model.tts.*`（14 个文件：DashScope TTS / Realtime TTS / `AudioPlayer` 等）                | 直接对接上游 TTS SDK                               |
| `io.agentscope.core.model.StructuredOutputReminder`                                                    | 不再需要，模型层原生支持                                 |
| `io.agentscope.core.agent.StructuredOutputCapableAgent`                                                | 不再需要，能力已内联到 `ReActAgent`                     |
| `io.agentscope.core.hook.PendingToolRecoveryHook`                                                      | `Builder.enablePendingToolRecovery(boolean)` |
| `io.agentscope.core.hook.TTSHook`                                                                      | 随 TTS 模块删除                                   |

#### A.3 模型提供商迁出 core

OpenAI、Gemini、Anthropic、DashScope、Ollama 的 Chat Model 实现不再打包在 `agentscope-core` 中。core 现在只保留共享模型契约，例如 `Model`、`ChatModelBase`、`Formatter`、`ModelRegistry` 和 `ModelProvider` SPI。

如果 v1 代码从 core import 具体模型提供商类，需要改为引入对应模型扩展模块：

| v1 import / 依赖                                       | v2 替代方案                                                                                                         |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `io.agentscope.core.model.OpenAIChatModel`           | 引入 `agentscope-extensions-model-openai`；import `io.agentscope.extensions.model.openai.OpenAIChatModel`          |
| `io.agentscope.core.model.GeminiChatModel`           | 引入 `agentscope-extensions-model-gemini`；import `io.agentscope.extensions.model.gemini.GeminiChatModel`          |
| `io.agentscope.core.model.AnthropicChatModel`        | 引入 `agentscope-extensions-model-anthropic`；import `io.agentscope.extensions.model.anthropic.AnthropicChatModel` |
| `io.agentscope.core.model.DashScopeChatModel`        | 引入 `agentscope-extensions-model-dashscope`；import `io.agentscope.extensions.model.dashscope.DashScopeChatModel` |
| `io.agentscope.core.model.OllamaChatModel`           | 引入 `agentscope-extensions-model-ollama`；import `io.agentscope.extensions.model.ollama.OllamaChatModel`          |
| `io.agentscope.core.formatter.<provider>.*`          | `io.agentscope.extensions.model.<provider>.formatter.*`                                                         |
| `io.agentscope.core.credential.<Provider>Credential` | `io.agentscope.extensions.model.<provider>.credential.<Provider>Credential`                                     |

`ModelRegistry` 字符串 id 仍然可用，但前提是对应模型扩展模块已经在 classpath 中：

```java theme={null}
ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .model("dashscope:qwen-plus")
    .build();
```

Spring Boot 应用应使用对应模型提供商的 starter，而不是依赖 core 中的通用模型创建路径：

| 模型提供商     | Spring Boot starter                        |
| --------- | ------------------------------------------ |
| OpenAI    | `agentscope-openai-spring-boot-starter`    |
| DashScope | `agentscope-dashscope-spring-boot-starter` |
| Gemini    | `agentscope-gemini-spring-boot-starter`    |
| Anthropic | `agentscope-anthropic-spring-boot-starter` |
| Ollama    | `agentscope-ollama-spring-boot-starter`    |

详见 → [模型](/v2/zh/docs/building-blocks/model)、[模型提供商](/v2/zh/integration/overview)

#### A.4 `state` 包重构（编译错误）

| v1                 | v2                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------ |
| `AgentMetaState`   | `AgentState`                                                                         |
| `StateModule`      | **删除**                                                                               |
| `StatePersistence` | **删除**，改用 `AgentStateStore`                                                          |
| `ToolkitState`     | `io.agentscope.core.state.legacy.ToolkitState`（仅兼容）                                  |
| （新增）               | `Task`、`TaskContextState`、`ToolContextState`、`PlanModeContextState`、`ReadCacheEntry` |

凡是从 `io.agentscope.core.state` import `AgentMetaState`、`StateModule`、`StatePersistence`、`ToolkitState` 的代码都会编译失败。详见 → [上下文](/v2/zh/docs/building-blocks/context)

#### A.5 `PlanNotebook` 已删除 —— 改用 `HarnessAgent.enablePlanMode()`

整个 `io.agentscope.core.plan` 包（`PlanNotebook`、`Plan`、`SubTask`、`PlanStorage`、`PlanToHint` 及相关类）已完整删除，无 deprecated 桥接。

**变更说明**：v1 的 `PlanNotebook` 将计划建模为结构化的 `Plan` + `SubTask` 对象，带状态机（todo → in\_progress → done → abandoned）和 8 个工具函数。v2 的替代方案是完全不同的设计思路 —— plan mode 是一个**只读的调查设计阶段**，agent 在一个纯 markdown 文件中完成方案设计，然后才获得写权限。

| v1 `PlanNotebook`                                                                                                                                     | v2 Plan Mode                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `ReActAgent.builder().planNotebook(PlanNotebook.builder().build())`                                                                                   | `HarnessAgent.builder().enablePlanMode()`                       |
| 结构化 `Plan` + `SubTask` 对象，带状态机                                                                                                                        | 纯 markdown 文件（`plans/PLAN.md`）                                  |
| 8 个工具：`createPlan`、`reviseCurrentPlan`、`updateSubtaskState`、`finishSubtask`、`finishPlan`、`viewSubtasks`、`viewHistoricalPlans`、`recoverHistoricalPlan` | 3 个工具：`plan_enter`、`plan_write`、`plan_exit`                     |
| 计划与执行混合 —— 无只读限制                                                                                                                                      | plan mode 为只读；`plan_exit` 触发 HITL 门控，用户确认后 agent 才恢复写权限         |
| `PlanToHint` 在每个 reasoning step 前注入上下文提示                                                                                                              | `PlanModeMiddleware` 在 plan mode 下阻止 mutating 工具调用              |
| `PlanStorage`（内存）+ `StateModule` 持久化                                                                                                                  | 计划文件通过 `WorkspaceManager` 写入；状态保存在 `AgentState.planModeContext` |

**子任务跟踪**：如果你的 v1 代码依赖 `PlanNotebook` 的子任务状态跟踪（把工作拆成子任务并在执行过程中逐个勾选），v2 的等价能力是**任务列表** —— 在 builder 上调用 `.enableTaskList(true)` 启用，会注册 `TodoTools` 和 `TaskReminderMiddleware`。

#### A.6 `Msg` 构造按 role 严格校验（运行抛异常）

`Msg` 现在在构造时按 `role` 对 `content` 做校验：

* `USER` —— 仅允许 `TextBlock` / `DataBlock` / `ImageBlock` / `AudioBlock` / `VideoBlock`
* `SYSTEM` —— 仅允许 `TextBlock`
* `ASSISTANT` —— 不限制

v1 中容忍的非法组合（例如 `USER` 携带 `ToolUseBlock`）现在会在构造时直接抛异常。推荐改用 role 子类 `UserMessage` / `AssistantMessage` / `SystemMessage` / `ToolResultMessage`，在调用处就显式表达 role 与 content 的对应关系。详见 → [消息与事件](/v2/zh/docs/building-blocks/message-and-event)

#### A.7 Agent 完全无状态（架构变更）

`ReActAgent` 现在是 **完全无状态** 的——实例本身不持有任何可变的"当前会话"状态。所有 per-call 可变状态（`AgentState`、`PermissionEngine`、事件 sink）封装在内部 `CallExecution` 对象中，通过 Reactor Context 在调用链上透传。同一个 Agent 实例可以安全地并发服务多个 `(userId, sessionId)` 组合，不同 session 的调用互不干扰。

**v1 → v2 影响**：

| 已移除                                              | 替代方案                                                              |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| `ReActAgent.getCurrentSessionId()`               | `RuntimeContext.getSessionId()`                                   |
| `ReActAgent.getCurrentUserId()`                  | `RuntimeContext.getUserId()`                                      |
| `AgentBase(name, desc, checkRunning, hooks)` 构造器 | `AgentBase(name, desc, hooks)`                                    |
| `ReActAgent.getState()`                          | `ReActAgent.getAgentState()` 或 `getAgentState(userId, sessionId)` |

`isCheckRunning()` 仍可调用（返回 `false`），`Builder.checkRunning(boolean)` 仍可调用（被忽略），均已标 `@Deprecated`。

#### A.8 `TracerRegistry` + `TelemetryTracer` → `OtelTracingMiddleware`

旧的 tracing 配置会在框架中全局注册一个 `Tracer`：

```java theme={null}
TracerRegistry.register(TelemetryTracer.builder().tracer(tracer).build());
```

在当前 2.0 源码中，`TelemetryTracer` 位于 `agentscope-extensions-studio` 模块，而不是 `agentscope-core`。Studio 集成仍会使用它，但仅仅为了恢复应用级 tracing 而引入 Studio 扩展并不是推荐迁移方式。`Tracer` 接口与 `TracerRegistry` 都已标记为待删除。

应用 tracing 应改用标准 OpenTelemetry 组件：

| 旧配置                                              | 2.0 替代方案                                              |
| ------------------------------------------------ | ----------------------------------------------------- |
| `TelemetryTracer.builder().endpoint(...)`        | 构建 `OtlpHttpSpanExporter` 并添加到 `SdkTracerProvider`    |
| `TelemetryTracer.builder().addHeader(...)`       | 调用 `OtlpHttpSpanExporter.builder().addHeader(...)`    |
| `TracerRegistry.register(...)`                   | 通过 `OpenTelemetrySdk.buildAndRegisterGlobal()` 注册 SDK |
| 框架级全局 tracer                                     | 为每个需要输出 span 的 agent 添加 `new OtelTracingMiddleware()` |
| `TracerRegistry.resetToNoop()` / tracer shutdown | 应用关闭时关闭由应用持有的 `SdkTracerProvider`                     |

Middleware 从 `GlobalOpenTelemetry` 读取 SDK，因此必须先注册 SDK，再让 agent 使用 middleware。所需依赖、完整 OTLP 配置以及自定义认证 header 示例见 [Middleware — OtelTracingMiddleware](/v2/zh/docs/building-blocks/middleware#oteltracingmiddleware)。

***

### Part B —— 推荐迁移（`@Deprecated(forRemoval = true)`，仍可调用）

本节列出在 2.0 中仍可调用、但已标记 `@Deprecated(forRemoval = true)` 的 API。为保证平滑升级，这些 API 在 2.0.x 期间会持续保留，将在未来大版本（如 2.1）中逐步清理。可以按节奏迁移，但建议尽早。

#### B.1 `SkillBox` → SkillRepository

* `SkillBox` 类与 `Builder.skillBox(SkillBox)` 均标 `@Deprecated(forRemoval = true, since = "2.0.0")`
* 新方式：通过 `AgentSkillRepository`（内置 `ClasspathSkillRepository`、`FileSystemSkillRepository`）注入技能，使用 `Builder.skillRepository(...)` / `.skillRepositories(...)`。只要注册了至少一个 repository，`DynamicSkillMiddleware` 会自动安装，在每次 `call()` 前重建 skill prompt
* 细粒度过滤：`Builder.skillFilter(SkillFilter)`

详见 → [技能](/v2/zh/docs/harness/skill)

#### B.2 Hook → Middleware

整个 `io.agentscope.core.hook` 包 —— 包括 `Hook` 接口、`HookEvent`、`HookEventType` 与所有 `*Event` 类 —— 均标 `@Deprecated(forRemoval = true, since = "2.0.0")`。原有 import 仍能编译，`Builder.hook(...)` / `.hooks(...)` 仍可调用（由 `LegacyHookDispatcher` 桥接），v1 代码不会立刻 break。推荐改用 `io.agentscope.core.middleware`：

* `MiddlewareBase` 提供 5 个 stage：洋葱型 `onAgent` / `onReasoning` / `onActing` / `onModelCall`，管道型 `onSystemPrompt`
* Builder：`.middleware(MiddlewareBase)` 与 `.middlewares(List<? extends MiddlewareBase>)`
* 内置：`TaskReminderMiddleware`（与 `TodoTools` 配合，在每个 reasoning step 前注入任务提醒）

详见 → [Middleware](/v2/zh/docs/building-blocks/middleware)

#### B.3 `Memory` → `AgentStateStore` + `AgentState`

* `io.agentscope.core.memory.Memory` 接口与所有实现（`InMemoryMemory`、`LongTermMemory` 等）均标 `@Deprecated(forRemoval = true, since = "2.0.0")`
* `Memory` 不再 `extends StateModule`；新增 `saveTo(AgentStateStore, userId, sessionId)` / `loadFrom(AgentStateStore, userId, sessionId)` 作桥接，方便现有实现继续通过 `AgentStateStore` 走持久化
* 新模型：
  * **会话历史**保存在 `AgentState.getContext()`
  * **持久化**通过 `AgentStateStore` 抽象（内置 `InMemoryAgentStateStore`、`JsonFileAgentStateStore`），按 `(userId, sessionId)` 二元组分桶
  * Builder 链：`.stateStore(AgentStateStore)` —— `AgentState` 在每次 `call()` 后自动 save/load，按该次调用 `RuntimeContext` 的 `(userId, sessionId)` 寻址

详见 → [上下文](/v2/zh/docs/building-blocks/context)

#### B.4 事件订阅：hook + chunk → `streamEvents()`

v1 中通过 `Hook` + 各种 `*ChunkEvent` 拼装文本 / 工具增量的代码，可直接迁到 `agent.streamEvents()`：返回 `Flux<AgentEvent>`，覆盖 agent 全生命周期及 HITL 流程的 28 个类型化事件（`RequireUserConfirmEvent`、`RequireExternalExecutionEvent`、`UserConfirmResultEvent`、`ExternalExecutionResultEvent` 等）。

配合 `Msg` 重构新增的能力：

* `DataBlock` —— 统一的多模态块，base64 / URL 二选一
* `HintBlock` —— agent 引导提示 / 中间推理
* `ToolUseBlock` / `ToolResultBlock` 增加 `state` 字段（`ToolCallState` / `ToolResultState`）—— 完整建模 tool-call 生命周期
* 所有 block 加 `id` 字段 —— 跨事件流稳定引用

详见 → [消息与事件](/v2/zh/docs/building-blocks/message-and-event)

##### `stream()` → `streamEvents()`（与 Python 2.0 对齐）

Python 2.0 的 `agent.reply_stream()` 只返回一种事件流签名（`AsyncGenerator[AgentEvent, None]`），对应 Java 的细粒度 `io.agentscope.core.event.AgentEvent` 体系。为了与之对齐，Java 端的粗粒度 `Flux<Event> stream(...)` API 在 2.0.0 全部 `@Deprecated`：

* **方法（`forRemoval = true`，将在未来大版本如 2.1 中清理）**
  * `StreamableAgent.stream(...)` —— 接口上的全部 11 个 `stream(...)` 重载（默认方法 + 抽象方法）
  * `AgentBase.stream(...)` —— 3 个 `Flux<Event>` 实现
  * `ReActAgent.stream(..., RuntimeContext)` —— 4 个 `RuntimeContext` 后缀重载
  * `HarnessAgent.stream(...)` —— 9 个重载（3 个接口 `@Override` + 6 个 `RuntimeContext` 变体）。`HarnessAgent` 新增 `streamEvents(Msg/List<Msg>[, RuntimeContext])` 4 个方法，内部委托到 `ReActAgent.streamEvents(...)` 并复用沙箱生命周期 `acquireForCall` / `releaseForCall`
  * `ReActAgent.streamEvents(..., RuntimeContext)` 新增 —— 对齐 `call(..., RuntimeContext)` 的 context 透传形态
* **类型（软弃用，暂不 `forRemoval`）**
  * `io.agentscope.core.agent.Event`、`EventType`、`EventSource`
  * 这些类目前仍被 harness（子 agent 事件转发：`SubAgentTool` / `SubagentEventBus` / `DefaultAgentManager` / `AgentSpawnTool`）、AGUI、A2A、chat-completions-web、kotlin extension 等内部模块作为事件总线 / 适配器的输入消费。等这些模块完成迁移到 `AgentEvent` 后再翻成 `forRemoval = true`，避免一次性把下游全打成警告
  * `HarnessAgent.streamEvents(...)` 会转发子 agent 事件（`source` 非空路径），远程 Agent Protocol 子 agent 在 `remoteStreaming` 开启时同样支持

新代码统一改用：

```java theme={null}
agent.streamEvents(new UserMessage("Hello"))
        .doOnNext(event -> {
            if (event.getType() == AgentEventType.TEXT_BLOCK_DELTA) {
                System.out.print(((TextBlockDeltaEvent) event).getDelta());
            }
        })
        .blockLast();
```

#### B.5 RAG 模块：推进中

* `Knowledge`、`KnowledgeRetrievalTools`、`RAGMode`、`GenericRAGHook` 全部 `@Deprecated(forRemoval = true, since = "2.0.0")`
* Builder：`.knowledge(...)` / `.knowledges(...)` / `.ragMode(...)` / `.retrieveConfig(...)` 同步弃用
* v2 架构下的 knowledge base / document reader / store 将在后续 minor 版本上线。v1 实现在 2.0 仍可调用以保兼容，但**新代码不要依赖**

#### B.6 长期记忆模块：推进中

* `LongTermMemory`、`LongTermMemoryMode`、`LongTermMemoryTools` 全部 `@Deprecated(forRemoval = true, since = "2.0.0")`
* Builder：`.longTermMemory(...)` / `.longTermMemoryMode(...)` / `.longTermMemoryAsyncRecord(...)` 同步弃用
* 同样在 v2 架构下重写中；新代码先不要依赖

#### B.7 core 内置 Shell / File 工具：不再 deprecated

* `io.agentscope.core.tool.coding.*`（`ShellCommandTool`、`CommandValidator`、`UnixCommandValidator`、`WindowsCommandValidator`）与 `io.agentscope.core.tool.file.*`（`ReadFileTool`、`WriteFileTool`、`FileToolUtils`）自 2.0.0-RC1 起**不再标 `@Deprecated`**
* 这些工具直接在宿主机进程上执行命令和读写文件。对于不需要 workspace / 沙箱隔离的 `ReActAgent` 用户，它们是给 agent 添加 shell 和文件访问能力的推荐方式：

```java theme={null}
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new ReadFileTool("/path/to/base/dir"));
toolkit.registerTool(new WriteFileTool("/path/to/base/dir"));
toolkit.registerTool(new ShellCommandTool());

ReActAgent agent = ReActAgent.builder()
    .toolkit(toolkit)
    /* ... */
    .build();
```

* 对于 `HarnessAgent` 用户，harness 模块自带 workspace 感知的文件和 shell 工具（`read_file`、`write_file`、`execute` 等），提供统一的本地 / Docker / 云沙箱后端、权限隔离、读写缓存、HITL 审批，推荐在需要 workspace 集成的场景下使用 harness 内置工具

详见 → [Harness 文件系统](/v2/zh/docs/harness/filesystem)

***

## 新增内容

下面列出的能力都是 2.0 的增量新增，对 1.x 代码 0 影响。事件系统、消息重构、middleware 机制已在上方迁移指南完整覆盖，此处不再重复。

### AG-UI v2

* AG-UI 适配器迁移到 v2 `streamEvents()` 链路，正常 `RUN_STARTED` / `RUN_FINISHED` 由 `AgentStartEvent` / `AgentEndEvent` 转换生成，异常路径输出 `RUN_ERROR` 并补 `RUN_FINISHED`
* 新增 `AgentEventConverter` 与 `AguiEventEnricher` 扩展点：converter 负责语义映射，enricher 负责 `timestamp` / `rawEvent` 等横切属性；Spring Boot starter 会自动收集对应 bean
* 所有 `AguiEvent` 支持 AG-UI base event properties；默认不启用 `BaseEventPropertiesEnricher`，显式开启后只补缺失 `timestamp`，不默认填 `rawEvent`
* `AguiAdapterConfig.emitTokenUsage` 可选输出 `CUSTOM token_usage` 事件，包含当前模型调用 delta 与本次 run cumulative token usage
* **行为变更：** `source != null` 的 AgentEvent（子 agent 事件）默认映射为 AG-UI `CUSTOM`（`subagent.lifecycle` / `subagent.text` / `subagent.thinking` / `subagent.tool_call` / `subagent.tool_result` / `subagent.require_confirm`），不再走原生 `TEXT_MESSAGE_*` / `RUN_*`。设 `emitSubagentEventsAsNative(true)` 可恢复旧的原生映射
* Spring Boot starter 支持 `AguiRuntimeContextResolver` 和自定义 `AguiAgentAdapterFactory`，并支持 frontend tool injection / merge mode 与 HITL interrupt 输出

详见 → [AG-UI](/v2/zh/integration/protocol/agui)

### Toolkit & Permission

工具执行是 2.0 主要的扩展面，而权限系统直接挂在工具执行路径上，因此合并讲。

* **Toolkit 升级**：
  * 统一基类：`ToolBase` / `AgentTool`
  * 工具组：`ToolGroup` / `ToolGroupScope` / `MetaToolFactory` —— 按需激活；保留的 `basic` 组始终在线
  * 注解驱动：`ReflectiveFunctionTool` + `@Tool` / `@ToolParam`；`Toolkit#registerTool(Object)` 反射注册任意带注解的方法
  * 内置任务工具：`io.agentscope.core.tool.builtin.TodoTools.todoWrite`（与 `TaskReminderMiddleware` 配合）
* **Permission 系统**（新包 `io.agentscope.core.permission`）：
  * `PermissionEngine`、`PermissionRule`、`PermissionMode`（`DEFAULT` / `ACCEPT_EDITS` / `EXPLORE` / `BYPASS` / `DONT_ASK`）、`PermissionBehavior`
  * 每次 tool 调用前自动经 `PermissionEngine`：允许 / 用户审批 / 拒绝；HITL 决策回流到 `UserConfirmResultEvent`

详见 → [工具](/v2/zh/docs/building-blocks/tool)、[权限系统](/v2/zh/docs/building-blocks/permission-system)

### 模型容错与凭据

* 新包：`io.agentscope.core.credential` —— 共享 credential 契约与 `ModelCard`；特定模型提供商的 credential 随对应模型扩展模块提供
* `ModelRegistry`：在对应模型扩展模块位于 classpath 时，按 `"provider:model"` 字符串解析（如 `dashscope:qwen-max`、`openai:gpt-5`）
* Builder 新增：`.model(String)`、`.maxRetries(int)`、`.fallbackModel(Model)` / `.fallbackModel(String)`、`.stopOnReject(boolean)` —— 主模型失败自动重试 / 切换备用模型

详见 → [模型](/v2/zh/docs/building-blocks/model)

### Workspace（Harness 模块）

* 工作区抽象：本地文件系统 / Docker / E2B 云沙箱统一接口
* 预热池：支持提前批量初始化执行环境，适配 RL rollout 等并行场景

详见 → [Workspace](/v2/zh/docs/harness/workspace)

### Builder 其他新方法

* `.enableTaskList(...)` / `.enableTaskList(boolean)` —— 启用内置 `TodoTools`
* `.permissionContext(PermissionContextState)` —— 预置 permission 规则
* `ReActAgent.Builder.fromAgent(ReActAgent)` —— 从现有 agent 的可观察配置（name、description、system prompt、model、maxIters、generateOptions、toolkit）派生新的 builder
* `HarnessAgent.Builder.fromAgent(ReActAgent)` —— 把 ReActAgent 迁到 HarnessAgent 的辅助方法。在 `ReActAgent.Builder.fromAgent` 的 7 个字段之上额外继承 ReActAgent 上**所有可观察的配置**：`stateStore` / `defaultSessionId`、`ModelConfig`（`maxRetries` / `fallbackModel`）、`ReactConfig.stopOnReject`、`modelExecutionConfig` / `toolExecutionConfig` / `toolExecutionContext`、`enablePendingToolRecovery`、`checkRunning`、`permissionContext`、`middlewares`、`hooks`。`enableMetaTool` / `enableTaskList` 不复制（这两个是 Builder-time 工具注册开关，toolkit copy 已经把它们注册的工具带过来了）。harness 独有的 workspace / filesystem / subagent / skill / plan mode / 各 `disable*` 等仍需手动设置。javadoc 里有完整列表
* **ReActAgent 新增 getter 以支撑上述迁移**：`getModelExecutionConfig()` / `getToolExecutionConfig()` / `getToolExecutionContext()` / `isPendingToolRecoveryEnabled()` / `getPermissionContext()`（位于 `ReActAgent`）；`isCheckRunning()`（位于 `AgentBase`，已弃用，始终返回 `false`）

详见 → [智能体](/v2/zh/docs/building-blocks/agent)

### Memory / Compaction 独立模型

`MemoryConfig` 和 `CompactionConfig` 新增 `.model(Model)` / `.model(String)` builder 方法，允许为记忆提取（flush）、记忆整理（consolidation）和上下文压缩（compaction）指定独立于 agent 主模型的轻量模型。不设则 fallback 到 agent 主模型（保持原行为）。

```java theme={null}
HarnessAgent.builder()
    .model("openai:o3")
    .memory(MemoryConfig.builder()
        .model("openai:gpt-4.1-mini")
        .build())
    .compaction(CompactionConfig.builder()
        .model("openai:gpt-4.1-mini")
        .build())
    .build();
```