# 第十章 实战：多 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 工程结构

```text
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`：

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

`workspace/subagents/flight.md`：

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

`workspace/subagents/attraction.md`：

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

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

## 10.3 在 Java 端补强 subagent

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

```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`：

```java
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 里加：

```text
"用户问题涉及多主题时，优先使用 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`：

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

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

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

## 10.6 完整工程演示

`pom.xml`：

```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/` 会自动生成：

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

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

## 10.7 本章小结

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

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


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

【AgentScope Java新手村系列】（10）实战-多Agent天气助手

实战-多Agent天气助手 — 文件驱动 subagent 实战，主 agent 自主编排天气查询、航班搜索、景点推荐三个子任务并行调研。

人工智能

后端

开发工具

本文介绍多Agent天气助手实战，通过文件驱动Subagent实现主Agent自主编排天气、航班、景点查询。采用workspace/subagents/*.md文件描述Subagent，主Agent根据需求动态调用，支持同步/异步并行调研。包含Java端Subagent补强、工具注册、跨会话记忆等关键技术点，展示2.0版本灵活的任务调度能力。

中间件

多云

路由

Agent

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

本文介绍多Agent天气助手实战，通过文件驱动Subagent实现主Agent自主编排天气、航班、景点查询。采用workspace/subagents/*.md文件描述Subagent，主Agent根据需求动态调用，支持同步/异步并行调研。包含Java端Subagent补强、工具注册、跨会话记忆等关键技术点，展示2.0...

【AgentScope Java新手村系列】（10）实战-多Agent天气助手-腾讯云开发者社区-腾讯云

【AgentScope Java新手村系列】（10）实战-多Agent天气助手

【AgentScope Java新手村系列】（10）实战-多Agent天气助手

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