类class io.agentscope.harness.agent.subagent 2.x

SubagentDeclaration

public final class SubagentDeclaration

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:66–701

子智能体 Declaration，支持智能体之间的发现、委派与协作。位于 io.agentscope.harness.agent.subagent 包。核心成员包括 builder、getName、getDescription、getWorkspaceMode、getWorkspacePath、getInlineAgentsBody。

Declares a subagent: its identity, workspace resolution strategy, and optional capability allowlist.

A declaration binds to exactly one of two source modes:

Definition workspace — #getWorkspacePath() points to a workspace directory containing at least AGENTS.md. That file is used as the subagent's system-prompt body. Skills, knowledge, and MEMORY in the definition directory are available when the WorkspaceMode is WorkspaceMode#ISOLATED.
Remote HTTP — #getUrl() points to an AgentScope task HTTP server. No local definition workspace or inline body; the subagent runs out-of-process. Mutually exclusive with definition workspace and inline body.

The three source modes are mutually exclusive: at most one of Builder#workspace(Path), a non-blank Builder#inlineAgentsBody(String), or a non-blank Builder#url(String) may be set.

Workspace resolution follows the five-row decision table in WorkspaceMode.

The tools list, when non-empty, acts as an allowlist filter for inherited parent tools: only inherited tools whose names appear in the list are kept. Child-local tool registrations may still be added by the child builder.

Obtain instances via #builder().

Example (programmatic):

`SubagentDeclaration decl = SubagentDeclaration.builder()
.name("code-reviewer")
.description("Reviews code for security, performance, and readability issues.")
.workspace(Path.of("./defs/code-reviewer"))
.workspaceMode(WorkspaceMode.ISOLATED)
.model("qwen3-max")
.tools(List.of("read_file", "grep_files", "edit_file"))
.build();
`

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`Mode`	枚举enum	定义模式相关取值的枚举。 Whether a declaration can be used as a top-level primary agent, only as a delegated subagent, or both.
`Builder`	类class	构建器，用于构建并配置目标实例。 A class in io.agentscope.harness.agent.subagent that supports discovery, delegation and collaboration between agents.

方法摘要Method Summary

