第十章 实战：多 Agent 天气助手——文件驱动 Subagent，主 Agent 自主编排天气/航班/景点

"用户问：'我明天从北京飞杭州，落地后去西湖，要带伞吗？'——1.x 时代我们用 Pipeline 串天气、航班、景点三个 agent。2.0 我们用 subagent + workspace/subagents/*.md 文件描述：主 agent 自己决定先查天气还是先查航班，三个 subagent 并行启动。这是 2.0 推荐的『文件驱动 subagent』实战。"

本章你将学到：如何用文件描述 subagent、如何用 SubagentDeclaration 在 Java 端补强、如何用 agent_spawn 同步 / 异步组合出并行调研。

10.1 工程结构

travel-assistant/
├── pom.xml
└── workspace/
    ├── MEMORY.md
    ├── subagents/
    │   ├── weather.md
    │   ├── flight.md
    │   └── attraction.md
    └── state/
        └── session-*.json   (JsonFileAgentStateStore 自动生成)

10.2 三个 subagent 文件

workspace/subagents/weather.md：

id: weather
description: |
  查城市天气。
  输入：城市名 + 日期（YYYY-MM-DD）。
  输出：温度区间、是否下雨、是否需要带伞。
sysPrompt: |
  你是一个气象助理。
  用户给你一个城市和日期，你返回：
  - 温度（高/低，摄氏度）
  - 是否下雨
  - 是否需要带伞
  严格三行，不超过 60 字。

workspace/subagents/flight.md：

id: flight
description: |
  查航班信息（mock）。
  输入：出发城市 + 到达城市 + 日期。
  输出：航班号、起飞时间、到达时间。
sysPrompt: |
  你是一个航班查询助理。
  根据用户输入给出一个 mock 航班号和起降时间。
  注意：测试环境，无需真查询，给出合理 mock 即可。

workspace/subagents/attraction.md：

id: attraction
description: |
  景点信息助理（mock）。
  输入：城市 + 景点名。
  输出：开放时间、是否需要预约、周边交通。
sysPrompt: |
  你是一个导游助理。
  根据用户输入给出景点的实用信息。

这三份描述对主 agent 来说是路由表——主 agent 全靠 description 决定要不要 spawn 它们。

10.3 在 Java 端补强 subagent

如果某些 subagent 需要 Java 端的工具（例如 weather.md 背后要接真的天气 API），可以在 Java 端再注册一份——HarnessAgent 会把文件 + Java 声明合并：

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.harness.agent.subagent.SubagentDeclaration;
import io.agentscope.harness.HarnessAgent;

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

public class Chapter10_TravelAssistant {
   

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

        // 创建 toolkit 并注册天气查询工具
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new WeatherLookupTool());

        // Java 端补强 weather subagent —— tools 白名单过滤继承自父 agent 的工具
        SubagentDeclaration weather =
                SubagentDeclaration.builder()
                        .name("weather")
                        .description("查城市天气；输入城市+日期，返回温度区间和是否带伞")
                        .inlineAgentsBody("你是一个气象助理，会调用 weather_lookup 工具查真实天气。")
                        .model(model)
                        .tools(List.of("weather_lookup"))   // 白名单：只允许 weather_lookup
                        .build();

        HarnessAgent host = HarnessAgent.builder()
                .name("travel_assistant")
                .sysPrompt("""
                        你是一个出行助理。
                        用户给一段出行需求，自己决定：
                        1. 是否需要查天气 → spawn weather
                        2. 是否需要查航班 → spawn flight
                        3. 是否需要查景点 → spawn attraction
                        最后用一段自然语言综合三方信息回复用户。
                        """)
                .model(model)
                .toolkit(toolkit)                           // 父 agent 持有所有工具
                .workspace(Path.of("./workspace"))          // 自动加载 subagents/*.md
                .subagent(weather)                          // Java 端补强
                .build();

        host.call(
                List.of(new UserMessage("user", "我明天从北京飞杭州，落地后去西湖，要带伞吗？")),
                RuntimeContext.empty())
                .block();
    }
}

WeatherLookupTool.java 是个简单的 @Tool：

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;

public class WeatherLookupTool {
   

    @Tool(name = "weather_lookup", description = "查城市天气")
    public String lookup(
            @ToolParam(name = "city") String city,
            @ToolParam(name = "date") String date) {
   

        // 实际生产里调 https://api.weather.com/...
        // 这里 mock
        return String.format("%s 在 %s 的天气：22~28℃，局部多云，建议带伞。", city, date);
    }
}

10.4 同步 vs 异步 spawn 的选择

weather / flight / attraction 三件事互不依赖，可以让主 agent 用 async spawn 三连发。需要在主 agent 的 system prompt 里加：

"用户问题涉及多主题时，优先使用 timeout_seconds=0 的 async spawn 一次发出，
 拿到 task_id 后用 todo_write 跟踪，最后统一汇总。"

agent_spawn + todo_write 的组合就是 2.0 的"fanout pipeline"——比 1.x FanoutPipeline 更灵活。

如果用户明确说"先告诉我航班，再决定要不要去"——主 agent 会自己用同步 spawn 等结果再决定下一步。这正是 2.0 优于 1.x 的地方：调度逻辑由 LLM 在 system prompt 引导下自主决定。

10.5 跨会话记忆：把"用户的常驻地"写进 MEMORY.md

第一轮对话里用户说"我从北京出发"——主 agent 把这条信息写进 workspace/MEMORY.md：

# MEMORY.md
## 用户偏好
- 常驻城市：北京
- 喜欢：少排队

第二周用户再问"周末去上海玩两天"——主 agent 看到 MEMORY.md 知道"用户在北京"，主动把返程航班算成"北京-上海-北京"。

CompactionMiddleware 配好后，2.0 自动维护这份记忆；详见第 18 章。

10.6 完整工程演示

pom.xml：

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>demo</groupId>
    <artifactId>travel-assistant</artifactId>
    <version>0.1.0</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <agentscope.version>2.0.0-RC2</agentscope.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.agentscope</groupId>
            <artifactId>agentscope-harness</artifactId>
            <version>${agentscope.version}</version>
        </dependency>
    </dependencies>
</project>

启动后看 workspace/state/ 会自动生成：

session-2026-06-07T10-23-15.json

里面是这通对话的完整状态；下次再用相同 sessionId 调用，状态会自动恢复。

10.7 本章小结

• workspace/subagents/*.md 让产品经理也能调路由。
• Java 端 SubagentDeclaration 可补强：自定义工具 / 自定义模型 / 自定义中间件。
• 同一份 HarnessAgent 可以被多次调用，每次用 RuntimeContext.sessionId 隔离会话。
• MEMORY.md 跨会话记忆，由 CompactionMiddleware 自动维护。

下一章我们讨论"中断与恢复"——用户聊到一半关了浏览器，二十分钟后回来，怎么让 agent 接着聊。