fix(docs): align documentation with actual codebase

docs/en/intro.md

@@ -34,15 +34,14 @@ AgentScope includes production-ready tools that address common challenges in age
 AgentScope is designed to integrate with existing enterprise infrastructure without requiring extensive modifications:
 
 - **MCP Protocol** - Integrate with any MCP-compatible server to instantly extend agent capabilities. Connect to the growing ecosystem of MCP tools and services—from file systems and databases to web browsers and code interpreters—without writing custom integration code.
-- **A2A Protocol** - Enable distributed multi-agent collaboration through standard service discovery. Register agent capabilities to Nacos or similar registries, allowing agents to discover and invoke each other as naturally as calling microservices.
+- **A2A Protocol** - Enable distributed multi-agent collaboration through extension modules. Register agent capabilities to Nacos or similar registries (via `agentscope-extensions-nacos-a2a`), allowing agents to discover and invoke each other as naturally as calling microservices.
 
 ### Production Grade
 
 Built for enterprise deployment requirements:
 
-- **High Performance** - Reactive architecture based on Project Reactor ensures non-blocking execution. GraalVM native image compilation achieves 200ms cold start times, making AgentScope suitable for serverless and auto-scaling environments.
-- **Security Sandbox** - AgentScope Runtime provides isolated execution environments for untrusted tool code. Includes pre-built sandboxes for GUI automation, file system operations, and mobile device interaction, preventing unauthorized access to system resources.
-- **Observability** - Native integration with OpenTelemetry for distributed tracing across the entire agent execution pipeline. AgentScope Studio provides visual debugging, real-time monitoring, and comprehensive logging for development and production environments.
+- **High Performance** - Reactive architecture based on Project Reactor ensures non-blocking execution. Supports GraalVM native image compilation through Micronaut/Quarkus, suitable for serverless and auto-scaling environments.
+- **Observability** - Pluggable Tracer SPI with extension module support for OpenTelemetry, enabling distributed tracing across the entire agent execution pipeline. AgentScope Studio provides visual debugging, real-time monitoring, and comprehensive logging for development and production environments.
 
 ## Requirements
 

docs/en/multi-agent/handoffs.md

@@ -105,7 +105,7 @@ Register each tool on the corresponding agent’s Toolkit via `toolkit.registerT
 Create a sales and a support agent as `AgentScopeAgent`, each with its own ReActAgent, system prompt, and Toolkit that includes the appropriate handoff tool.
 
 ```java
-import com.alibaba.cloud.ai.graph.agent.agentscope.AgentScopeAgent;
+import com.alibaba.cloud.ai.agent.agentscope.AgentScopeAgent;
 import io.agentscope.core.ReActAgent;
 import io.agentscope.core.memory.InMemoryMemory;
 import io.agentscope.core.model.DashScopeChatModel;
@@ -129,6 +129,7 @@ ReActAgent.Builder salesReActBuilder = ReActAgent.builder()
 
 AgentScopeAgent salesAgent = AgentScopeAgent.fromBuilder(salesReActBuilder)
         .name(AgentScopeStateConstants.SALES_AGENT)
+        .description("Sales agent for pricing, product availability, and sales inquiries")
         .instruction("please assist the customer with their sales inquiry: {input}.")
         .includeContents(true)
         .returnReasoningContents(true)
@@ -152,6 +153,7 @@ ReActAgent.Builder supportReActBuilder = ReActAgent.builder()
 
 AgentScopeAgent supportAgent = AgentScopeAgent.fromBuilder(supportReActBuilder)
         .name(AgentScopeStateConstants.SUPPORT_AGENT)
+        .description("Support agent for technical issues and troubleshooting")
         .instruction("please assist the customer with their product technical inquiry: {input}.")
         .includeContents(true)
         .returnReasoningContents(true)

docs/en/multi-agent/workflow.md

@@ -83,9 +83,9 @@ START → list_tables → call_get_schema → get_schema → generate_query →
 
 **Configuration**:
 
-- `workflow.rag.enabled` – Enable RAG workflow beans.
-- `workflow.sql.enabled` – Enable SQL workflow beans.
-- `workflow.runner.enabled` – When `true`, run a one-shot demo on startup (use with one of the above).
+- `workflow.rag.enabled` – Enable RAG workflow beans (default `false`).
+- `workflow.sql.enabled` – Enable SQL workflow beans (default `true` in example).
+- `workflow.runner.enabled` – When `true`, run a one-shot demo on startup (default `true` in example; use with one of the above).
 - **DashScope API key**: `AI_DASHSCOPE_API_KEY` or `spring.ai.dashscope.api-key` (required for RAG and SQL; RAG also needs an embedding model).
 
 ## Custom workflow vs other patterns

docs/en/quickstart/agent.md

@@ -26,12 +26,16 @@ The `ReActAgent` class exposes the following parameters in its constructor:
 | Parameter | Further Reading | Description |
 |-----------|-----------------|-------------|
 | `name` (required) | | Agent's name |
-| `sysPrompt` (required) | | System prompt |
+| `sysPrompt` | | System prompt (recommended) |
 | `model` (required) | [Model Integration](../task/model.md) | Model for generating responses |
 | `toolkit` | [Tool System](../task/tool.md) | Module for registering/calling tool functions |
 | `memory` | [Memory Management](../task/memory.md) | Short-term memory for conversation history |
-| `longTermMemory` | [Long-term Memory](../task/long-term-memory.md) | Long-term memory |
-| `longTermMemoryMode` | [Long-term Memory](../task/long-term-memory.md) | Long-term memory mode: `AGENT_CONTROL`, `STATIC_CONTROL`, or `BOTH` |
+| `description` | | Agent description |
+| `generateOptions` | | LLM generation parameters (temperature, topP, maxTokens, etc.) |
+| `toolExecutionContext` | [Tool System](../task/tool.md) | Tool execution context for dependency injection into tools |
+| `planNotebook` | [Planning](../task/plan.md) | Plan manager |
+| `longTermMemory` | [Memory Management](../task/memory.md) | Long-term memory |
+| `longTermMemoryMode` | [Memory Management](../task/memory.md) | Long-term memory mode: `AGENT_CONTROL`, `STATIC_CONTROL`, or `BOTH` |
 | `maxIters` | | Max iterations for generating response (default: 10) |
 | `hooks` | [Hook System](../task/hook.md) | Event hooks for customizing agent behavior |
 | `modelExecutionConfig` | | Timeout/retry config for model calls |

docs/en/quickstart/installation.md

@@ -36,7 +36,7 @@ implementation 'io.agentscope:agentscope:1.0.11'
 
 The all-in-one package includes these dependencies by default:
 
-- DashScope SDK (Qwen series models)
+- DashScope model support (Qwen series models, via native HTTP calls, no additional SDK required)
 - MCP SDK (Model Context Protocol)
 - Reactor Core, Jackson, SLF4J (base frameworks)
 
@@ -185,6 +185,7 @@ implementation 'io.agentscope:agentscope-core:1.0.11'
 |--------|---------|-------------------|
 | [agentscope-extensions-scheduler-common](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-scheduler-common) | Scheduler Common | `io.agentscope:agentscope-extensions-scheduler-common` |
 | [agentscope-extensions-scheduler-xxl-job](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-scheduler-xxl-job) | XXL-Job Scheduler | `io.agentscope:agentscope-extensions-scheduler-xxl-job` |
+| [agentscope-extensions-scheduler-quartz](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-scheduler-quartz) | Quartz Scheduler | `io.agentscope:agentscope-extensions-scheduler-quartz` |
 
 #### User Interface
 
@@ -224,6 +225,8 @@ Additional starters:
 |---------|---------|-------------------|
 | agentscope-a2a-spring-boot-starter | A2A Integration | `io.agentscope:agentscope-a2a-spring-boot-starter` |
 | agentscope-agui-spring-boot-starter | AG-UI Integration | `io.agentscope:agentscope-agui-spring-boot-starter` |
+| agentscope-chat-completions-web-starter | Chat Completions Web Integration | `io.agentscope:agentscope-chat-completions-web-starter` |
+| agentscope-nacos-spring-boot-starter | Nacos Integration | `io.agentscope:agentscope-nacos-spring-boot-starter` |
 
 ### Quarkus
 

docs/en/quickstart/key-concepts.md

@@ -72,9 +72,11 @@ Message is the most fundamental data structure in AgentScope, used for:
 
 | Field | Description |
 |-------|-------------|
+| `id` | Unique message identifier (auto-generated UUID) |
 | `name` | Sender's name, used to distinguish identities in multi-agent scenarios |
 | `role` | Role: `USER`, `ASSISTANT`, `SYSTEM`, or `TOOL` |
 | `content` | List of content blocks, supports multiple types |
+| `timestamp` | Message timestamp |
 | `metadata` | Optional structured data |
 
 **Content types**:
@@ -99,6 +101,8 @@ Messages returned by Agent contain additional metadata to help understand execut
 | Value | Description |
 |-------|-------------|
 | `MODEL_STOP` | Task completed normally |
