[Feat]: enhanced subagent support for HarnessAgent#1384
Open
chickenlj wants to merge 2 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR enhances HarnessAgent subagent orchestration by refactoring subagent configuration into a more expressive declaration model, adding workspace-backed async task persistence (session-scoped), and updating docs + the Sphinx/JupyterBook site chrome to better organize the documentation.
Changes:
- Replace
SubagentSpecwithSubagentDeclaration+WorkspaceMode, update Markdown declaration parsing, and expand subagent builder/test coverage (including the 5-row decision table and GP mirroring). - Make async subagent tasks session-scoped and durable via workspace storage (
agents/<agentId>/tasks/<sessionId>.json), and update tools/hooks to surface task state each turn. - Rework docs navigation (top tabs + sidebar filtering) and add site-level notice/header templates + supporting assets; expand Harness docs structure in TOC.
Reviewed changes
Copilot reviewed 54 out of 55 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/zh/integration/overview.md | Adds stub Integration overview page (ZH). |
| docs/zh/harness/workspace.md | Updates workspace structure docs to reflect subagent declarations and isolated runtime roots. |
| docs/zh/harness/subagent.md | Major update: declaration/definition/runtime model, decision table, async task semantics, API examples. |
| docs/zh/harness/sandbox/index.md | Adjusts sandbox docs links/wording and multi-replica guard guidance. |
| docs/zh/harness/quickstart/index.md | Adds Harness quickstart stub (ZH). |
| docs/zh/harness/overview.md | Fixes Sandbox doc links to new sandbox index path. |
| docs/zh/harness/filesystem.md | Updates Sandbox references to new sandbox index path. |
| docs/zh/harness/example/index.md | Adds examples stub (ZH). |
| docs/zh/harness/architecture.md | Updates Sandbox references and refreshes subagent source description. |
| docs/zh/community/overview.md | Adds stub Community overview page (ZH). |
| docs/zh/blogs/index.md | Adds stub Blogs landing page (ZH). |
| docs/en/integration/overview.md | Adds stub Integration overview page (EN). |
| docs/en/harness/overview.md | Adds EN hub page pointing to ZH Harness docs. |
| docs/en/community/overview.md | Adds stub Community overview page (EN). |
| docs/en/blogs/index.md | Adds stub Blogs landing page (EN). |
| docs/en/agentscope_java.egg-info/top_level.txt | Adds Python packaging metadata under docs (likely generated artifact). |
| docs/en/agentscope_java.egg-info/SOURCES.txt | Adds Python packaging metadata under docs (likely generated artifact). |
| docs/en/agentscope_java.egg-info/requires.txt | Adds Python packaging metadata under docs (likely generated artifact). |
| docs/en/agentscope_java.egg-info/PKG-INFO | Adds Python packaging metadata under docs (likely generated artifact). |
| docs/en/agentscope_java.egg-info/dependency_links.txt | Adds Python packaging metadata under docs (likely generated artifact). |
| docs/_toc.yml | Adds new EN captions and expands ZH Harness section structure. |
| docs/_templates/top-tabs.html | Adds top tab navigation template (lang-aware). |
| docs/_templates/page.html | Wraps Furo page template to inject new header/notice chrome. |
| docs/_templates/language-switch.html | Simplifies language switch markup and delegates behavior to JS. |
| docs/_templates/docs-site-notice.html | Adds configurable site-wide notice bar template. |
| docs/_templates/docs-site-header.html | Adds new docs header (brand + tabs + search/theme/lang actions). |
| docs/_static/tabs.js | Implements tab activation, sidebar filtering, and language-menu behavior. |
| docs/_static/notice-bar.js | Adds dismiss logic for the notice bar (localStorage-backed). |
| docs/_static/custom.css | Adds styling for header, tabs, notice bar, and responsive behavior. |
| docs/_sphinx_extensions/root_index_notice.py | Adds Sphinx extension to patch root redirect stub so notice/header can render. |
| docs/_config.yml | Registers new templates/assets/extensions and configures tabs/notice context. |
| agentscope-harness/src/test/java/io/agentscope/harness/agent/subagent/task/WorkspaceTaskRepositoryTest.java | Adds comprehensive tests for workspace-backed task persistence + routing. |
| agentscope-harness/src/test/java/io/agentscope/harness/agent/sandbox/SandboxManagerIsolationTest.java | Adds test ensuring USER-scope guard uses user isolation key. |
| agentscope-harness/src/test/java/io/agentscope/harness/agent/HarnessAgentTest.java | Updates subagent Markdown naming rules; adds decision table + mirroring + allowlist tests. |
| agentscope-harness/src/test/java/io/agentscope/harness/agent/HarnessAgentModelStringTest.java | Updates subagent model override test to SubagentDeclaration. |
| agentscope-harness/src/test/java/io/agentscope/harness/agent/HarnessAgentIntegrationExampleTest.java | Updates integration example tests for filename-derived subagent IDs. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/WorkspaceManager.java | Adds task record read/write/list APIs with JSON persistence + per-file locking. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/WorkspaceConstants.java | Adds TASKS_DIR, removes legacy SUBAGENT_YML. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/TaskTool.java | Scopes task ops by session via RuntimeContext; improves guidance and fallback messaging. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/AgentSpawnTool.java | Scopes async tasks by parent session; propagates userId to child invocation. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/WorkspaceMode.java | Introduces workspace mode enum + decision table documentation. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/task/WorkspaceTaskRepository.java | Implements workspace-backed task repository with local overlay + cross-node fallback. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/task/TaskRepository.java | Makes TaskRepository session-scoped (API change). |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/task/TaskRecord.java | Adds persisted task record schema (Jackson). |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/task/DefaultTaskRepository.java | Updates in-memory repository to new session-scoped interface (session ignored). |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/SubagentSpec.java | Removes legacy SubagentSpec. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/SubagentDeclaration.java | Adds new declaration model + builder validation and allowlist semantics. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/DefaultAgentManager.java | Adds userId propagation when invoking HarnessAgent children. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/subagent/AgentSpecLoader.java | Refactors Markdown loader to produce SubagentDeclarations (filename-derived IDs). |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/sandbox/SandboxExecutionGuard.java | Updates guard docs to emphasize USER scope in multi-replica deployments. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/hook/SubagentsHook.java | Injects per-turn async task summary; passes session/user context through tools. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java | Core refactor: declarations, workspace decision table, workspace task repo default, GP mirroring, compaction hook exposure. |
| agentscope-harness/src/main/java/io/agentscope/harness/agent/filesystem/spec/RemoteFilesystemSpec.java | Routes agents/<agentId>/tasks/ to shared storage in RemoteFilesystem mode. |
| agentscope-examples/harness-examples/harness-example-sandbox/README.md | Updates doc link to new sandbox index page. |
| .gitignore | Adds .venv/ ignore. |
Comment on lines
+254
to
+263
| private static Path resolvePath(String pathStr, Path mainWorkspace) { | ||
| Path p = Path.of(pathStr); | ||
| if (p.isAbsolute()) { | ||
| return p; | ||
| } | ||
| if (mainWorkspace != null) { | ||
| Path resolved = mainWorkspace.resolve(p).normalize(); | ||
| return resolved; | ||
| } | ||
| return p; |
Collaborator
Author
There was a problem hiding this comment.
This kind of boundary escape check would be implemented later.
Comment on lines
+1765
to
1768
| // Apply tools allowlist: retain only the requested tool names. | ||
| if (!decl.getTools().isEmpty()) { | ||
| sub.toolkit(new Toolkit()); | ||
| } |
Comment on lines
+254
to
+275
| private void updateStatus( | ||
| String sessionId, String taskId, TaskStatus status, String result, String error) { | ||
| Optional<TaskRecord> existing = | ||
| workspaceManager.readTaskRecord(parentAgentId, sessionId, taskId); | ||
| TaskRecord record = | ||
| existing.orElseGet( | ||
| () -> { | ||
| TaskRecord r = new TaskRecord(); | ||
| r.setTaskId(taskId); | ||
| r.setParentAgentId(parentAgentId); | ||
| r.setParentSessionId(sessionId); | ||
| return r; | ||
| }); | ||
| record.setStatus(status); | ||
| if (result != null) { | ||
| record.setResult(result); | ||
| } | ||
| if (error != null) { | ||
| record.setErrorMessage(error); | ||
| } | ||
| persistRecord(sessionId, record); | ||
| } |
Comment on lines
+349
to
+372
| public Optional<TaskRecord> readTaskRecord(String agentId, String sessionId, String taskId) { | ||
| if (agentId == null | ||
| || agentId.isBlank() | ||
| || sessionId == null | ||
| || sessionId.isBlank() | ||
| || taskId == null | ||
| || taskId.isBlank()) { | ||
| return Optional.empty(); | ||
| } | ||
| String rel = taskRecordPath(agentId, sessionId); | ||
| Map<String, TaskRecord> map = readTaskMap(rel); | ||
| return Optional.ofNullable(map.get(taskId)); | ||
| } | ||
|
|
||
| /** | ||
| * Returns all {@link TaskRecord}s for the given agent and session, in insertion order. | ||
| */ | ||
| public Collection<TaskRecord> listTaskRecords(String agentId, String sessionId) { | ||
| if (agentId == null || agentId.isBlank() || sessionId == null || sessionId.isBlank()) { | ||
| return Collections.emptyList(); | ||
| } | ||
| String rel = taskRecordPath(agentId, sessionId); | ||
| return List.copyOf(readTaskMap(rel).values()); | ||
| } |
Comment on lines
+1
to
+7
| pyproject.toml | ||
| setup.py | ||
| en/agentscope_java.egg-info/PKG-INFO | ||
| en/agentscope_java.egg-info/SOURCES.txt | ||
| en/agentscope_java.egg-info/dependency_links.txt | ||
| en/agentscope_java.egg-info/requires.txt | ||
| en/agentscope_java.egg-info/top_level.txt No newline at end of file |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request refactors how subagents are declared and managed in the
HarnessAgentclass, improving extensibility and clarity around subagent configuration. The most significant changes involve replacingSubagentSpecwithSubagentDeclaration, updating related builder methods, and enhancing subagent instantiation logic. Additional improvements include exposing the compaction hook for testing and refining documentation and comments for clarity.