fix(docs): align documentation with actual codebase by LearningGp · Pull Request #1107 · agentscope-ai/agentscope-java

LearningGp · 2026-04-02T07:41:39Z

AgentScope-Java Version

1.0.11

Description

fix(docs): align documentation with actual codebase

Checklist

Please check the following items before code is ready to be reviewed.

Code has been formatted with mvn spotless:apply
All tests are passing (mvn test)
Javadoc comments are complete and follow project conventions
Related documentation has been updated (e.g. links, examples, etc.)
Code is ready for review

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

codecov · 2026-04-02T07:52:03Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR updates the English and Chinese documentation to match the current AgentScope Java (1.0.11) APIs and runtime behaviors, mainly correcting outdated code examples and capability matrices.

Changes:

Update doc code snippets to current APIs (e.g., Msg.builder().textContent(...), ReActAgent.builder().toolkit(...), new tool-choice classes).
Clarify/expand documented behaviors and capabilities (hooks/events, multimodal tool capabilities, model options, workflow defaults).
Fix/adjust cross-doc links and configuration notes to reflect the current module structure.

Reviewed changes

Copilot reviewed 38 out of 38 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/zh/task/tts.md	Update TTS examples to new `Msg` builder API and Toolkit-based tool registration
docs/zh/task/tool.md	Clarify streaming tools, add `list_directory`, update Toolkit defaults and suspend-resume example
docs/zh/task/studio.md	Clarify Studio runs as a frontend dev server
docs/zh/task/rag.md	Remove outdated RAG option (`enableOnlyForUserQueries`)
docs/zh/task/plan.md	Document `needUserConfirm` behavior and defaults
docs/zh/task/online-training.md	Update message creation API in example
docs/zh/task/model.md	Update model capability matrix and add DashScope/OpenAI option details
docs/zh/task/memory.md	Fix related-doc link to current agent config doc
docs/zh/task/mcp.md	Fix tool group variable usage and clarify HTTP-only params/headers behavior
docs/zh/task/hook.md	Update hook modifiability and add summary hook events
docs/zh/task/agent-skill.md	Update `SkillBox` construction to include Toolkit
docs/zh/task/agent-config.md	Update skill example to new `AgentSkill.builder()` style
docs/zh/task/a2a.md	Update AgentCard skill examples to builder pattern
docs/zh/quickstart/key-concepts.md	Align key concepts with current message fields, reasons, and agent interfaces
docs/zh/quickstart/installation.md	Update dependency/module listing notes
docs/zh/quickstart/agent.md	Align ReActAgent builder parameter list with current options
docs/zh/multi-agent/workflow.md	Clarify workflow example defaults and runner behavior
docs/zh/multi-agent/handoffs.md	Fix `AgentScopeAgent` import path
docs/zh/intro.md	Align intro claims with current architecture/modules (A2A, tracing, etc.)
docs/en/task/tts.md	Update TTS examples to new `Msg` builder API and Toolkit-based tool registration
docs/en/task/tool.md	Clarify streaming tools, add `list_directory`, update Toolkit defaults and suspend-resume example
docs/en/task/studio.md	Clarify Studio runs as a frontend dev server
docs/en/task/rag.md	Remove outdated RAG option (`enableOnlyForUserQueries`)
docs/en/task/plan.md	Document `needUserConfirm` behavior and defaults
docs/en/task/online-training.md	Update message creation API in example
docs/en/task/model.md	Update model capability matrix and add DashScope/OpenAI option details
docs/en/task/memory.md	Fix related-doc link to current agent config doc
docs/en/task/mcp.md	Fix tool group variable usage and clarify HTTP-only params/headers behavior
docs/en/task/hook.md	Update hook modifiability and add summary hook events
docs/en/task/agent-skill.md	Update `SkillBox` construction to include Toolkit
docs/en/task/agent-config.md	Update skill example (needs correction for compile validity)
docs/en/task/a2a.md	Update AgentCard skill examples to builder pattern
docs/en/quickstart/key-concepts.md	Align key concepts with current message fields, reasons, and agent interfaces
docs/en/quickstart/installation.md	Update dependency/module listing notes
docs/en/quickstart/agent.md	Align ReActAgent builder parameter list with current options
docs/en/multi-agent/workflow.md	Clarify workflow example defaults and runner behavior
docs/en/multi-agent/handoffs.md	Fix `AgentScopeAgent` import path and add descriptions
docs/en/intro.md	Align intro claims with current architecture/modules (A2A, tracing, etc.)

Copilot · 2026-04-02T07:52:31Z

docs/en/task/tool.md

 ```java
 toolkit.registerMetaTool();
-// Agent can call "reset_equipped_tools" to activate/deactivate tool groups
+// Agent can call "reset_equipped_tools" to activate (reset to specified set) tool groups


reset_equipped_tools does not actually “reset to the specified set” of tool groups. In MetaToolFactory#resetEquippedToolsImpl, it only calls updateToolGroups(toActivate, true) and never deactivates other active groups, so the comment here is misleading. Please reword to match current semantics (activate these groups without disabling others) or adjust the implementation if true reset semantics are intended.

Suggested change

// Agent can call "reset_equipped_tools" to activate (reset to specified set) tool groups

// Agent can call "reset_equipped_tools" to activate the specified tool groups (without disabling others)

Copilot · 2026-04-02T07:52:32Z

docs/zh/task/tool.md

 ```java
 toolkit.registerMetaTool();
