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

Builder

public static final class Builder

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:393–700

构建器，用于构建并配置目标实例。位于 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.

方法摘要Method Summary

方法Method	说明Description
`public` `Builder name(String name)`	设置名称。 Sets the unique name / agent-id for this subagent (required).
`public` `Builder description(String description)`	设置该配置项。 Sets the human-readable description the orchestrator uses to decide when to delegate (required).
`public` `Builder workspaceMode(WorkspaceMode mode)`	设置工作区模式。 Sets the workspace resolution mode.
`public` `Builder workspace(Path workspacePath)`	设置工作区。 Points this declaration at an external definition workspace.
`public` `Builder inlineAgentsBody(String body)`	设置该配置项。 Sets the inline system-prompt body for lightweight subagents that do not need a dedicated definition workspace.
`public` `Builder model(String model)`	设置模型。 Optional model override resolved via `io.agentscope.core.model.ModelRegistry`.
`public` `Builder maxIters(int maxIters)` deprecated	设置最大迭代次数。 Maximum reasoning iterations (default 10).
`public` `Builder steps(int steps)`	设置步骤。 Maximum reasoning iterations (default 10).
`public` `Builder temperature(Double temperature)`	设置该配置项。 Optional sampling temperature override.
`public` `Builder topP(Double topP)`	设置该配置项。 Optional nucleus-sampling (top-p) override.
`public` `Builder variant(String variant)`	设置该配置项。 Optional model-variant identifier (e.g.
`public` `Builder mode(Mode mode)`	设置`Mode`。 Sets the `Mode`.
`public` `Builder hidden(boolean hidden)`	设置隐藏。 Hide this declaration from the LLM's available-subagent list.
`public` `Builder persistSession(boolean persistSession)`	设置该配置项。 When `true`, the subagent's spawn key is derived deterministically from (parentSessionId, agentId, label), enabling state recovery across parent calls and process restarts.
`public` `Builder inheritParentPermissions(boolean inheritParentPermissions)`	设置该配置项。 When `true` (default), parent DENY permission rules are propagated to the child at spawn time.
`public` `Builder exposeToUser(Boolean exposeToUser)`	设置该配置项。 Per-type policy for exposing spawned instances as user-addressable threads.
`public` `Builder enablePendingToolRecovery(Boolean enable)`	启用该配置。 Overrides pending-tool recovery for this local subagent.
`public` `Builder tools(List<String> tools)`	设置工具。 Tool allowlist: when non-empty, only inherited parent tools with listed names are kept.
`public` `Builder skills(List<String> skills)`	设置技能。 Performs the skills operation.
`public` `Builder url(String url)`	设置URL。 Remote task server base URL.
`public` `Builder headers(Map<String, String> headers)`	设置请求头。 Optional HTTP headers for the remote task server (e.g.
`public` `Builder remoteStreaming(Boolean remoteStreaming)`	设置远程流式。 Whether remote subagent events should be streamed back into the parent's event stream.
`public` `Builder remoteStreamDetail(RemoteStreamDetail remoteStreamDetail)`	设置远程流详情。 How much of the remote event stream to forward.
`public` `Builder remoteAskPolicy(RemoteAskPolicy remoteAskPolicy)`	设置该配置项。 Policy for resolving remote HITL confirmations.
`public` `Builder remoteContextAttributes(Map<String, Object> remoteContextAttributes)`	设置远程上下文属性。 Static attributes sent as `context.attributes` with every submission to this remote subagent (e.g.
`public` `SubagentDeclaration build()`	构建`SubagentDeclaration`。 Builds the `SubagentDeclaration`.

方法详情Method Detail

name

public Builder name(String name)

设置名称。

Sets the unique name / agent-id for this subagent (required).

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:423–426

description

public Builder description(String description)

设置该配置项。

Sets the human-readable description the orchestrator uses to decide when to delegate (required).

参数Parameters

名称Name	类型Type	说明Description
`description`	String	描述（类型 `String`）。The description.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:432–435

workspaceMode

public Builder workspaceMode(WorkspaceMode mode)

设置工作区模式。

Sets the workspace resolution mode.

参数Parameters

名称Name	类型Type	说明Description
`mode`	WorkspaceMode	模式（类型 `WorkspaceMode`）。workspace mode; `null` is treated as `WorkspaceMode#ISOLATED`

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:442–445

workspace

public Builder workspace(Path workspacePath)

设置工作区。

Points this declaration at an external definition workspace.

参数Parameters

名称Name	类型Type	说明Description
`workspacePath`	Path	工作区路径（类型 `Path`）。absolute path, or path relative to `mainWorkspace` when set via a Markdown front matter file

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:456–459

inlineAgentsBody

public Builder inlineAgentsBody(String body)

设置该配置项。

Sets the inline system-prompt body for lightweight subagents that do not need a dedicated definition workspace.

参数Parameters

名称Name	类型Type	说明Description
`body`	String	正文（类型 `String`）。the system-prompt body text (Markdown); may be `null` or blank

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:469–472

model

public Builder model(String model)

设置模型。

Optional model override resolved via io.agentscope.core.model.ModelRegistry.

参数Parameters

名称Name	类型Type	说明Description
`model`	String	模型实例（类型 `String`）。The model.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:478–481

maxIters

public Builder maxIters(int maxIters)

deprecated

设置最大迭代次数。

Maximum reasoning iterations (default 10).

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。since Phase A — use `#steps(int)`. Equivalent in behaviour.

参数Parameters

名称Name	类型Type	说明Description
`maxIters`	int	最大迭代次数（类型 `int`）。The max iters.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:488–492

steps

public Builder steps(int steps)

设置步骤。

Maximum reasoning iterations (default 10).

参数Parameters

名称Name	类型Type	说明Description
`steps`	int	步骤（类型 `int`）。The steps.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:495–498

temperature

public Builder temperature(Double temperature)

设置该配置项。

Optional sampling temperature override.

参数Parameters

名称Name	类型Type	说明Description
`temperature`	Double	temperature（类型 `Double`）。The temperature.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:504–507

topP

public Builder topP(Double topP)

设置该配置项。

Optional nucleus-sampling (top-p) override.

参数Parameters

名称Name	类型Type	说明Description
`topP`	Double	top P（类型 `Double`）。The top p.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:513–516

variant

public Builder variant(String variant)

设置该配置项。

Optional model-variant identifier (e.g.

参数Parameters

名称Name	类型Type	说明Description
`variant`	String	variant（类型 `String`）。The variant.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:523–526

mode

public Builder mode(Mode mode)

设置Mode。

Sets the Mode.

参数Parameters

名称Name	类型Type	说明Description
`mode`	Mode	模式（类型 `Mode`）。The mode.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:531–534

hidden

public Builder hidden(boolean hidden)

设置隐藏。

Hide this declaration from the LLM's available-subagent list.

参数Parameters

名称Name	类型Type	说明Description
`hidden`	boolean	隐藏（类型 `boolean`）。The hidden.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:539–542

persistSession

public Builder persistSession(boolean persistSession)

设置该配置项。

When true, the subagent's spawn key is derived deterministically from (parentSessionId, agentId, label), enabling state recovery across parent calls and process restarts.

参数Parameters

名称Name	类型Type	说明Description
`persistSession`	boolean	persist 会话（类型 `boolean`）。The persist session.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:549–552

inheritParentPermissions

public Builder inheritParentPermissions(boolean inheritParentPermissions)

设置该配置项。

When true (default), parent DENY permission rules are propagated to the child at spawn time.

参数Parameters

名称Name	类型Type	说明Description
`inheritParentPermissions`	boolean	inherit 父级权限（类型 `boolean`）。The inherit parent permissions.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:559–562

exposeToUser

public Builder exposeToUser(Boolean exposeToUser)

设置该配置项。

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

参数Parameters

名称Name	类型Type	说明Description
`exposeToUser`	Boolean	expose 到用户（类型 `Boolean`）。The expose to user.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:571–574

enablePendingToolRecovery

public Builder enablePendingToolRecovery(Boolean enable)

启用该配置。

Overrides pending-tool recovery for this local subagent.

参数Parameters

名称Name	类型Type	说明Description
`enable`	Boolean	启用（类型 `Boolean`）。whether to enable recovery, or `null` to inherit

返回Returns Builder

返回当前实例，以支持链式调用。this builder

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:583–586

tools

public Builder tools(List<String> tools)

设置工具。

Tool allowlist: when non-empty, only inherited parent tools with listed names are kept.

参数Parameters

名称Name	类型Type	说明Description
`tools`	List<String>	工具列表（类型 `List`）。The tools.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:592–595

skills

public Builder skills(List<String> skills)

设置技能。

Performs the skills operation.

参数Parameters

名称Name	类型Type	说明Description
`skills`	List<String>	技能（类型 `List`）。The skills.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:597–600

url

public Builder url(String url)

设置URL。

Remote task server base URL.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。The url.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:606–609

headers

public Builder headers(Map<String, String> headers)

设置请求头。

Optional HTTP headers for the remote task server (e.g.

参数Parameters

名称Name	类型Type	说明Description
`headers`	Map<String, String>	请求头（类型 `Map`）。The headers.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:615–618

remoteStreaming

public Builder remoteStreaming(Boolean remoteStreaming)

设置远程流式。

Whether remote subagent events should be streamed back into the parent's event stream.

参数Parameters

名称Name	类型Type	说明Description
`remoteStreaming`	Boolean	远程流式（类型 `Boolean`）。The remote streaming.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:625–628

remoteStreamDetail

public Builder remoteStreamDetail(RemoteStreamDetail remoteStreamDetail)

设置远程流详情。

How much of the remote event stream to forward.

参数Parameters

名称Name	类型Type	说明Description
`remoteStreamDetail`	RemoteStreamDetail	远程流详情（类型 `RemoteStreamDetail`）。The remote stream detail.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:636–639

remoteAskPolicy

public Builder remoteAskPolicy(RemoteAskPolicy remoteAskPolicy)

设置该配置项。

Policy for resolving remote HITL confirmations.

参数Parameters

名称Name	类型Type	说明Description
`remoteAskPolicy`	RemoteAskPolicy	远程 Ask 策略（类型 `RemoteAskPolicy`）。The remote ask policy.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:645–648

remoteContextAttributes

public Builder remoteContextAttributes(Map<String, Object> remoteContextAttributes)

设置远程上下文属性。

Static attributes sent as context.attributes with every submission to this remote subagent (e.g.

参数Parameters

名称Name	类型Type	说明Description
`remoteContextAttributes`	Map<String, Object>	远程上下文属性（类型 `Map`）。The remote context attributes.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:656–659

build

public SubagentDeclaration build()

构建SubagentDeclaration。

Builds the SubagentDeclaration.

返回Returns SubagentDeclaration

返回SubagentDeclaration。Returns subagent declaration.

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if `name` or `description` is blank, or mutually exclusive fields are combined (workspace vs inline vs remote URL)

源码Source io/agentscope/harness/agent/subagent/SubagentDeclaration.java:667–699