方法Method	说明Description
`public static` `Builder builder()` static	用于新的构建器的工厂方法。 Factory method for a new builder.
`public String getName()`	获取名称。 Unique name / agent-id used to reference this subagent.
`public String getDescription()`	获取 `getDescription`。 Human-readable description; the main agent uses this to decide when to delegate.
`public` `WorkspaceMode getWorkspaceMode()`	获取工作区模式。 Workspace resolution strategy.
`public Path getWorkspacePath()`	获取工作区路径。 Path to the definition workspace directory (contains at least `AGENTS.md`).
`public String getInlineAgentsBody()`	获取 `getInlineAgentsBody`。 Inline system-prompt body used when `#getWorkspacePath()` is `null`.
`public String getModel()`	获取模型。 Optional model override (e.g.
`public int getMaxIters()` deprecated	获取最大迭代次数。 Maximum reasoning iterations.
`public int getSteps()`	获取步骤。 Maximum reasoning iterations (default 10).
`public Double getTemperature()`	获取 `getTemperature`。 Optional sampling temperature override (e.g.
`public Double getTopP()`	获取 `getTopP`。 Optional nucleus-sampling override.
`public String getVariant()`	获取 `getVariant`。 Optional model variant identifier (e.g.
`public` `Mode getMode()`	获取模式。 The `Mode` of this declaration.
`public boolean isHidden()`	判断是否隐藏。 Whether this declaration should be hidden from the LLM's view of available subagents.
`public boolean isPersistSession()`	判断是否 `isPersistSession`。 Whether the subagent's session state should persist across parent calls.
`public boolean isInheritParentPermissions()`	判断是否 `isInheritParentPermissions`。 Whether the subagent inherits parent DENY permission rules.
`public Boolean getExposeToUser()`	获取 `getExposeToUser`。 Per-type policy for exposing spawned instances of this subagent as user-addressable threads.
`public Boolean getEnablePendingToolRecovery()`	获取 `getEnablePendingToolRecovery`。 Recovery policy for orphaned tool calls in an automatically constructed local subagent.
`public List<String> getTools()`	获取工具。 Optional tool allowlist.
`public List<String> getSkills()`	获取技能。 Returns the skills.
`public boolean isRemote()`	判断是否远程。 Returns `true` when this declaration targets a remote task HTTP server.
`public String getUrl()`	远程任务服务端的基类 URL。 Base URL of the remote task server.
`public Map<String, String> getHeaders()`	获取请求头。 Optional HTTP headers (e.g.
`public boolean isRemoteStreaming()`	判断是否远程流式。 Whether remote subagent events (text deltas, tool calls, confirmations) should be streamed back into the parent's live event stream when one is present.
`public` `RemoteStreamDetail getRemoteStreamDetail()`	获取远程流详情。 How much of the remote event stream to forward.
`public` `RemoteAskPolicy getRemoteAskPolicy()`	获取 `getRemoteAskPolicy`。 Policy for resolving remote HITL (tool-confirmation) requests.
`public Map<String, Object> getRemoteContextAttributes()`	获取远程上下文属性。 Static attributes sent as `context.attributes` with every remote submission, for the remote server to route on or expose to its agent.
`public boolean hasDefinitionWorkspace()`	判断是否具有定义工作区。 Returns `true` when this declaration points at an external definition workspace.

方法详情Method Detail

builder

public static Builder builder()

static

用于新的构建器的工厂方法。

Factory method for a new builder.

返回Returns Builder

返回当前实例，以支持链式调用。Returns the current instance for chaining.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:161–163

getName

public String getName()

获取名称。

Unique name / agent-id used to reference this subagent.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:166–168

getDescription

public String getDescription()

获取 getDescription。

Human-readable description; the main agent uses this to decide when to delegate.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:171–173

getWorkspaceMode

public WorkspaceMode getWorkspaceMode()

获取工作区模式。

Workspace resolution strategy.

返回Returns WorkspaceMode

返回WorkspaceMode。Returns workspace mode.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:179–181

getWorkspacePath

public Path getWorkspacePath()

获取工作区路径。

Path to the definition workspace directory (contains at least AGENTS.md).

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:188–190

getInlineAgentsBody

public String getInlineAgentsBody()

获取 getInlineAgentsBody。

Inline system-prompt body used when #getWorkspacePath() is null.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:196–198

getModel

public String getModel()

获取模型。

Optional model override (e.g.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:204–206

getMaxIters

public int getMaxIters()

deprecated

获取最大迭代次数。

Maximum reasoning iterations.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。since Phase A — use `#getSteps()`. Returns the same value; kept for source compatibility with callers built before the `steps` field existed.

返回Returns int

返回数值结果。Returns a numeric result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:214–217

getSteps

public int getSteps()

获取步骤。

Maximum reasoning iterations (default 10).

返回Returns int

返回数值结果。Returns a numeric result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:220–222

getTemperature

public Double getTemperature()

获取 getTemperature。

Optional sampling temperature override (e.g.

返回Returns Double

返回数值结果。Returns a numeric result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:229–231

getTopP

public Double getTopP()

获取 getTopP。

Optional nucleus-sampling override.

返回Returns Double

返回数值结果。Returns a numeric result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:237–239

getVariant

public String getVariant()

获取 getVariant。

Optional model variant identifier (e.g.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:246–248

getMode

public Mode getMode()

获取模式。

The Mode of this declaration.

返回Returns Mode

返回模式。Returns mode.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:254–256

isHidden

public boolean isHidden()

判断是否隐藏。

Whether this declaration should be hidden from the LLM's view of available subagents.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:263–265

isPersistSession

public boolean isPersistSession()

判断是否 isPersistSession。

Whether the subagent's session state should persist across parent calls.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:272–274

isInheritParentPermissions

public boolean isInheritParentPermissions()

判断是否 isInheritParentPermissions。

Whether the subagent inherits parent DENY permission rules.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:281–283

getExposeToUser

public Boolean getExposeToUser()

获取 getExposeToUser。

Per-type policy for exposing spawned instances of this subagent as user-addressable threads.

返回Returns Boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:301–303

getEnablePendingToolRecovery

public Boolean getEnablePendingToolRecovery()

获取 getEnablePendingToolRecovery。

Recovery policy for orphaned tool calls in an automatically constructed local subagent.

返回Returns Boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:310–312

getTools

public List<String> getTools()

获取工具。

Optional tool allowlist.

返回Returns List<String>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:318–320

getSkills

public List<String> getSkills()

获取技能。

Returns the skills.

返回Returns List<String>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:322–324

isRemote

public boolean isRemote()

判断是否远程。

Returns true when this declaration targets a remote task HTTP server.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:327–329

getUrl

public String getUrl()

远程任务服务端的基类 URL。

Base URL of the remote task server.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:334–336

getHeaders

public Map<String, String> getHeaders()

获取请求头。

Optional HTTP headers (e.g.

返回Returns Map<String, String>

返回映射。Returns map.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:342–344

isRemoteStreaming

public boolean isRemoteStreaming()

判断是否远程流式。

Whether remote subagent events (text deltas, tool calls, confirmations) should be streamed back into the parent's live event stream when one is present.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:351–353

getRemoteStreamDetail

public RemoteStreamDetail getRemoteStreamDetail()

获取远程流详情。

How much of the remote event stream to forward.

返回Returns RemoteStreamDetail

返回RemoteStreamDetail。Returns remote stream detail.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:362–364

getRemoteAskPolicy

public RemoteAskPolicy getRemoteAskPolicy()

获取 getRemoteAskPolicy。

Policy for resolving remote HITL (tool-confirmation) requests.

返回Returns RemoteAskPolicy

返回RemoteAskPolicy。Returns remote ask policy.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:371–373

getRemoteContextAttributes

public Map<String, Object> getRemoteContextAttributes()

获取远程上下文属性。

Static attributes sent as context.attributes with every remote submission, for the remote server to route on or expose to its agent.

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:380–382

hasDefinitionWorkspace

public boolean hasDefinitionWorkspace()

判断是否具有定义工作区。

Returns true when this declaration points at an external definition workspace.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:385–387

嵌套类详情Nested Class Detail

Mode

public enum Mode

定义模式相关取值的枚举。位于 io.agentscope.harness.agent.subagent 包。核心成员包括 PRIMARY、SUBAGENT、ALL。

Whether a declaration can be used as a top-level primary agent, only as a delegated subagent, or both.

The io.agentscope.harness.agent.subagent.DefaultAgentManager#createAgentIfPresent path rejects spawn requests for #PRIMARY-only declarations so they can never be invoked as workers; conversely, top-level launchers may want to reject #SUBAGENT declarations as entry points (current core does not own that check — top-level launch goes through HarnessAgent.builder() directly, not through a declaration).

Builder

public static final class Builder

构建器，用于构建并配置目标实例。位于 io.agentscope.harness.agent.subagent 包。核心成员包括 name、description、workspaceMode、workspace、inlineAgentsBody、model。

A class in io.agentscope.harness.agent.subagent that supports discovery, delegation and collaboration between agents. Declared in io.agentscope.harness.agent.subagent.