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

Builder

public static class Builder

源码Source io/agentscope/harness/agent/HarnessAgent.java:1194–2970

HarnessAgent的构建器。位于 io.agentscope.harness.agent 包。核心成员包括 teamsMode、fromAgent、name、description、sysPrompt、checkRunning。

Builder for HarnessAgent. Owns the harness orchestration: workspace + filesystem + sandbox + hooks/middlewares + tools + skills + subagents + tools.json + plan-mode.

方法摘要Method Summary

方法Method	说明Description
`public` `Builder teamsMode(io.agentscope.harness.agent.team.TeamClient teamClient, io.agentscope.harness.agent.team.TeamContext teamContext)`	设置该配置项。 Enables AgentTeams mode: attaches `io.agentscope.harness.agent.middleware.TeamsMiddleware` and registers the role-clipped `team` tool.
`public` `Builder teamsMode(io.agentscope.harness.agent.team.TeamClient teamClient, io.agentscope.harness.agent.team.TeamContext teamContext, String sessionId)`	设置该配置项。 Same as `#teamsMode(io.agentscope.harness.agent.team.TeamClient, io.agentscope.harness.agent.team.TeamContext)` but also binds the middleware to ` sessionId` so control-plane TeamEvents addressed at that session reach this agent.
`public static` `Builder fromAgent(ReActAgent agent)` static	设置来自智能体。 Returns a new `Builder` pre-populated with as much of the given `ReActAgent`'s observable configuration as can be read back from public getters.
`public` `Builder name(String name)`	设置名称。 Performs the name operation.
`public` `Builder description(String description)`	设置该配置项。 Performs the description operation.
`public` `Builder sysPrompt(String sysPrompt)`	设置该配置项。 Performs the sys prompt operation.
`public` `Builder checkRunning(boolean checkRunning)`	设置检查运行中。 Performs the check running operation.
`public` `Builder model(Model model)`	设置模型。 Performs the model operation.
`public` `Builder model(String modelId)`	设置模型。 Performs the model operation.
`public` `Builder toolkit(Toolkit toolkit)`	设置工具包。 Performs the toolkit operation.
`public` `Builder maxIters(int maxIters)`	设置最大迭代次数。 Performs the max iters operation.
`public` `Builder modelExecutionConfig(ExecutionConfig config)`	设置模型执行配置。 Performs the model execution config operation.
`public` `Builder toolExecutionConfig(ExecutionConfig config)`	设置工具执行配置。 Performs the tool execution config operation.
`public` `Builder generateOptions(GenerateOptions options)`	设置该配置项。 Performs the generate options operation.
`public` `Builder hook(Hook hook)`	设置钩子。 Performs the hook operation.
`public` `Builder hooks(List<Hook> hooks)`	设置该配置项。 Performs the hooks operation.
`public` `Builder middleware(MiddlewareBase middleware)`	设置中间件。 Performs the middleware operation.
`public` `Builder middlewares(List<? extends MiddlewareBase> middlewareList)`	设置该配置项。 Performs the middlewares operation.
`public` `Builder stateStore(AgentStateStore stateStore)`	设置状态存储。 Performs the state store operation.
`public` `Builder distributedStore(DistributedStore store)`	设置分布式存储。 Configures a distributed store that provides all storage components at once: `AgentStateStore`, `io.agentscope.harness.agent.filesystem.remote.store.BaseStore`, `io.agentscope.harness.agent.sandbox.snapshot.SandboxSnapshotSpec`, and `io.agentscope.harness.agent.sandbox.SandboxExecutionGuard`.
`public` `Builder defaultSessionId(String defaultSessionId)`	设置默认会话标识。 Performs the default session id operation.
`public` `Builder toolExecutionContext(ToolExecutionContext ctx)`	设置工具执行上下文。 Performs the tool execution context operation.
`public` `Builder enableMetaTool(boolean enableMetaTool)`	启用元数据工具。 Enables the meta tool.
`public` `Builder enablePendingToolRecovery(boolean enable)`	启用该配置。 Enables recovery of orphaned tool calls when a new message arrives.
`public` `Builder enableTaskList()`	启用任务列表。 Enables the task list.
`public` `Builder enableTaskList(boolean enabled)`	启用任务列表。 Enables the task list.
`public` `Builder maxRetries(int maxRetries)`	设置最大重试。 Performs the max retries operation.
`public` `Builder fallbackModel(Model fallbackModel)`	设置回退模型。 Performs the fallback model operation.
`public` `Builder fallbackModel(String modelId)`	设置回退模型。 Performs the fallback model operation.
`public` `Builder failoverListener(FailoverListener failoverListener)`	设置故障转移监听器。 Sets the listener notified when the fallback model takes over from a failed primary model.
`public` `Builder stopOnReject(boolean stopOnReject)`	设置停止 On 拒绝。 Stops the on reject.
`public` `Builder permissionContext(PermissionContextState permissionContext)`	设置权限上下文。 Performs the permission context operation.
`public` `Builder agentId(String agentId)`	设置智能体标识。 Sets the stable identifier used as the agent's namespace key in the composite filesystem (e.g.
`public` `Builder skillRepository(AgentSkillRepository skillRepository)`	设置技能仓库。 Adds a marketplace / external skill repository (e.g.
`public` `Builder skillRepositories(List<AgentSkillRepository> repositories)`	设置该配置项。 Replaces the current marketplace repository list with the given collection.
`public` `Builder projectGlobalSkillsDir(Path projectGlobalSkillsDir)`	设置该配置项。 Configures a project-global skills directory layered below marketplace and workspace skills (lowest precedence).
`public` `Builder workspace(Path workspace)`	设置工作区目录。 Sets the workspace directory.
`public` `Builder workspace(String path)`	设置工作区。 Sets the workspace directory from a filesystem path string.
`public` `Builder environmentMemory(String environmentMemory)`	设置环境记忆。 Performs the environment memory operation.
`public` `Builder abstractFilesystem(AbstractFilesystem store)`	设置抽象文件系统。 Escape hatch: sets a custom `AbstractFilesystem` implementation directly.
`public` `Builder filesystem(SandboxFilesystemSpec spec)`	设置文件系统。 Configures Mode 2 — sandbox filesystem.
`public` `Builder filesystem(RemoteFilesystemSpec spec)`	设置文件系统。 Configures Mode 1 — composite (non-sandbox) filesystem.
`public` `Builder filesystem(LocalFilesystemSpec spec)`	设置文件系统。 Configures Mode 3 — local filesystem with shell.
`public` `Builder filesystemRoute(String prefix, AbstractFilesystem filesystem)`	设置文件系统路由。 Mounts an additional `AbstractFilesystem` under a path prefix, alongside the primary filesystem configured via `#filesystem(SandboxFilesystemSpec)`, `#filesystem(RemoteFilesystemSpec)`, or `#filesystem(LocalFilesystemSpec)`.
`public` `Builder compaction(CompactionConfig config)`	设置压缩。 Overrides the default `CompactionMiddleware` configuration.
`public` `Builder disableCompaction()`	禁用压缩。 Disables the `CompactionMiddleware` entirely.
`public` `Builder memory(MemoryConfig config)`	设置记忆。 Overrides the long-term memory pipeline configuration (flush + consolidation + maintenance).
`public` `Builder toolResultEviction(ToolResultEvictionConfig config)`	设置工具结果淘汰。 Overrides the default `ToolResultEvictionMiddleware` configuration.
`public` `Builder disableToolResultEviction()`	禁用工具结果淘汰。 Disables the `ToolResultEvictionMiddleware` entirely.
`public` `Builder toolsConfig(ToolsConfig toolsConfig)`	设置工具配置。 Programmatic override for `workspace/tools.json`.
`public` `Builder mcpServerRegistrationListener(McpServerRegistrationListener mcpServerRegistrationListener)`	设置MCP 服务端注册监听器。 Sets the listener for terminal MCP server registration results produced while building this agent.
`public` `Builder subagent(SubagentDeclaration declaration)`	设置子智能体。 Adds a subagent declaration.
`public` `Builder subagents(List<SubagentDeclaration> declarations)`	设置该配置项。 Performs the subagents operation.
`public` `Builder subagentFactory(String name, Function<String, Agent> factory)`	设置子智能体工厂。 Adds a fully custom subagent factory for a given agent id.
`public` `Builder subagentFactory(String name, String description, Function<String, Agent> factory)`	设置子智能体工厂。 Adds a fully custom subagent factory for a given agent id, with a description shown to the orchestrator.
`public` `Builder taskRepository(TaskRepository taskRepository)`	设置任务仓库。 Sets a custom `TaskRepository` for background subagent execution.
`public` `Builder messageBus(io.agentscope.harness.agent.bus.MessageBus messageBus)`	设置消息总线。 Sets the `io.agentscope.harness.agent.bus.MessageBus` for inbox-based message delivery.
`public` `Builder asyncToolTimeout(java.time.Duration timeout)`	设置异步工具超时。 Enables `AsyncToolMiddleware` with the given timeout.
`public` `Builder asyncToolRegistry(io.agentscope.harness.agent.bus.AsyncToolRegistry registry)`	设置异步工具注册表。 Sets the `io.agentscope.harness.agent.bus.AsyncToolRegistry` for tracking async tool executions.
`public` `Builder externalSubagentTool(Object tool)`	设置外部子智能体工具。 Injects an external subagent tool (typically `SessionsTool`).
`public` `Builder modelResolver(Function<String, Model> resolver)`	设置模型解析器。 Sets a resolver for model name strings to `Model` instances for subagents.
`public` `Builder additionalContextFile(String relativePath)`	设置该参数。 Adds a custom context file (relative to workspace) loaded into the system prompt alongside AGENTS.md, MEMORY.md, and KNOWLEDGE.md.
`public` `Builder maxContextTokens(int maxTokens)`	设置最大上下文令牌数。 Sets the maximum token budget for workspace context.
`public` `Builder useLegacyXmlWorkspaceContext(boolean enabled)`	设置该配置项。 Switches workspace context rendering between markdown (default) and legacy XML style.
`public` `Builder enableAgentTracingLog(boolean enabled)`	启用智能体追踪日志。 Enables or disables agent execution trace logging via `AgentTraceMiddleware`.
`public` `Builder artifactDeliveryTarget(ArtifactDeliveryTarget target)`	设置该配置项。 Configures the `ArtifactDeliveryTarget` used by the `deliver_artifact` tool.
`public` `Builder disableFilesystemTools()`	禁用文件系统工具。 Skips registration of `FilesystemTool`.
`public` `Builder disableShellTool()`	禁用该配置。 Skips registration of `ShellExecuteTool`.
`public` `Builder disableWebTools()`	禁用该配置。 Skips registration of the optional Tavily-backed `web_search` and `web_fetch` tools.
`public` `Builder webHttpClient(HttpClient client)`	设置该配置项。 Supplies a custom `java.net.http.HttpClient` used by the built-in `web_fetch` and `web_search` tools (e.g.
`public` `Builder registerExternalSchemas(java.util.List<io.agentscope.core.model.ToolSchema> schemas)`	注册外部模式。 Registers schema-only external tools on the builder toolkit (merged into the final agent toolkit at `#build()`).
`public` `Builder disableDynamicSkills()`	禁用该配置。 Disables dynamic per-call skill loading from the workspace filesystem.
`public` `Builder disableDefaultWorkspaceSkills()`	禁用默认工作区技能。 Skips registration of the default Layer-4 `io.agentscope.harness.agent.skill.WorkspaceSkillRepository`.
`public` `Builder enableSkillManageTool(SkillManageConfig config)`	启用该配置。 Enables the agent-callable `skill_manage` tool so the agent can create / edit / patch / archive its own skills in the workspace, and upgrades the workspace skill repository to a writable variant.
`public` `Builder enableSkillManageTool(boolean autoPromote)`	启用该配置。 Shorthand for `#enableSkillManageTool(SkillManageConfig)` with default config.
`public` `Builder enableSkillPromotionGate(SkillPromotionGate gate, SkillVisibilityFilter visibilityFilter)`	启用该配置。 Configures the runtime promotion gate + visibility filter chain.
`public` `Builder environment(String env)`	设置环境。 Sets the deployment environment label used by `EnvironmentFilter`.
`public` `Builder enableSkillCurator(SkillCuratorConfig config)`	启用该配置。 Enables the background skill curator.
`public` `Builder enablePlanMode()`	启用计划模式。 Enables plan mode (read-only design phase) with `plan_enter`/`plan_write`/ `plan_exit` tools and a `PlanModeMiddleware` that enforces read-only tools while plan mode is active.
`public` `Builder enablePlanMode(boolean enabled)`	启用计划模式。 Enables the plan mode.
`public` `Builder planFileDirectory(String dir)`	设置计划文件目录。 Performs the plan file directory operation.
`public` `Builder allowShellInPlanMode()`	返回 `allowShellInPlanMode` 结果。 Allows the shell tool (`execute`) to run while plan mode is active.
`public` `Builder allowShellInPlanMode(boolean allowed)`	设置该配置项。 Performs the allow shell in plan mode operation.
`public` `Builder skillFilter(io.agentscope.core.skill.SkillFilter filter)`	设置技能过滤器。 Performs the skill filter operation.
`public` `Builder skillsEnabled(boolean enabled)`	设置技能已启用。 Performs the skills enabled operation.
`public` `Builder enableSkills(String... skillNames)`	启用技能。 Enables the skills.
`public` `Builder disableSkills(String... skillNames)`	禁用技能。 Disables the skills.
`public` `Builder disableDynamicSubagents()`	禁用该配置。 Disables the dynamic subagents.
`public` `Builder disableMemoryTools()`	禁用记忆工具。 Skips registration of `memory_search` / `memory_get` / `memory_save` / `session_search`, and omits matching Memory Recall / tool-based Persistence guidance from the workspace system prompt.
`public` `Builder disableMemoryHooks()`	禁用该配置。 Disables memory flush + background consolidation, and removes the "automatically extracted" Persistence line from the workspace system prompt.
`public` `Builder disableTranscript()`	禁用该配置。 Disables the independent session-transcript middleware.
`public` `Builder transcriptStore(TranscriptStore transcriptStore)`	设置该配置项。 Optional override for the session `TranscriptStore` (segmented append store).
`public` `Builder transcriptTenant(String transcriptTenant)`	设置该配置项。 Tenant segment used in transcript object keys (default `"default"`).
`public` `Builder disableSessionPersistence()`	禁用会话持久化。 No-op since 2.0; session persistence is owned by ReActAgent itself.
`public` `Builder disableWorkspaceContext()`	禁用工作区上下文。 Disables the workspace context.
`public` `Builder disableAtPathExpansion()`	禁用该配置。 Disables the at path expansion.
`public` `Builder disableSubagents()`	禁用该配置。 Disables the subagents.
`public` `Builder disableToolsConfig()`	禁用工具配置。 Disables the tools config.
`public List<SubagentEntry> buildSubagentEntries(Path resolvedWorkspace)`	构建子智能体条目。 Builds the subagent entries (general-purpose + declared + custom factories) without constructing the full agent.
`public List<SubagentEntry> buildSubagentEntries(Path resolvedWorkspace, SandboxBackedFilesystem sandboxFs)`	构建子智能体条目。 Builds the subagent entries.
`public` `HarnessAgent build()`	构建并返回最终实例。 Creates and returns an instance.

方法详情Method Detail

teamsMode

public Builder teamsMode(io.agentscope.harness.agent.team.TeamClient teamClient, io.agentscope.harness.agent.team.TeamContext teamContext)

设置该配置项。

Enables AgentTeams mode: attaches io.agentscope.harness.agent.middleware.TeamsMiddleware and registers the role-clipped team tool.

参数Parameters

名称Name	类型Type	说明Description
`teamClient`	io.agentscope.harness.agent.team.TeamClient	团队客户端（类型 `io.agentscope.harness.agent.team.TeamClient`）。The team client.
`teamContext`	io.agentscope.harness.agent.team.TeamContext	团队上下文（类型 `io.agentscope.harness.agent.team.TeamContext`）。The team context.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1310–1314

teamsMode

public Builder teamsMode(io.agentscope.harness.agent.team.TeamClient teamClient, io.agentscope.harness.agent.team.TeamContext teamContext, String sessionId)

设置该配置项。

Same as #teamsMode(io.agentscope.harness.agent.team.TeamClient, io.agentscope.harness.agent.team.TeamContext) but also binds the middleware to sessionId so control-plane TeamEvents addressed at that session reach this agent.

参数Parameters

名称Name	类型Type	说明Description
`teamClient`	io.agentscope.harness.agent.team.TeamClient	团队客户端（类型 `io.agentscope.harness.agent.team.TeamClient`）。The team client.
`teamContext`	io.agentscope.harness.agent.team.TeamContext	团队上下文（类型 `io.agentscope.harness.agent.team.TeamContext`）。The team context.
`sessionId`	String	会话标识（类型 `String`）。The session id.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1321–1329

fromAgent

public static Builder fromAgent(ReActAgent agent)

static

设置来自智能体。

Returns a new Builder pre-populated with as much of the given ReActAgent's observable configuration as can be read back from public getters.

参数Parameters

名称Name	类型Type	说明Description
`agent`	ReActAgent	智能体（类型 `ReActAgent`）。source `ReActAgent` to inherit observable configuration from

返回Returns Builder

返回当前实例，以支持链式调用。a new `Builder` pre-populated with the inheritable subset

源码Source io/agentscope/harness/agent/HarnessAgent.java:1427–1502

name

public Builder name(String name)

设置名称。

Performs the name operation.

参数Parameters

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

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1506–1510

description

public Builder description(String description)

设置该配置项。

Performs the description operation.

参数Parameters

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

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1512–1516

sysPrompt

public Builder sysPrompt(String sysPrompt)

设置该配置项。

Performs the sys prompt operation.

参数Parameters

名称Name	类型Type	说明Description
`sysPrompt`	String	sys 提示词（类型 `String`）。The sys prompt.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1518–1522

checkRunning

public Builder checkRunning(boolean checkRunning)

设置检查运行中。

Performs the check running operation.

参数Parameters

名称Name	类型Type	说明Description
`checkRunning`	boolean	检查运行中（类型 `boolean`）。The check running.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1524–1528

model

public Builder model(Model model)

设置模型。

Performs the model operation.

参数Parameters

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

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1530–1534

model

public Builder model(String modelId)

设置模型。

Performs the model operation.

参数Parameters

名称Name	类型Type	说明Description
`modelId`	String	模型标识（类型 `String`）。The model id.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1536–1541

toolkit

public Builder toolkit(Toolkit toolkit)

设置工具包。

Performs the toolkit operation.

参数Parameters

名称Name	类型Type	说明Description
`toolkit`	Toolkit	工具包（类型 `Toolkit`）。The toolkit.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1543–1548

maxIters

public Builder maxIters(int maxIters)

设置最大迭代次数。

Performs the max iters operation.

参数Parameters

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

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1559–1563

modelExecutionConfig

public Builder modelExecutionConfig(ExecutionConfig config)

设置模型执行配置。

Performs the model execution config operation.

参数Parameters

名称Name	类型Type	说明Description
`config`	ExecutionConfig	配置对象（类型 `ExecutionConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1565–1569

toolExecutionConfig

public Builder toolExecutionConfig(ExecutionConfig config)

设置工具执行配置。

Performs the tool execution config operation.

参数Parameters

名称Name	类型Type	说明Description
`config`	ExecutionConfig	配置对象（类型 `ExecutionConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1571–1575

generateOptions

public Builder generateOptions(GenerateOptions options)

设置该配置项。

Performs the generate options operation.

参数Parameters

名称Name	类型Type	说明Description
`options`	GenerateOptions	选项（类型 `GenerateOptions`）。The options.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1577–1581

hook

public Builder hook(Hook hook)

设置钩子。

Performs the hook operation.

参数Parameters

名称Name	类型Type	说明Description
`hook`	Hook	钩子（类型 `Hook`）。The hook.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1583–1589

hooks

public Builder hooks(List<Hook> hooks)

设置该配置项。

Performs the hooks operation.

参数Parameters

名称Name	类型Type	说明Description
`hooks`	List<Hook>	hooks（类型 `List`）。The hooks.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1591–1598

middleware

public Builder middleware(MiddlewareBase middleware)

设置中间件。

Performs the middleware operation.

参数Parameters

名称Name	类型Type	说明Description
`middleware`	MiddlewareBase	中间件（类型 `MiddlewareBase`）。The middleware.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1600–1606

middlewares

public Builder middlewares(List<? extends MiddlewareBase> middlewareList)

设置该配置项。

Performs the middlewares operation.

参数Parameters

名称Name	类型Type	说明Description
`middlewareList`	List<? extends MiddlewareBase>	中间件列表（类型 `List`）。The middleware list.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1608–1615

stateStore

public Builder stateStore(AgentStateStore stateStore)

设置状态存储。

Performs the state store operation.

参数Parameters

名称Name	类型Type	说明Description
`stateStore`	AgentStateStore	状态存储（类型 `AgentStateStore`）。The state store.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1631–1635

distributedStore

public Builder distributedStore(DistributedStore store)

设置分布式存储。

Configures a distributed store that provides all storage components at once: AgentStateStore, io.agentscope.harness.agent.filesystem.remote.store.BaseStore, io.agentscope.harness.agent.sandbox.snapshot.SandboxSnapshotSpec, and `io.agentscope.harness.agent.sandbox.SandboxEx…

参数Parameters

名称Name	类型Type	说明Description
`store`	DistributedStore	分布式存储到使用。the distributed store to use

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1649–1652

defaultSessionId

public Builder defaultSessionId(String defaultSessionId)

设置默认会话标识。

Performs the default session id operation.

参数Parameters

名称Name	类型Type	说明Description
`defaultSessionId`	String	默认会话标识（类型 `String`）。The default session id.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1654–1657

toolExecutionContext

public Builder toolExecutionContext(ToolExecutionContext ctx)

设置工具执行上下文。

Performs the tool execution context operation.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	ToolExecutionContext	运行时上下文（类型 `ToolExecutionContext`）。The ctx.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1659–1662

enableMetaTool

public Builder enableMetaTool(boolean enableMetaTool)

启用元数据工具。

Enables the meta tool.

参数Parameters

名称Name	类型Type	说明Description
`enableMetaTool`	boolean	启用元数据工具（类型 `boolean`）。The enable meta tool.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1664–1667

enablePendingToolRecovery

public Builder enablePendingToolRecovery(boolean enable)

启用该配置。

Enables recovery of orphaned tool calls when a new message arrives.

参数Parameters

名称Name	类型Type	说明Description
`enable`	boolean	启用（类型 `boolean`）。whether to synthesize error results for orphaned tool calls

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1677–1681

enableTaskList

public Builder enableTaskList()

启用任务列表。

Enables the task list.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1683–1686

enableTaskList

public Builder enableTaskList(boolean enabled)

启用任务列表。

Enables the task list.

参数Parameters

名称Name	类型Type	说明Description
`enabled`	boolean	已启用（类型 `boolean`）。The enabled.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1688–1691

maxRetries

public Builder maxRetries(int maxRetries)

设置最大重试。

Performs the max retries operation.

参数Parameters

名称Name	类型Type	说明Description
`maxRetries`	int	最大重试（类型 `int`）。The max retries.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1693–1696

fallbackModel

public Builder fallbackModel(Model fallbackModel)

设置回退模型。

Performs the fallback model operation.

参数Parameters

名称Name	类型Type	说明Description
`fallbackModel`	Model	回退模型（类型 `Model`）。The fallback model.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1698–1701

fallbackModel

public Builder fallbackModel(String modelId)

设置回退模型。

Performs the fallback model operation.

参数Parameters

名称Name	类型Type	说明Description
`modelId`	String	模型标识（类型 `String`）。The model id.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1703–1706

failoverListener

public Builder failoverListener(FailoverListener failoverListener)

设置故障转移监听器。

Sets the listener notified when the fallback model takes over from a failed primary model.

另见See also @see FailoverListener for the threading and failure contract

参数Parameters

名称Name	类型Type	说明Description
`failoverListener`	FailoverListener	故障转移监听器（类型 `FailoverListener`）。The failover listener.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1714–1717

stopOnReject

public Builder stopOnReject(boolean stopOnReject)

设置停止 On 拒绝。

Stops the on reject.

参数Parameters

名称Name	类型Type	说明Description
`stopOnReject`	boolean	停止 On 拒绝（类型 `boolean`）。The stop on reject.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1719–1722

permissionContext

public Builder permissionContext(PermissionContextState permissionContext)

设置权限上下文。

Performs the permission context operation.

参数Parameters

名称Name	类型Type	说明Description
`permissionContext`	PermissionContextState	权限上下文（类型 `PermissionContextState`）。The permission context.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1724–1728

agentId

public Builder agentId(String agentId)

设置智能体标识。

Sets the stable identifier used as the agent's namespace key in the composite filesystem (e.g.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1737–1740

skillRepository

public Builder skillRepository(AgentSkillRepository skillRepository)

设置技能仓库。

Adds a marketplace / external skill repository (e.g.

参数Parameters

名称Name	类型Type	说明Description
`skillRepository`	AgentSkillRepository	技能仓库（类型 `AgentSkillRepository`）。The skill repository.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1746–1751

skillRepositories

public Builder skillRepositories(List<AgentSkillRepository> repositories)

设置该配置项。

Replaces the current marketplace repository list with the given collection.

参数Parameters

名称Name	类型Type	说明Description
`repositories`	List<AgentSkillRepository>	repositories（类型 `List`）。The repositories.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1756–1766

projectGlobalSkillsDir

public Builder projectGlobalSkillsDir(Path projectGlobalSkillsDir)

设置该配置项。

Configures a project-global skills directory layered below marketplace and workspace skills (lowest precedence).

参数Parameters

名称Name	类型Type	说明Description
`projectGlobalSkillsDir`	Path	project Global 技能目录（类型 `Path`）。The project global skills dir.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1772–1775

workspace

public Builder workspace(Path workspace)

设置工作区目录。

Sets the workspace directory.

参数Parameters

名称Name	类型Type	说明Description
`workspace`	Path	工作区（类型 `Path`）。the workspace directory, or `null` to fall back to the resolved default

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1794–1797

workspace

public Builder workspace(String path)

设置工作区。

Sets the workspace directory from a filesystem path string.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。the workspace directory path, or `null` to fall back to the resolved default

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1808–1819

environmentMemory

public Builder environmentMemory(String environmentMemory)

设置环境记忆。

Performs the environment memory operation.

参数Parameters

名称Name	类型Type	说明Description
`environmentMemory`	String	环境记忆（类型 `String`）。The environment memory.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1821–1824

abstractFilesystem

public Builder abstractFilesystem(AbstractFilesystem store)

设置抽象文件系统。

Escape hatch: sets a custom AbstractFilesystem implementation directly.

参数Parameters

名称Name	类型Type	说明Description
`store`	AbstractFilesystem	存储实例（类型 `AbstractFilesystem`）。The store.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1827–1830

filesystem

public Builder filesystem(SandboxFilesystemSpec spec)

设置文件系统。

Configures Mode 2 — sandbox filesystem.

参数Parameters

名称Name	类型Type	说明Description
`spec`	SandboxFilesystemSpec	规格（类型 `SandboxFilesystemSpec`）。The spec.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1833–1836

filesystem

public Builder filesystem(RemoteFilesystemSpec spec)

设置文件系统。

Configures Mode 1 — composite (non-sandbox) filesystem.

参数Parameters

名称Name	类型Type	说明Description
`spec`	RemoteFilesystemSpec	规格（类型 `RemoteFilesystemSpec`）。The spec.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1839–1842

filesystem

public Builder filesystem(LocalFilesystemSpec spec)

设置文件系统。

Configures Mode 3 — local filesystem with shell.

参数Parameters

名称Name	类型Type	说明Description
`spec`	LocalFilesystemSpec	规格（类型 `LocalFilesystemSpec`）。The spec.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1845–1848

filesystemRoute

public Builder filesystemRoute(String prefix, AbstractFilesystem filesystem)

设置文件系统路由。

Mounts an additional AbstractFilesystem under a path prefix, alongside the primary filesystem configured via #filesystem(SandboxFilesystemSpec), #filesystem(RemoteFilesystemSpec), or #filesystem(LocalFilesystemSpec).

参数Parameters

名称Name	类型Type	说明Description
`prefix`	String	prefix（类型 `String`）。path prefix for the route (e.g. `"memory-stores/notes/"`)
`filesystem`	AbstractFilesystem	文件系统（类型 `AbstractFilesystem`）。backend serving paths under `prefix`

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1862–1865

compaction

public Builder compaction(CompactionConfig config)

设置压缩。

Overrides the default CompactionMiddleware configuration.

参数Parameters

名称Name	类型Type	说明Description
`config`	CompactionConfig	配置对象（类型 `CompactionConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1873–1877

disableCompaction

public Builder disableCompaction()

禁用压缩。

Disables the CompactionMiddleware entirely.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1880–1883

memory

public Builder memory(MemoryConfig config)

设置记忆。

Overrides the long-term memory pipeline configuration (flush + consolidation + maintenance).

参数Parameters

名称Name	类型Type	说明Description
`config`	MemoryConfig	配置对象（类型 `MemoryConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1893–1896

toolResultEviction

public Builder toolResultEviction(ToolResultEvictionConfig config)

设置工具结果淘汰。

Overrides the default ToolResultEvictionMiddleware configuration.

参数Parameters

名称Name	类型Type	说明Description
`config`	ToolResultEvictionConfig	配置对象（类型 `ToolResultEvictionConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1904–1908

disableToolResultEviction

public Builder disableToolResultEviction()

禁用工具结果淘汰。

Disables the ToolResultEvictionMiddleware entirely.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1911–1914

toolsConfig

public Builder toolsConfig(ToolsConfig toolsConfig)

设置工具配置。

Programmatic override for workspace/tools.json.

参数Parameters

名称Name	类型Type	说明Description
`toolsConfig`	ToolsConfig	工具配置（类型 `ToolsConfig`）。The tools config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1917–1920

mcpServerRegistrationListener

public Builder mcpServerRegistrationListener(McpServerRegistrationListener mcpServerRegistrationListener)

设置MCP 服务端注册监听器。

Sets the listener for terminal MCP server registration results produced while building this agent.

参数Parameters

名称Name	类型Type	说明Description
`mcpServerRegistrationListener`	McpServerRegistrationListener	MCP 服务端注册监听器（类型 `McpServerRegistrationListener`）。The mcp server registration listener.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1927–1931

subagent

public Builder subagent(SubagentDeclaration declaration)

设置子智能体。

Adds a subagent declaration.

参数Parameters

名称Name	类型Type	说明Description
`declaration`	SubagentDeclaration	declaration（类型 `SubagentDeclaration`）。The declaration.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1934–1937

subagents

public Builder subagents(List<SubagentDeclaration> declarations)

设置该配置项。

Performs the subagents operation.

参数Parameters

名称Name	类型Type	说明Description
`declarations`	List<SubagentDeclaration>	declarations（类型 `List`）。The declarations.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1939–1942

subagentFactory

public Builder subagentFactory(String name, Function<String, Agent> factory)

设置子智能体工厂。

Adds a fully custom subagent factory for a given agent id.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`factory`	Function<String, Agent>	工厂（类型 `Function`）。The factory.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1945–1947

subagentFactory

public Builder subagentFactory(String name, String description, Function<String, Agent> factory)

设置子智能体工厂。

Adds a fully custom subagent factory for a given agent id, with a description shown to the orchestrator.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。The name.
`description`	String	描述（类型 `String`）。The description.
`factory`	Function<String, Agent>	工厂（类型 `Function`）。The factory.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1953–1959

taskRepository

public Builder taskRepository(TaskRepository taskRepository)

设置任务仓库。

Sets a custom TaskRepository for background subagent execution.

参数Parameters

名称Name	类型Type	说明Description
`taskRepository`	TaskRepository	任务仓库（类型 `TaskRepository`）。The task repository.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1962–1965

messageBus

public Builder messageBus(io.agentscope.harness.agent.bus.MessageBus messageBus)

设置消息总线。

Sets the io.agentscope.harness.agent.bus.MessageBus for inbox-based message delivery.

参数Parameters

名称Name	类型Type	说明Description
`messageBus`	io.agentscope.harness.agent.bus.MessageBus	消息总线（类型 `io.agentscope.harness.agent.bus.MessageBus`）。The message bus.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1972–1975

asyncToolTimeout

public Builder asyncToolTimeout(java.time.Duration timeout)

设置异步工具超时。

Enables AsyncToolMiddleware with the given timeout.

参数Parameters

名称Name	类型Type	说明Description
`timeout`	java.time.Duration	超时时间（类型 `java.time.Duration`）。The timeout.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1982–1985

asyncToolRegistry

public Builder asyncToolRegistry(io.agentscope.harness.agent.bus.AsyncToolRegistry registry)

设置异步工具注册表。

Sets the io.agentscope.harness.agent.bus.AsyncToolRegistry for tracking async tool executions.

参数Parameters

名称Name	类型Type	说明Description
`registry`	io.agentscope.harness.agent.bus.AsyncToolRegistry	注册表（类型 `io.agentscope.harness.agent.bus.AsyncToolRegistry`）。The registry.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1992–1996

externalSubagentTool

public Builder externalSubagentTool(Object tool)

设置外部子智能体工具。

Injects an external subagent tool (typically SessionsTool).

参数Parameters

名称Name	类型Type	说明Description
`tool`	Object	工具（类型 `Object`）。The tool.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:1999–2002

modelResolver

public Builder modelResolver(Function<String, Model> resolver)

设置模型解析器。

Sets a resolver for model name strings to Model instances for subagents.

参数Parameters

名称Name	类型Type	说明Description
`resolver`	Function<String, Model>	解析器（类型 `Function`）。The resolver.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2005–2008

additionalContextFile

public Builder additionalContextFile(String relativePath)

设置该参数。

Adds a custom context file (relative to workspace) loaded into the system prompt alongside AGENTS.md, MEMORY.md, and KNOWLEDGE.md.

参数Parameters

名称Name	类型Type	说明Description
`relativePath`	String	relative 路径（类型 `String`）。The relative path.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2014–2019

maxContextTokens

public Builder maxContextTokens(int maxTokens)

设置最大上下文令牌数。

Sets the maximum token budget for workspace context.

参数Parameters

名称Name	类型Type	说明Description
`maxTokens`	int	最大令牌数（类型 `int`）。The max tokens.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2022–2025

useLegacyXmlWorkspaceContext

public Builder useLegacyXmlWorkspaceContext(boolean enabled)

设置该配置项。

Switches workspace context rendering between markdown (default) and legacy XML style.

参数Parameters

名称Name	类型Type	说明Description
`enabled`	boolean	已启用（类型 `boolean`）。The enabled.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2028–2031

enableAgentTracingLog

public Builder enableAgentTracingLog(boolean enabled)

启用智能体追踪日志。

Enables or disables agent execution trace logging via AgentTraceMiddleware.

参数Parameters

名称Name	类型Type	说明Description
`enabled`	boolean	已启用（类型 `boolean`）。The enabled.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2037–2040

artifactDeliveryTarget

public Builder artifactDeliveryTarget(ArtifactDeliveryTarget target)

设置该配置项。

Configures the ArtifactDeliveryTarget used by the deliver_artifact tool.

参数Parameters

名称Name	类型Type	说明Description
`target`	ArtifactDeliveryTarget	目标（类型 `ArtifactDeliveryTarget`）。The target.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2056–2059

disableFilesystemTools

public Builder disableFilesystemTools()

禁用文件系统工具。

Skips registration of FilesystemTool.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2062–2065

disableShellTool

public Builder disableShellTool()

禁用该配置。

Skips registration of ShellExecuteTool.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2068–2071

disableWebTools

public Builder disableWebTools()

禁用该配置。

Skips registration of the optional Tavily-backed web_search and web_fetch tools.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2074–2077

webHttpClient

public Builder webHttpClient(HttpClient client)

设置该配置项。

Supplies a custom java.net.http.HttpClient used by the built-in web_fetch and web_search tools (e.g.

参数Parameters

名称Name	类型Type	说明Description
`client`	HttpClient	客户端（类型 `HttpClient`）。The client.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2086–2089

registerExternalSchemas

public Builder registerExternalSchemas(java.util.List<io.agentscope.core.model.ToolSchema> schemas)

注册外部模式。

Registers schema-only external tools on the builder toolkit (merged into the final agent toolkit at #build()).

参数Parameters

名称Name	类型Type	说明Description
`schemas`	java.util.List<io.agentscope.core.model.ToolSchema>	模式（类型 `java.util.List`）。The schemas.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2096–2102

disableDynamicSkills

public Builder disableDynamicSkills()

禁用该配置。

Disables dynamic per-call skill loading from the workspace filesystem.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2105–2108

disableDefaultWorkspaceSkills

public Builder disableDefaultWorkspaceSkills()

禁用默认工作区技能。

Skips registration of the default Layer-4 io.agentscope.harness.agent.skill.WorkspaceSkillRepository.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2116–2119

enableSkillManageTool

public Builder enableSkillManageTool(SkillManageConfig config)

启用该配置。

Enables the agent-callable skill_manage tool so the agent can create / edit / patch / archive its own skills in the workspace, and upgrades the workspace skill repository to a writable variant.

参数Parameters

名称Name	类型Type	说明Description
`config`	SkillManageConfig	配置对象（类型 `SkillManageConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2126–2130

enableSkillManageTool

public Builder enableSkillManageTool(boolean autoPromote)

启用该配置。

Shorthand for #enableSkillManageTool(SkillManageConfig) with default config.

参数Parameters

名称Name	类型Type	说明Description
`autoPromote`	boolean	auto Promote（类型 `boolean`）。The auto promote.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2133–2136

enableSkillPromotionGate

public Builder enableSkillPromotionGate(SkillPromotionGate gate, SkillVisibilityFilter visibilityFilter)

启用该配置。

Configures the runtime promotion gate + visibility filter chain.

参数Parameters

名称Name	类型Type	说明Description
`gate`	SkillPromotionGate	gate（类型 `SkillPromotionGate`）。The gate.
`visibilityFilter`	SkillVisibilityFilter	visibility 过滤器（类型 `SkillVisibilityFilter`）。The visibility filter.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2141–2146

environment

public Builder environment(String env)

设置环境。

Sets the deployment environment label used by EnvironmentFilter.

参数Parameters

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

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2149–2152

enableSkillCurator

public Builder enableSkillCurator(SkillCuratorConfig config)

启用该配置。

Enables the background skill curator.

参数Parameters

名称Name	类型Type	说明Description
`config`	SkillCuratorConfig	配置对象（类型 `SkillCuratorConfig`）。The config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2155–2159

enablePlanMode

public Builder enablePlanMode()

启用计划模式。

Enables plan mode (read-only design phase) with plan_enter/plan_write/ plan_exit tools and a PlanModeMiddleware that enforces read-only tools while plan mode is active.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2166–2168

enablePlanMode

public Builder enablePlanMode(boolean enabled)

启用计划模式。

Enables the plan mode.

参数Parameters

名称Name	类型Type	说明Description
`enabled`	boolean	已启用（类型 `boolean`）。The enabled.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2170–2173

planFileDirectory

public Builder planFileDirectory(String dir)

设置计划文件目录。

Performs the plan file directory operation.

参数Parameters

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

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2175–2180

allowShellInPlanMode

public Builder allowShellInPlanMode()

返回 allowShellInPlanMode 结果。

Allows the shell tool (execute) to run while plan mode is active.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2190–2192

allowShellInPlanMode

public Builder allowShellInPlanMode(boolean allowed)

设置该配置项。

Performs the allow shell in plan mode operation.

参数Parameters

名称Name	类型Type	说明Description
`allowed`	boolean	已允许（类型 `boolean`）。The allowed.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2194–2197

skillFilter

public Builder skillFilter(io.agentscope.core.skill.SkillFilter filter)

设置技能过滤器。

Performs the skill filter operation.

参数Parameters

名称Name	类型Type	说明Description
`filter`	io.agentscope.core.skill.SkillFilter	过滤条件（类型 `io.agentscope.core.skill.SkillFilter`）。The filter.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2199–2202

skillsEnabled

public Builder skillsEnabled(boolean enabled)

设置技能已启用。

Performs the skills enabled operation.

参数Parameters

名称Name	类型Type	说明Description
`enabled`	boolean	已启用（类型 `boolean`）。The enabled.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2204–2210

enableSkills

public Builder enableSkills(String... skillNames)

启用技能。

Enables the skills.

参数Parameters

名称Name	类型Type	说明Description
`skillNames` varargs	String...	技能 Names（类型 `String...`）。The skill names.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2212–2215

disableSkills

public Builder disableSkills(String... skillNames)

禁用技能。

Disables the skills.

参数Parameters

名称Name	类型Type	说明Description
`skillNames` varargs	String...	技能 Names（类型 `String...`）。The skill names.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2217–2220

disableDynamicSubagents

public Builder disableDynamicSubagents()

禁用该配置。

Disables the dynamic subagents.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2222–2225

disableMemoryTools

public Builder disableMemoryTools()

禁用记忆工具。

Skips registration of memory_search / memory_get / memory_save / session_search, and omits matching Memory Recall / tool-based Persistence guidance from the workspace system prompt.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2232–2235

disableMemoryHooks

public Builder disableMemoryHooks()

禁用该配置。

Disables memory flush + background consolidation, and removes the "automatically extracted" Persistence line from the workspace system prompt.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2243–2246

disableTranscript

public Builder disableTranscript()

禁用该配置。

Disables the independent session-transcript middleware.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2252–2255

transcriptStore

public Builder transcriptStore(TranscriptStore transcriptStore)

设置该配置项。

Optional override for the session TranscriptStore (segmented append store).

参数Parameters

名称Name	类型Type	说明Description
`transcriptStore`	TranscriptStore	transcript 存储（类型 `TranscriptStore`）。The transcript store.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2258–2261

transcriptTenant

public Builder transcriptTenant(String transcriptTenant)

设置该配置项。

Tenant segment used in transcript object keys (default "default").

参数Parameters

名称Name	类型Type	说明Description
`transcriptTenant`	String	transcript 租户（类型 `String`）。The transcript tenant.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2264–2267

disableSessionPersistence

public Builder disableSessionPersistence()

禁用会话持久化。

No-op since 2.0; session persistence is owned by ReActAgent itself.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2270–2273

disableWorkspaceContext

public Builder disableWorkspaceContext()

禁用工作区上下文。

Disables the workspace context.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2275–2278

disableAtPathExpansion

public Builder disableAtPathExpansion()

禁用该配置。

Disables the at path expansion.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2280–2283

disableSubagents

public Builder disableSubagents()

禁用该配置。

Disables the subagents.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2285–2288

disableToolsConfig

public Builder disableToolsConfig()

禁用工具配置。

Disables the tools config.

返回Returns Builder

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

源码Source io/agentscope/harness/agent/HarnessAgent.java:2290–2293

buildSubagentEntries

public List<SubagentEntry> buildSubagentEntries(Path resolvedWorkspace)

构建子智能体条目。

Builds the subagent entries (general-purpose + declared + custom factories) without constructing the full agent.

参数Parameters

名称Name	类型Type	说明Description
`resolvedWorkspace`	Path	已解析工作区（类型 `Path`）。The resolved workspace.

返回Returns List<SubagentEntry>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/HarnessAgent.java:2310–2312

buildSubagentEntries

public List<SubagentEntry> buildSubagentEntries(Path resolvedWorkspace, SandboxBackedFilesystem sandboxFs)

构建子智能体条目。

Builds the subagent entries.

参数Parameters

名称Name	类型Type	说明Description
`resolvedWorkspace`	Path	已解析工作区（类型 `Path`）。The resolved workspace.
`sandboxFs`	SandboxBackedFilesystem	沙箱 Fs（类型 `SandboxBackedFilesystem`）。The sandbox fs.

返回Returns List<SubagentEntry>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/HarnessAgent.java:2314–2318

build

public HarnessAgent build()

构建并返回最终实例。

Creates and returns an instance.

返回Returns HarnessAgent

返回HarnessAgent。Returns harness agent.

源码Source io/agentscope/harness/agent/HarnessAgent.java:2356–2969