+| `TOOL_CALLS` | Model returned tool calls (internal tools, framework continues execution) |
+| `STRUCTURED_OUTPUT` | Structured output completed |
 | `TOOL_SUSPENDED` | Tool needs external execution, waiting for result |
 | `REASONING_STOP_REQUESTED` | Paused by Hook during Reasoning phase (HITL) |
 | `ACTING_STOP_REQUESTED` | Paused by Hook during Acting phase (HITL) |
@@ -133,10 +137,11 @@ Msg imgMsg = Msg.builder()
 The Agent interface defines the core contract:
 
 ```java
-public interface Agent {
-    Mono<Msg> call(Msg msg);      // Process message and return response
-    Flux<Msg> stream(Msg msg);    // Stream response in real-time
-    void interrupt();             // Stop execution
+public interface Agent extends CallableAgent, StreamableAgent, ObservableAgent {
+    String getAgentId();
+    String getName();
+    void interrupt();
+    void interrupt(Msg msg);
 }
 ```
 
@@ -239,8 +244,13 @@ Formatter is responsible for converting AgentScope messages to the format requir
 - Identity handling in multi-agent scenarios
 
 **Built-in implementations**:
-- `DashScopeFormatter` - Alibaba Cloud DashScope (Qwen series)
-- `OpenAIFormatter` - OpenAI and compatible APIs
+- `DashScopeChatFormatter` - Alibaba Cloud DashScope (Qwen series)
+- `OpenAIChatFormatter` - OpenAI and compatible APIs
+- `AnthropicChatFormatter` - Anthropic (Claude series)
+- `GeminiChatFormatter` - Google Gemini
+- `OllamaChatFormatter` - Ollama local models
+- `DeepSeekFormatter` - DeepSeek
+- `GLMFormatter` - GLM (Zhipu)
 
 > Formatter is automatically selected based on Model type; manual configuration is usually not needed.
 
@@ -262,6 +272,9 @@ Hook provides extension points at key nodes of the ReAct loop through an event m
 | `PreActingEvent` | Before executing tool | ✓ |
 | `PostActingEvent` | After tool execution | ✓ |
 | `ActingChunkEvent` | During tool streaming output | - |
+| `PreSummaryEvent` | Before summary generation | ✓ |
+| `PostSummaryEvent` | After summary generation | ✓ |
+| `SummaryChunkEvent` | During summary streaming output | - |
 | `ErrorEvent` | When error occurs | - |
 
 **Hook Priority**: Hooks execute in priority order (lower value = higher priority), default is 100.
@@ -309,9 +322,10 @@ ReActAgent agent = ReActAgent.builder()
 
 **Problem solved**: Agent state such as conversation history and configuration needs to be saved and restored to support session persistence.
 
-AgentScope separates "initialization" from "state":
-- `saveState()` - Export current state as a serializable Map
-- `loadState()` - Restore from saved state
+AgentScope separates "initialization" from "state" through the `StateModule` interface:
+- `saveTo(Session, SessionKey)` - Save current state to Session
+- `loadFrom(Session, SessionKey)` - Restore state from Session
+- `loadIfExists(Session, SessionKey)` - Restore state from Session if it exists
 
 **Session** provides persistent storage across runs:
 

docs/en/task/a2a.md

@@ -160,8 +160,8 @@ ConfigurableAgentCard agentCard = new ConfigurableAgentCard.Builder()
     .description("Intelligent assistant")
     .version("1.0.0")
     .skills(List.of(
-        new AgentSkill("text-generation", "Text Generation"),
-        new AgentSkill("question-answering", "Q&A")))
+        AgentSkill.builder().name("text-generation").description("Text Generation").skillContent("").build(),
+        AgentSkill.builder().name("question-answering").description("Q&A").skillContent("").build()))
     .build();
 
 AgentScopeA2aServer.builder(agentBuilder)

docs/en/task/agent-config.md

@@ -254,10 +254,10 @@ In the `ReActAgent`'s reasoning phase (ReasoningPipeline), this configuration is
 **Default Configuration** (ExecutionConfig.MODEL_DEFAULTS):
 - Timeout: 5 minutes
 - Max attempts: 3 (initial + 2 retries)
-- Initial backoff: 1 second
-- Max backoff: 10 seconds
+- Initial backoff: 2 seconds
+- Max backoff: 30 seconds
 - Backoff multiplier: 2.0 (exponential)
-- Retry condition: all errors
+- Retry condition: retryable errors (429, 5xx, timeout, network IO errors)
 
 **Use Cases**:
 - Adjust model API timeout
@@ -460,7 +460,7 @@ Generally, there's no need to explicitly specify; the model will automatically s
 Provides the set of skills available to the Agent. It allows the Agent to load skills through tool functions and automatically injects skill hints via the Hook mechanism.
 
 ```java
-SkillBox skillBox = new SkillBox();
+SkillBox skillBox = new SkillBox(new Toolkit());
 .skillBox(skillBox)
 ```
 
@@ -563,7 +563,11 @@ public class ComprehensiveAgentExample {
     // 5. Define skill class
     public static class WeatherSkill extends AgentSkill {
         public WeatherSkill() {
-            super("weather", "weather", "weather", null);
+            super(AgentSkill.builder()
+                .name("weather")
+                .description("weather")
+                .skillContent("weather")
+                .build());
         }
     }
 
@@ -635,7 +639,7 @@ public class ComprehensiveAgentExample {
         // Step 5: Configure Skills
         // ============================================================
 
-        SkillBox skillBox = new SkillBox();
+        SkillBox skillBox = new SkillBox(new Toolkit());
         skillBox.registerSkill(new WeatherSkill());
 
         // ============================================================

docs/en/task/agent-skill.md

@@ -153,7 +153,7 @@ ReActAgent agent = ReActAgent.builder()
 ## Simplified Integration
 
 ```java
-SkillBox skillBox = new SkillBox();
+SkillBox skillBox = new SkillBox(new Toolkit());
 
 skillBox.registerSkill(dataSkill);
 

docs/en/task/hook.md

@@ -15,14 +15,17 @@ AgentScope Java uses a **unified event model** where all hooks implement the `on
 
 | Event Type            | Timing                    | Modifiable | Description                              |
 |-----------------------|---------------------------|------------|------------------------------------------|
-| PreCallEvent          | Before agent call         | ❌         | Before agent starts processing (notification-only)           |
+| PreCallEvent          | Before agent call         | ✅         | Before agent starts processing (modifiable input messages)           |
 | PostCallEvent         | After agent call          | ✅         | After agent completes response (can modify final message)           |
 | PreReasoningEvent     | Before reasoning          | ✅         | Before LLM reasoning (can modify input messages)          |
 | PostReasoningEvent    | After reasoning           | ✅         | After LLM reasoning (can modify reasoning result)            |
 | ReasoningChunkEvent   | During reasoning stream   | ❌         | Each chunk of streaming reasoning (notification-only)        |
 | PreActingEvent        | Before tool execution     | ✅         | Before tool execution (can modify tool parameters)                    |
 | PostActingEvent       | After tool execution      | ✅         | After tool execution (can modify tool result)                |
 | ActingChunkEvent      | During tool stream        | ❌         | Tool execution progress chunks (notification-only)    |
+| PreSummaryEvent       | Before summary            | ✅         | Before summary generation when max iterations reached         |
+| PostSummaryEvent      | After summary             | ✅         | After summary generation (can modify summary result)       |
+| SummaryChunkEvent     | During summary stream     | ❌         | Each chunk of streaming summary (notification-only)           |
 | ErrorEvent            | On error                  | ❌         | When errors occur (notification-only)                        |
 
 ## Creating Hooks

docs/en/task/mcp.md

@@ -157,9 +157,9 @@ String groupName = "filesystem";
 toolkit.createToolGroup(groupName, "Tools for operating system files", true);
 
 // Register MCP tools in a group
-toolkit.registration().mcpClient(mcpClient).group("groupName").apply();
+toolkit.registration().mcpClient(mcpClient).group(groupName).apply();
 
-// Create agent that only uses specific groups
+// Create agent with toolkit (only active group tools available)
 ReActAgent agent = ReActAgent.builder()
         .name("Assistant")
         .model(model)
@@ -222,7 +222,7 @@ McpClientWrapper client = McpClientBuilder.create("mcp")
         .block();
 ```
 
-> **Note**: Query parameters only apply to HTTP transports (SSE and HTTP). They are ignored for StdIO transport.
+> **Note**: Query parameters and HTTP headers only apply to HTTP transports (SSE and HTTP). They are silently ignored for StdIO transport.
 
 ### Synchronous vs Asynchronous Clients
 

docs/en/task/memory.md

@@ -316,4 +316,4 @@ mvn exec:java -Dexec.mainClass="io.agentscope.examples.advanced.ReMeExample"
 
 - [AutoContextMemory Documentation](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-autocontext-memory/README.md)
 - [Session Management](./session.md)
-- [ReActAgent Guide](./react-agent.md)
+- [ReActAgent Guide](./agent-config.md)