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

AgentSpecLoader

public final class AgentSpecLoader

源码Source io/agentscope/harness/agent/subagent/AgentSpecLoader.java:74–439

智能体规格加载器，支持智能体之间的发现、委派与协作。位于 io.agentscope.harness.agent.subagent 包。核心成员包括 loadFromDirectory、loadFromFilesystem、loadFromFile、parse。

Loads SubagentDeclaration instances from Markdown files with YAML front matter placed in the subagents/ directory of a workspace.

File naming: the filename (without the .md extension) becomes the subagent's name / agent-id. The front matter must not contain a name field.

Scan strategy: only direct children of the given directory are scanned (non-recursive) to prevent accidentally loading files that live inside a definition workspace that happens to be stored under the same parent.

File format:


---
description: Reviews code for security and performance issues.
workspace:
mode: isolated # isolated | shared (default: isolated)
path: ./defs/reviewer # optional; relative to mainWorkspace, or absolute
model: qwen3-max # optional model override
maxIters: 12 # optional (default 10)
tools: [read_file, grep_files, edit_file] # optional allowlist
---

# Inline body (only when workspace.path is absent)
You are a code reviewer...

Rules:

description is required.
When workspace.path is present, the Markdown body must be blank; the subagent's system prompt is read from <workspace.path>/AGENTS.md at runtime.
When workspace.path is absent, the Markdown body (if any) becomes the inline SubagentDeclaration#getInlineAgentsBody().

方法摘要Method Summary

方法Method	说明Description
`public static List<SubagentDeclaration> loadFromDirectory(Path subagentsDir, Path mainWorkspace)` static	加载来自目录。 Non-recursively scans `subagentsDir` for `.md` files and parses each into a `SubagentDeclaration`.
`public static List<SubagentDeclaration> loadFromFilesystem(AbstractFilesystem filesystem, Path mainWorkspace)` static	加载来自文件系统。 Loads subagent declarations via the `AbstractFilesystem` using an empty runtime context.
`public static List<SubagentDeclaration> loadFromFilesystem(AbstractFilesystem filesystem, RuntimeContext runtimeContext, Path mainWorkspace)` static	加载来自文件系统。 Loads subagent declarations via the `AbstractFilesystem`, respecting the supplied runtime context's namespace isolation.
`public static` `SubagentDeclaration loadFromFile(Path filePath, Path mainWorkspace) throws IOException` static	加载来自文件。 Parses a single Markdown declaration file.
`public static` `SubagentDeclaration parse(String markdown, String name, Path mainWorkspace)` static	执行解析相关操作。 Parses markdown content with YAML front matter into a `SubagentDeclaration`.

方法详情Method Detail

loadFromDirectory

public static List<SubagentDeclaration> loadFromDirectory(Path subagentsDir, Path mainWorkspace)

static

加载来自目录。

Non-recursively scans subagentsDir for .md files and parses each into a SubagentDeclaration.

参数Parameters

名称Name	类型Type	说明Description
`subagentsDir`	Path	subagents 目录（类型 `Path`）。the `subagents/` directory to scan
`mainWorkspace`	Path	主工作区（类型 `Path`）。the parent workspace used to resolve relative `workspace.path` values; may be `null` (relative paths will remain relative)

返回Returns List<SubagentDeclaration>

返回列出。list of parsed declarations; never `null`

源码Source io/agentscope/harness/agent/subagent/AgentSpecLoader.java:90–122

loadFromFilesystem

public static List<SubagentDeclaration> loadFromFilesystem(AbstractFilesystem filesystem, Path mainWorkspace)

static

加载来自文件系统。

Loads subagent declarations via the AbstractFilesystem using an empty runtime context.

参数Parameters

名称Name	类型Type	说明Description
`filesystem`	AbstractFilesystem	文件系统（类型 `AbstractFilesystem`）。the filesystem layer (applies namespace transparently)
`mainWorkspace`	Path	主工作区（类型 `Path`）。the parent workspace for resolving relative workspace paths; may be `null`

返回Returns List<SubagentDeclaration>

返回列出。list of parsed declarations; never `null`

源码Source io/agentscope/harness/agent/subagent/AgentSpecLoader.java:136–139

loadFromFilesystem

public static List<SubagentDeclaration> loadFromFilesystem(AbstractFilesystem filesystem, RuntimeContext runtimeContext, Path mainWorkspace)

static

加载来自文件系统。

Loads subagent declarations via the AbstractFilesystem, respecting the supplied runtime context's namespace isolation.

参数Parameters

名称Name	类型Type	说明Description
`filesystem`	AbstractFilesystem	文件系统（类型 `AbstractFilesystem`）。the filesystem layer (applies namespace transparently)
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。the call context used to resolve namespace-scoped declarations
`mainWorkspace`	Path	主工作区（类型 `Path`）。the parent workspace for resolving relative workspace paths; may be `null`

返回Returns List<SubagentDeclaration>

返回列出。list of parsed declarations; never `null`

源码Source io/agentscope/harness/agent/subagent/AgentSpecLoader.java:151–189

loadFromFile

public static SubagentDeclaration loadFromFile(Path filePath, Path mainWorkspace) throws IOException

static

加载来自文件。

Parses a single Markdown declaration file.

参数Parameters

名称Name	类型Type	说明Description
`filePath`	Path	`.md`文件到解析。the `.md` file to parse
`mainWorkspace`	Path	主工作区（类型 `Path`）。workspace root used to resolve relative `workspace.path` values; may be `null`

返回Returns SubagentDeclaration

返回SubagentDeclaration。parsed declaration, or `null` if the file is malformed / missing required fields

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/subagent/AgentSpecLoader.java:200–205

parse

public static SubagentDeclaration parse(String markdown, String name, Path mainWorkspace)

static

执行解析相关操作。

Parses markdown content with YAML front matter into a SubagentDeclaration.

参数Parameters

名称Name	类型Type	说明Description
`markdown`	String	markdown（类型 `String`）。the full file content
`name`	String	名称（类型 `String`）。the subagent name (derived from the filename, without `.md`)
`mainWorkspace`	Path	主工作区（类型 `Path`）。workspace root used to resolve relative `workspace.path` values; may be `null`

返回Returns SubagentDeclaration

返回SubagentDeclaration。parsed declaration, or `null` if the content is malformed

源码Source io/agentscope/harness/agent/subagent/AgentSpecLoader.java:216–347