V1 Migration Guide

• Migration Guide — what changes against 1.x, in two tiers:
  • Part A · Required — your code will fail to compile or throw at runtime if you don’t migrate
  • Part B · Recommended — still works but @Deprecated(forRemoval = true); will be removed in the next minor
• What’s New — net-new capabilities that don’t appear in the Migration Guide

​

Migration Guide

​

Part A — Required (compile errors or runtime exceptions if you don’t migrate)

​

A.1 Removed ReActAgent.Builder methods

​

A.2 Removed packages and classes

​

A.3 Model providers moved out of core

ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .model("dashscope:qwen-plus")
    .build();

​

A.4 state package restructure (compile error)

​

A.5 PlanNotebook removed — use HarnessAgent.enablePlanMode()

​

A.6 Msg content validation is stricter (runtime exception)

• USER — only TextBlock / DataBlock / ImageBlock / AudioBlock / VideoBlock
• SYSTEM — only TextBlock
• ASSISTANT — unrestricted

​

A.7 Agent is fully stateless (architecture change)

​

A.8 TracerRegistry + TelemetryTracer → OtelTracingMiddleware

TracerRegistry.register(TelemetryTracer.builder().tracer(tracer).build());

​

Part B — Recommended (@Deprecated(forRemoval = true), still callable today)

​

B.1 SkillBox → skill repositories

• SkillBox (the class) and Builder.skillBox(SkillBox) are both @Deprecated(forRemoval = true, since = "2.0.0").
• Recommended path: register one or more AgentSkillRepository implementations (built-ins: ClasspathSkillRepository, FileSystemSkillRepository) via Builder.skillRepository(...) / .skillRepositories(...). When at least one repository is registered, DynamicSkillMiddleware is auto-installed and rebuilds the skill prompt on every call().
• Fine-grained filtering: Builder.skillFilter(SkillFilter).

​

B.2 Hook → Middleware

• MiddlewareBase exposes five stages: the onion-shaped onAgent / onReasoning / onActing / onModelCall, and the pipeline-shaped onSystemPrompt.
• Builder methods: .middleware(MiddlewareBase) and .middlewares(List<? extends MiddlewareBase>).
• Built-in: TaskReminderMiddleware (pairs with TodoTools, re-injects the task list before each reasoning step).

​

B.3 Memory → AgentStateStore + AgentState

• The io.agentscope.core.memory.Memory interface and every implementation (InMemoryMemory, LongTermMemory, …) are @Deprecated(forRemoval = true, since = "2.0.0").
• Memory no longer extends StateModule. It gains saveTo(AgentStateStore, userId, sessionId) / loadFrom(AgentStateStore, userId, sessionId) as a bridge so existing implementations can still round-trip through an AgentStateStore.
• Recommended model:
  • Conversation history lives on AgentState.getContext().
  • Persistence uses the AgentStateStore abstraction (built-in: InMemoryAgentStateStore, JsonFileAgentStateStore), partitioned by the (userId, sessionId) pair.
  • Builder chain: .stateStore(AgentStateStore) — AgentState is saved/loaded automatically on every call(), keyed by the (userId, sessionId) carried on the call’s RuntimeContext.

​

B.4 Event subscription: hooks + chunk events → streamEvents()

• DataBlock — unified multimodal block, accepts base64 or URL sources
• HintBlock — agent guidance / intermediate reasoning
• ToolCallState / ToolResultState on ToolUseBlock / ToolResultBlock — tool-call lifecycle
• id field on every block — stable references across the stream

stream() → streamEvents() (alignment with Python 2.0)

• Methods (forRemoval = true, going away next minor)
  • StreamableAgent.stream(...) — all 11 stream(...) overloads on the interface (defaults + abstract)
  • AgentBase.stream(...) — 3 Flux<Event> implementations
  • ReActAgent.stream(..., RuntimeContext) — 4 RuntimeContext-suffixed overloads
  • HarnessAgent.stream(...) — 9 overloads (3 interface @Overrides + 6 RuntimeContext variants). HarnessAgent gains 4 new streamEvents(Msg/List<Msg>[, RuntimeContext]) methods that delegate to ReActAgent.streamEvents(...) while reusing the sandbox lifecycle acquireForCall / releaseForCall
  • ReActAgent.streamEvents(..., RuntimeContext) added — mirrors call(..., RuntimeContext) for context propagation
• Types (soft deprecation, no forRemoval yet)
  • io.agentscope.core.agent.Event, EventType, EventSource
  • Still consumed internally by the harness (subagent event forwarding: SubAgentTool / SubagentEventBus / DefaultAgentManager / AgentSpawnTool), AGUI, A2A, chat-completions-web, and Kotlin extension modules as the event-bus / adapter input. They will be flipped to forRemoval = true only after those modules migrate to AgentEvent, so the entire downstream is not warning-flooded in a single release.
  • Subagent events are forwarded on HarnessAgent.streamEvents(...) with a non-null source path (including remote Agent Protocol children when remoteStreaming is enabled).

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

​

B.5 RAG module — in progress

• Knowledge, KnowledgeRetrievalTools, RAGMode, GenericRAGHook are all @Deprecated(forRemoval = true, since = "2.0.0").
• The builder methods .knowledge(...) / .knowledges(...) / .ragMode(...) / .retrieveConfig(...) are deprecated in parallel.
• The v2 rewrite is underway. New knowledge base, document reader, and store APIs will land in subsequent minor releases. The v1 implementations remain callable in 2.0 for compatibility, but new code should not depend on them.

​

B.6 Long-term memory module — in progress

• LongTermMemory, LongTermMemoryMode, LongTermMemoryTools are all @Deprecated(forRemoval = true, since = "2.0.0").
• The builder methods .longTermMemory(...) / .longTermMemoryMode(...) / .longTermMemoryAsyncRecord(...) are deprecated in parallel.
• Same status — being rewritten on the v2 architecture. New code should not depend on the current API.

​

B.7 Core shell / file tools — no longer deprecated

• io.agentscope.core.tool.coding.* (ShellCommandTool, CommandValidator, UnixCommandValidator, WindowsCommandValidator) and io.agentscope.core.tool.file.* (ReadFileTool, WriteFileTool, FileToolUtils) are no longer @Deprecated as of 2.0.0-RC1.
• These tools run commands and read/write files directly against the host process. For ReActAgent users who don’t need workspace / sandbox isolation, they are the recommended way to give the agent shell and file access:

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();

• For HarnessAgent users, the harness module provides its own workspace-aware file and shell tools (read_file, write_file, execute, etc.) with unified local / Docker / cloud-sandbox stores, permission isolation, read/write cache, and HITL approval. It is recommended to use the built-in harness tools for workspace-integrated scenarios.

​

What’s New

​

AG-UI v2

• The AG-UI adapter now uses the v2 streamEvents() path. Normal RUN_STARTED / RUN_FINISHED events are converted from AgentStartEvent / AgentEndEvent; error paths emit RUN_ERROR and a fallback RUN_FINISHED.
• New AgentEventConverter and AguiEventEnricher extension points: converters handle semantic mapping, while enrichers handle cross-cutting properties such as timestamp / rawEvent. The Spring Boot starter automatically collects both bean types.
• Every AguiEvent supports AG-UI base event properties. BaseEventPropertiesEnricher is disabled by default; when explicitly enabled, it only fills missing timestamp values and does not default rawEvent.
• AguiAdapterConfig.emitTokenUsage can emit CUSTOM token_usage events with model-call delta and run-level cumulative token usage.
• Behavior change: AgentEvents with source != null (subagent events) are emitted as AG-UI CUSTOM events (subagent.lifecycle, subagent.text, subagent.thinking, subagent.tool_call, subagent.tool_result, subagent.require_confirm) instead of native TEXT_MESSAGE_* / RUN_*. Set emitSubagentEventsAsNative(true) to restore the legacy native mapping.
• The Spring Boot starter supports AguiRuntimeContextResolver, custom AguiAgentAdapterFactory, frontend tool injection / merge mode, and HITL interrupt output.

​

Toolkit & Permission

• Toolkit upgrades:
  • Unified base classes: ToolBase / AgentTool
  • Tool groups: ToolGroup / ToolGroupScope / MetaToolFactory — activate on demand; the reserved basic group is always on
  • Annotation-driven registration: ReflectiveFunctionTool + @Tool / @ToolParam; Toolkit#registerTool(Object) reflectively registers any annotated methods
  • Built-in task tool: io.agentscope.core.tool.builtin.TodoTools.todoWrite (pairs with TaskReminderMiddleware)
• Permission system (new package io.agentscope.core.permission):
  • PermissionEngine, PermissionRule, PermissionMode (DEFAULT / ACCEPT_EDITS / EXPLORE / BYPASS / DONT_ASK), PermissionBehavior
  • Every tool call goes through PermissionEngine: allow / require user confirmation / deny. HITL decisions flow back as UserConfirmResultEvent.

​

Model fault tolerance and credentials

• New package io.agentscope.core.credential — shared credential contracts and ModelCard; provider-specific credentials live with the model extension modules
• ModelRegistry resolves models from "provider:model" strings when the matching model extension module is on the classpath (e.g. dashscope:qwen-max, openai:gpt-5)
• Builder additions: .model(String), .maxRetries(int), .fallbackModel(Model) / .fallbackModel(String), .stopOnReject(boolean) — primary-model failure auto-retries and falls back

​

Workspace (Harness module)

• Workspace abstraction unifies local filesystem, Docker, and E2B cloud sandbox execution behind a single interface
• Warm-up pool — pre-initialize execution environments in batches; useful for parallel RL rollouts

​

Other new Builder methods

• .enableTaskList(...) / .enableTaskList(boolean) — enable the built-in TodoTools
• .permissionContext(PermissionContextState) — preload permission rules
• ReActAgent.Builder.fromAgent(ReActAgent) — derive a new builder from an existing agent’s observable configuration (name, description, system prompt, model, maxIters, generateOptions, toolkit)
• HarnessAgent.Builder.fromAgent(ReActAgent) — ReActAgent → HarnessAgent migration helper. Inherits the same 7 fields as ReActAgent.Builder.fromAgent plus every other observable configuration on ReActAgent: stateStore / defaultSessionId, ModelConfig (maxRetries / fallbackModel), ReactConfig.stopOnReject, modelExecutionConfig / toolExecutionConfig / toolExecutionContext, enablePendingToolRecovery, checkRunning, permissionContext, middlewares, and hooks. The only flags not copied are enableMetaTool / enableTaskList — these are builder-time toolkit-mutation flags, and the toolkit copy already carries the tools they registered. Harness-only config (workspace / filesystem / subagents / skills / plan mode / disable* toggles) still has to be set explicitly. See javadoc for the full table.
• New getters on ReActAgent / parents to support the above migration: getModelExecutionConfig() / getToolExecutionConfig() / getToolExecutionContext() / isPendingToolRecoveryEnabled() / getPermissionContext() (on ReActAgent); isCheckRunning() (on AgentBase, deprecated, always returns false).

​

Dedicated model for Memory / Compaction

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();