-// Agent 可调用 "reset_equipped_tools" 激活/停用工具组
+// Agent 可调用 "reset_equipped_tools" 激活指定的工具组（重置为指定的工具组集合）
 ```


这里对 reset_equipped_tools 的描述“重置为指定的工具组集合”与实际实现不一致：MetaToolFactory#resetEquippedToolsImpl 只会调用 updateToolGroups(toActivate, true) 激活指定组，并不会停用其他已激活的组。建议将说明改为“激活指定组（不影响其他组）”，或如果确实需要 reset 语义则同步调整实现。

Copilot · 2026-04-02T07:52:32Z

docs/zh/task/agent-config.md


-        SkillBox skillBox = new SkillBox();
+        SkillBox skillBox = new SkillBox(new Toolkit());
        skillBox.registerSkill(new WeatherSkill());


该示例在当前改动后无法编译：上面把技能改成了 AgentSkill weatherSkill = ...（非 static），但在 main 里仍然 registerSkill(new WeatherSkill())，与前面的定义不一致。建议在 main 中直接构建并注册 AgentSkill（并确保可访问/作用域正确），或保留 WeatherSkill extends AgentSkill 的写法并在此处注册对应实例。

Suggested change

skillBox.registerSkill(new WeatherSkill());

skillBox.registerSkill(weatherSkill);

Copilot · 2026-04-02T07:52:32Z

docs/en/task/a2a.md

+        AgentSkill.builder().name("text-generation").description("Text Generation").skillContent("").build(),
+        AgentSkill.builder().name("question-answering").description("Q&A").skillContent("").build()))


AgentSkill requires non-empty skillContent (the constructor throws if it’s null/empty). Using .skillContent("") here will fail at runtime; please provide at least a minimal placeholder (e.g., a short markdown header/instructions) or show how to load skill content properly.

Suggested change

AgentSkill.builder().name("text-generation").description("Text Generation").skillContent("").build(),

AgentSkill.builder().name("question-answering").description("Q&A").skillContent("").build()))

AgentSkill.builder().name("text-generation").description("Text Generation").skillContent("# Text generation skill\nProvide helpful, coherent text based on user instructions.").build(),

AgentSkill.builder().name("question-answering").description("Q&A").skillContent("# Q&A skill\nAnswer user questions concisely using available information.").build()))

Copilot · 2026-04-02T07:52:33Z

docs/zh/task/a2a.md

+        AgentSkill.builder().name("text-generation").description("文本生成").skillContent("").build(),
+        AgentSkill.builder().name("question-answering").description("问答").skillContent("").build()))


AgentSkill 的 skillContent 不能为空（构造函数会对空字符串抛异常）。这里使用 .skillContent("") 会在运行时失败；建议提供最小可用的占位内容（例如简单的 markdown 说明），或展示如何正确加载/填写技能内容。

Suggested change

AgentSkill.builder().name("text-generation").description("文本生成").skillContent("").build(),

AgentSkill.builder().name("question-answering").description("问答").skillContent("").build()))

AgentSkill.builder().name("text-generation").description("文本生成").skillContent("# Text generation skill").build(),

AgentSkill.builder().name("question-answering").description("问答").skillContent("# Question answering skill").build()))

Copilot · 2026-04-02T07:52:33Z

docs/en/task/agent-config.md

+            super(AgentSkill.builder()
+                .name("weather")
+                .description("weather")
+                .skillContent("weather")
+                .build());


This example won’t compile: WeatherSkill extends AgentSkill, but AgentSkill has no constructor accepting an AgentSkill instance, so super(AgentSkill.builder()...build()) is invalid. Use the existing AgentSkill(String name, String description, String skillContent, Map<String,String> resources) constructor, or remove the subclass and just register the built AgentSkill directly.

Suggested change

super(AgentSkill.builder()

.name("weather")

.description("weather")

.skillContent("weather")

.build());

super("weather", "weather", "weather", null);

LearningGp and others added 2 commits April 2, 2026 15:16

fix(docs): align Chinese documentation with actual codebase

1af1cf9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(docs): sync English documentation with Chinese doc fixes

4aba328

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

LearningGp requested review from a team and Copilot April 2, 2026 07:41

Copilot started reviewing on behalf of LearningGp April 2, 2026 07:42 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(docs): align documentation with actual codebase #1107

fix(docs): align documentation with actual codebase #1107
LearningGp wants to merge 2 commits intoagentscope-ai:mainfrom
LearningGp:fix/doc

LearningGp commented Apr 2, 2026

Uh oh!

codecov bot commented Apr 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	// Agent can call "reset_equipped_tools" to activate (reset to specified set) tool groups
	// Agent can call "reset_equipped_tools" to activate the specified tool groups (without disabling others)

	skillBox.registerSkill(new WeatherSkill());
	skillBox.registerSkill(weatherSkill);

		AgentSkill.builder().name("text-generation").description("Text Generation").skillContent("").build(),
		AgentSkill.builder().name("question-answering").description("Q&A").skillContent("").build()))

Conversation

LearningGp commented Apr 2, 2026

AgentScope-Java Version

Description

Checklist

Uh oh!

codecov bot commented Apr 2, 2026

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants