文章目录1. 概述2. 三种声明方式2.1 工作区 spec 文件2.3 编程式声明2.3 内置 general-purpose3. 工作区3.1 ISOLATED默认自己独立的工作区3.2 SHARED直接共用主工作区4. 同步和异步执行4.1 后台任务自动反向通知4.2 后台任务工具逃生口4.3 给已存在的子 agent 补一条消息5. 持久会话6. 远程子 Agent7. 注意事项8. 入门案例1. 概述主Agent在一个会话里把所有事都做完有两个坏处上下文膨胀无关细节挤占主线对话无法并行一件件串着干。子Agent的思路是把可独立处理、上下文重、可并行的任务委派出去每个子Agent是一个临时实例本地的HarnessAgent或远程stub子Agent跑自己独立的会话结果通过工具调用返回给父agent。这样主Agent的对话保持清爽只看到我派了个子任务、拿回了一份结果而调研/审查/检索这类重活在子会话里完成。2. 三种声明方式子Agent支持三类来源构建时合并方式适用怎么配内置 general-purpose通用兜底镜像主 agent 能力总是有不需要配工作区 spec 文件项目特有、可版本控制workspace/subagents/id.md编程式声明跑时才能确定远程、动态参数builder.subagent(SubagentDeclaration.builder()...)2.1 工作区 spec 文件框架非递归扫描workspace/subagents/*.md文件文件名去掉.md即agent_id唯一标识不要在front matter里再写name。完整的front matter字段--- description: 代码评审专家 # 必填agent 选择是否委派的关键依据 workspace: mode: isolated # 默认 isolatedshared 表示与父共享工作区 path: ./defs/reviewer # 可选不写则用默认子目录 model: openai:gpt-4o-mini # 可选不写则继承父 agent steps: 8 # 可选该子 agent 单次最多迭代次数 temperature: 0.2 # 可选覆盖父的 GenerateOptions top_p: 0.95 # 可选 hidden: false # true 时不出现在可见列表仍可程序化 spawn mode: subagent # primary / subagent / all默认 allprimary 不允许被 spawn expose_to_user: true # 可选三态强制/禁止向用户暴露见【37】 tools: [read_file, grep_files] # 可选继承工具的白名单 --- 你是一个专注代码评审的子 agent。2.3 编程式声明跑时才能确定的子agent远程地址、动态参数用builder声明importio.agentscope.harness.agent.subagent.SubagentDeclaration;importio.agentscope.harness.agent.subagent.WorkspaceMode;HarnessAgent.builder().name(orchestrator).model(model).workspace(workspace)// 本地子 agent独立工作区 指定模型 工具白名单.subagent(SubagentDeclaration.builder().name(reviewer).description(代码审查专家).workspace(Path.of(./defs/reviewer))// 来源一本地工作区目录.workspaceMode(WorkspaceMode.ISOLATED).model(qwen3-max)// 不写则继承父 agent.steps(8)// 单次最多迭代 8 步.tools(List.of(read_file,grep_files))// 工具白名单.build())// 远程子 agent只填 url 可选 headers走 Agent Protocol.subagent(SubagentDeclaration.builder().name(remote-researcher).description(远端调研子 agent).url(http://agent-task-server:8080)// 来源三远程 HTTP 服务.headers(Map.of(Authorization,Bearer xxx)).build()).build();三种来源互斥workspace(...)、inlineAgentsBody(...)、url(...)三选一。workspace指向本地定义目录inlineAgentsBody直接内联spec正文url走远程。2.3 内置 general-purpose不需要写任何声明文件总是可用除非你显式disableSubagents()。general-purpose就是主agent的一个克隆模型、工具、技能、工作区都和主agent一致唯一区别是它跑在独立的子会话里、且不能再往下委派。它的价值是上下文隔离 零配置当你想把一个子任务丢到一段干净的新对话里跑避免一堆中间过程污染主线对话而这个子任务又需要完整能力读写文件、执行命令、调技能……、且不值得为它专门写一份spec时直接用它最省事。HarnessAgent默认会创建这个general-purpose并告知大模型于是模型实际看到的系统提示里有这么一段### Available agent ids - general-purpose: General-purpose subagent with same capabilities as the main agent. - reviewer: 代码审查专家。当用户需要 review PR、找代码问题、检查代码规范时使用。自定义spec子agent的区别内置 general-purpose工作区 spec 子 agent如 reviewer是否要写文件不用总是有要写subagents/id.md能力范围全量镜像主 agent同模型/工具/技能可收窄如只给read_file/grep_files 自定义角色提示词工作区SHARED共享主工作区默认ISOLATED独立适合临时的、任意的子任务需要完整能力反复使用、需要约束、可版本控制的专门角色3. 工作区workspaceMode决定子agent的运行时工作区根目录怎么算它直接影响子agent能读写哪些文件、状态存在哪、以及多租户会不会串。3.1 ISOLATED默认自己独立的工作区子agent有一块属于自己的运行时工作区和主agent物理隔开声明里写了workspace.path该路径既是运行时根也是它AGENTS.md系统提示的来源。适合这个子 agent 有一套自己的定义目录含skills/knowledge。没写workspace.path框架自动在mainWorkspace/agents/name/workspace/开一个子目录作运行时根并用spec的正文inline body作系统提示。ISOLATED还有一个关键特性持久化状态按父会话 用户分桶当spawn时的RuntimeContext带了userId/parentSessionId子agent的状态key形如{declarationName}[{parentSessionId}][#{userId}]这个分桶规则在所有AgentStateStoreWorkspace/Redis/InMemory/ 自定义上统一生效。带来的直接好处是同一个用户在不同对话里spawn同名子agent彼此互不污染不同用户之间更是天然隔离多租户安全边界不会因为委派而被打破。适用场景要干净隔离、不想让子agent的临时文件/状态弄脏主工作区、或有多租户隔离诉求时。这也是默认值拿不准就用它。3.2 SHARED直接共用主工作区子agent的运行时根永远是mainWorkspace无论声明里workspace.path写没写写了workspace.path只借用它的AGENTS.md作系统提示正文但定义目录里的skills/、knowledge/、MEMORY.md都会被忽略因为运行时根不是它。没写workspace.path用inline body作系统提示。SHARED不做按用户/会话分桶它有意复用父的bucket、不做多租户隔离。使用场景子agent的产出需要被父agent立即读到父子共享同一份文件或者你就是想让子agent站在主工作区里干活。内置的general-purpose 恒为 SHARED正是因为它的定位就是主agent的克隆、产出即时可见。4. 同步和异步执行主agent通过agent_spawn创建子agent关键参数是timeout_seconds 0默认30执行同步调用主agent在这一步block 等待结果子agent的结果作为工具结果返回。timeout_seconds 0执行后台调用立即返回一个task_id子agent在后台跑。4.1 后台任务自动反向通知后台任务跑完主agent不需要轮询下一次推理开始前框架会把已完成的任务结果作为系统提醒注入对话末尾system-reminder 后台任务已交付 - task_idxxxagentresearch-analyststatusCOMPLETED 结果摘要... /system-reminder主agent看到这条reminder自然地回应或继续行动。所以你不需要在prompt里写记得调 task_output 轮询那是旧版本的做法。4.2 后台任务工具逃生口子agent的生命周期由两组工具配合完成工具职责agent_spawn创建子 agent可选地执行任务同步或后台agent_send向已存在的子 agent 追加消息agent_list列出当前活跃的子 agent 实例task_output通过task_id获取后台任务结果阻塞或非阻塞task_cancel取消正在运行的后台任务task_list列出所有后台任务及其当前状态其中agent_spawn/agent_send管理子 agent 实例创建、复用、通信task_output/task_cancel/task_list管理后台任务结果查状态、取结果、取消。两者的桥梁是task_id在agent_spawn或agent_send用timeout_seconds0时返回。大多数情况下自动反向通知会把结果推回来不需要显式调用这些任务工具。它们主要作为逃生口反向通知触发前主动查进度、取消不再需要的任务、或对话压缩后恢复任务状态。4.3 给已存在的子 agent 补一条消息agent_spawn返回值里有一个agent_key运行时实例句柄用它或label就能后续追加消息agent_send agent_keyagent:reviewer:abc-123 message顺便也看下 schema 变更spawn时若设了label也可以用label寻址agent_spawn agent_idreviewer taskreview 这次 PR labelpr-reviewer agent_send labelpr-reviewer message顺便也看下 schema 变更要列当前活跃的子agentagent_list。5. 持久会话默认每次agent_spawn都创建新的子agent实例和会话不保留之前调用的上下文。在声明里设persistSession(true)可让同一子agent在多次spawn之间复用.subagent(SubagentDeclaration.builder().name(note-taker).description(跨对话轮次积累笔记).persistSession(true)// 复用实例对话历史与状态都保留.build())开启后框架按(parentSessionId, agentId, label)生成确定性的 key。再次spawn相同组合时会复用已存在的agent实例对话历史和状态都保留。6. 远程子 Agent声明里只填url 可选headers子agent就走远程HTTP服务Agent Protocol执行.subagent(SubagentDeclaration.builder().name(remote-researcher).description(远端调研子 agent).url(http://agent-task-server:8080).headers(Map.of(Authorization,Bearer xxx)).build())同样支持同步timeout_seconds0和后台timeout_seconds0。后台任务的状态默认写到workspace/agents/parentAgentId/tasks/sessionId.json。这带来三个特性共享存储模式多副本下任意节点都能读到任务状态任务执行粘在创建节点但完成结果会被任意节点读到、并能正常推回父agent想取消可从任意节点调task_cancel执行节点轮询取消标记后中止。7. 注意事项项目详细说明工具描述优化description是模型判断是否委派任务的核心依据。劣质写法代码评审优质写法当用户要 review PR、找代码风格问题时使用必须写明触发场景提升调用命中率。递归保护子Agent强制标记为叶子节点leaf worker系统提示禁止继续派生子Agent。委派链路固定为主Agent → 子Agent不允许无限递归spawn。租户上下文透传父AgentRuntimeContext.userId自动透传给子Agent多租户隔离链路不会断裂。权限继承策略1. 默认开启父Agent所有 DENY 拒绝规则自动继承给子Agent防止权限逃逸2. 可手动关闭inheritParentPermissions(false)3. PlanMode只读状态不会自动向下继承。父子事件流式转发父Agent调用streamEvents()时子Agent的中间事件实时回流到父级Flux流并携带来源标记。8. 入门案例最简单的用法把子agent的描述 写到工作区里就行文件名就是agent_id。示例在workspace/subagents/reviewer.md定义一个子智能体--- description: 代码审查专家。当用户需要 review PR、找代码问题、检查代码规范时使用。 --- 你是一个专注代码评审的子 agent。请按以下流程工作 1. 先 read_file / grep_files 收集上下文 2. 给出按文件 / 行号的具体建议 3. 末尾给一个 1-5 的总体评分其中description是主 agent 决定要不要委派的关键依据务必写清楚什么时候该用它下面的正文就是这个子agent的系统提示词。然后主Agent在推理时就能直接调用无需任何注册agent_spawn agent_idreviewer taskreview 这次 PR 的所有改动