# 第七章 子 Agent 编排：SubagentDeclaration + agent_spawn，主 Agent 委派子任务

> "以前我们用 `SequentialPipeline` 串三个 agent、用 `FanoutPipeline` 并行三个 agent、用 `MsgHub` 在多 agent 间广播消息……2.0 把这三种用法统一成了 **『子 agent + 同步/异步 spawn』** 一种范式：你的主 agent 就像一个『包工头』，对 LLM 喊一声'叫个翻译来'，它会自己 spawn 一个翻译 subagent 并把结果带回来。"
>
> 本章你将学到：如何用 `SubagentDeclaration` 描述子 agent、如何让主 agent 通过 `agent_spawn` 工具调用它们、同步与异步的差别、以及文件驱动的 subagent 描述如何让 1.x 的 Pipeline 写法**彻底消失**。

## 7.1 Pipeline 已经是历史

1.x 提供了一组"组织多个 agent"的抽象：

- `SequentialPipeline` —— 把 agent 串成流水线
- `FanoutPipeline` —— 把同一输入广播到多个 agent
- `MsgHub` —— 多个 agent 共享同一个消息总线
- `Pipelines.conversation()` —— 让多个 agent 在同一个 hub 里自由聊天

这些 API 在 2.0.0-RC2 中**被整体移除**。原因也很简单：LLM 自己做编排（"现在应该叫翻译"）远比写死 Pipeline 更鲁棒、更灵活。2.0 用一个"工具调用"代替了所有这些——

| 1.x 概念 | 2.0 替代 |
|----------|----------|
| `SequentialPipeline(a, b, c)` | 主 agent 决定**先**调 a、`agent_spawn` a 拿结果、再**调** b、最后调 c |
| `FanoutPipeline([a, b, c])` | 主 agent 用 `agent_spawn` `timeout_seconds=0` **并行** 调 a、b、c |
| `MsgHub` 多 agent 对话 | 主 agent 在循环里 `agent_spawn` 多个 subagent 并把上轮的回复喂回去 |
| `Pipelines.conversation()` | 同上，但用 `HarnessAgent` 的 subagent 文件做"角色表" |

> **⚠️ 2.0 重大变更**
>
> 2.0 移除了整个 `io.agentscope.core.pipeline` 包。如果你正在把 1.x 旧工程升到 2.0，遇到 `import io.agentscope.core.pipeline.*` 编译失败，请按本章 7.6 的迁移清单做改造。

## 7.2 第一个 subagent 例子：翻译

```java
import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.subagent.SubagentDeclaration;
import io.agentscope.harness.HarnessAgent;

import java.nio.file.Path;
import java.util.List;

public class Chapter07_FirstSubagent {

    public static void main(String[] args) {
        // 1. 描述一个「翻译 subagent」：叫什么、prompt 是什么、用什么模型
        SubagentDeclaration translator =
                SubagentDeclaration.builder()
                        .id("translator")
                        .description("中英互译；输入文本，输出翻译结果")
                        .sysPrompt("你是一个中英互译助手，只返回翻译后的文本，不要解释。")
                        .model(DashScopeChatModel.builder()
                                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                                .modelName("qwen-plus")
                                .build())
                        .build();

        // 2. 构造主 agent，把 subagent 注册进去
        HarnessAgent main = HarnessAgent.builder()
                .name("main")
                .sysPrompt("""
                        你是一个调度员。
                        需要把用户输入翻译成英文时调用 translator subagent。
                        """)
                .model(DashScopeChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen-plus")
                        .build())
                .workspace(Path.of("./workspace"))
                .subagent(translator)
                .build();

        // 3. 主 agent 会自己判断要不要 spawn translator
        main.call(
                List.of(new UserMessage("user", "把'今天杭州有雷阵雨'翻译成英文。")),
                io.agentscope.core.RuntimeContext.empty())
                .block();
    }
}
```

跑一下你会发现：主 agent 在 1 轮里就调用了 `agent_spawn` 工具，把任务交给 translator，再把 translator 的输出整合成最终回复——整个过程对业务代码透明。

## 7.3 `SubagentDeclaration` 字段速查

`SubagentDeclaration`（`io.agentscope.core.subagent`）描述一个 subagent：

| 字段 | 必填 | 说明 |
|------|------|------|
| `id` | 是 | 唯一 ID，主 agent 通过这个 ID 来 `agent_spawn` |
| `description` | 是 | **主 agent 看这段描述来决定是否调用**——写好描述等于写好路由表 |
| `sysPrompt` | 是 | subagent 的系统提示 |
| `model` | 否 | 缺省时继承主 agent 的 model |
| `tools` | 否 | 缺省时继承主 agent 的 tool 组 |
| `middleware` | 否 | subagent 自己的中间件（不继承主 agent） |
| `workspace` | 否 | 缺省时与主 agent 共享 workspace |

> **写好 `description` 非常关键**——主 agent 完全靠它判断"我该不该调这个 subagent"。描述里务必写清楚：subagent 是干嘛的、什么时候该调、输入和输出是什么。

## 7.4 同步 vs 异步：靠 `timeout_seconds`

`agent_spawn` 工具的入参：

| 字段 | 含义 |
|------|------|
| `agent_id` | 要调用的 subagent ID |
| `task` | 给 subagent 的自然语言任务 |
| `timeout_seconds` | **同步超时阈值**：`> 0` 同步等待 N 秒；`= 0` 立即返回（异步） |

### 7.4.1 同步 spawn（`timeout_seconds > 0`）

主 agent 等到结果回来再继续推理。**最常用**——"主 agent 把 subagent 当成工具函数"。

```text
主 agent：
  1. LLM 决定调用 translator，timeout_seconds=10
  2. Harness 启动 translator subagent，等它跑完（最多 10 秒）
  3. 把 subagent 的最终输出回填给主 agent
  4. 主 agent 继续推理
```

### 7.4.2 异步 spawn（`timeout_seconds = 0`）

主 agent 立刻拿到一个"任务 ID + 状态"对象，主 agent 可以**继续做别的事**，稍后再用 `agent_list` / `agent_send` 拉结果。

```text
主 agent：
  1. LLM 决定"同时调研 3 个问题"，对 3 个 subagent 各发一次 async spawn
  2. 3 个 subagent 并行启动（fanout）
  3. 主 agent 立即拿到 3 个 task_id
  4. 主 agent 写 `todo_write` 记下要跟踪
  5. 后续轮次里主 agent 用 `agent_send` 问"搞完没？"
```

> **异步 spawn 的最佳搭档是 `todo_write`**：主 agent 起任务时把 task_id 写到 todo 列表，每轮 `agent_send` 看哪些完成、回填哪些结果。详见第 12 章 Plan Mode。

## 7.5 文件驱动的 subagent：让 prompt 离开 Java 代码

`SubagentDeclaration` 写死在 Java 里没问题，但生产中我们常希望"产品经理改一段描述就能调整路由"——2.0 推荐用文件描述：

```text
workspace/
└── subagents/
    ├── translator.md
    ├── weather_lookup.md
    └── invoice_parser.md
```

每个文件就是一份 YAML/Markdown 描述：

```markdown
# translator.md
id: translator
description: 中英互译；输入文本，输出翻译结果
sysPrompt: |
  你是一个中英互译助手。
  只返回翻译后的文本，不要解释。
```

然后：

```java
HarnessAgent main = HarnessAgent.builder()
        ...
        .workspace(Path.of("./workspace"))   // 自动扫描 subagents/*.md
        .build();
```

`HarnessAgent.builder().workspace(...)` 会自动加载 `workspace/subagents/` 下所有 `*.md` / `*.yaml` 文件，省去 Java 端重复注册。

## 7.6 最小迁移清单（1.x Pipeline → 2.0 subagent）

| 1.x 用法 | 2.0 等价 |
|----------|----------|
| `SequentialPipeline(a, b, c).run(x)` | 主 agent 依次 `agent_spawn a / b / c`（同步） |
| `FanoutPipeline([a, b, c]).run(x)` | 主 agent 一次发 3 个 `timeout_seconds=0` 的 async spawn |
| `MsgHub.broadcast(msg)` | 主 agent 写一段自然语言 prompt，让所有 subagent 各自跑 |
| `Pipelines.conversation([a, b, c])` | 主 agent 持有 subagent 列表，每轮 `agent_spawn` + 拼接 |
| `pipeline.run(Msg)` | `main.call(List.of(new UserMessage("user", task)), ctx)` |

迁移技巧：**把 Pipeline 的每一步都想象成"主 agent 的一个工具调用"**。1.x 写死的执行顺序，2.0 让 LLM 在 system prompt + subagent description 的引导下自主决定——一开始可能觉得不踏实，跑两个 case 就发现它比硬编码灵活得多。

## 7.7 完整可运行示例

```java
import io.agentscope.core.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.subagent.SubagentDeclaration;
import io.agentscope.harness.HarnessAgent;

import java.nio.file.Path;
import java.util.List;

public class Chapter07_Fanout {

    public static void main(String[] args) {
        DashScopeChatModel model = DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-plus")
                .build();

        // 3 个并行调研 subagent
        SubagentDeclaration legal   = research("legal",   "做法律合规研究");
        SubagentDeclaration finance = research("finance", "做财务分析");
        SubagentDeclaration tech    = research("tech",    "做技术可行性评估");

        HarnessAgent main = HarnessAgent.builder()
                .name("project_due_diligence")
                .sysPrompt("""
                        你是一个项目尽调主管。
                        同时调用 legal / finance / tech 三个 subagent 调研同一议题，
                        最后综合三方结果给出一句话结论。
                        """)
                .model(model)
                .workspace(Path.of("./workspace"))
                .subagent(legal)
                .subagent(finance)
                .subagent(tech)
                .build();

        main.call(
                List.of(new UserMessage("user", "我们想在杭州开一家 50 平米咖啡店，请三路调研。")),
                RuntimeContext.empty())
                .block();
    }

    static SubagentDeclaration research(String id, String role) {
        return SubagentDeclaration.builder()
                .id(id)
                .description(role + "；输入是项目描述，输出是结构化要点（最多 5 条）")
                .sysPrompt("你是一个尽调分析师，专注 " + role + "。")
                .build();
    }
}
```

跑一下你会看到三个 subagent 的输出被自动拼成一份"尽调备忘录"。

## 7.8 本章小结

- 2.0 移除了 1.x 的 Pipeline / MsgHub；改用 `SubagentDeclaration` + 主 agent 自带的 `agent_spawn` 工具。
- 同步 spawn（`timeout_seconds > 0`）= 拿结果再走；异步 spawn（`timeout_seconds = 0`）= 立即返回 task_id，主 agent 后续用 `agent_send` 拉。
- 写好 `description` 字段 = 写好路由表——主 agent 全靠它判断"该不该调"。
- 文件驱动：`workspace/subagents/*.md` 让产品经理也能调路由。

下一章我们把同样的思路推到"多 agent 协作"——用 orchestrator + workers 的模式做狼人杀 / 群聊 / 多 agent 决策。


"以前我们用 SequentialPipeline 串三个 agent、用 FanoutPipeline 并行三个 agent、用 MsgHub 在多 agent 间广播消息……2.0 把这三种用法统一成了 『子 agent + 同步/异步 spawn』 一种范式：你的主 agent 就像一个『包工头』，对 LLM 喊一声'叫个翻译来'，它会自己 spawn 一个翻译 subagent 并把结果带回来。"

【AgentScope Java新手村系列】（7）子Agent编排

子Agent编排 — SubagentDeclaration 描述子 agent，主 agent 通过 agent_spawn 工具同步/异步委派子任务。

编程语言

架构设计

人工智能

"AgentScope 2.0引入子Agent编排新范式，通过SubagentDeclaration定义子Agent，主Agent使用agent_spawn工具动态调用。相比1.x的Pipeline模式，新方案更灵活智能，支持同步/异步调用和文件配置。主Agent根据子Agent描述自动路由任务，实现类似包工头的智能调度能力，让LLM自主决定任务分配。"

中间件

路由

Agent

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

"AgentScope 2.0引入子Agent编排新范式，通过SubagentDeclaration定义子Agent，主Agent使用agent_spawn工具动态调用。相比1.x的Pipeline模式，新方案更灵活智能，支持同步/异步调用和文件配置。主Agent根据子Agent描述自动路由任务，实现类似包工头的智能调...

【AgentScope Java新手村系列】（7）子Agent编排-腾讯云开发者社区-腾讯云

【AgentScope Java新手村系列】（7）子Agent编排

【AgentScope Java新手村系列】（7）子Agent编排

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