【SpringAI Alibaba】ReactAgent结构化输出OutputType与OutputSchema实战

目录

一、ReactAgent结构化输出OutputType实战

[1.1 什么是结构化输出](#1.1 什么是结构化输出)

[1.2 两种配置方式对比](#1.2 两种配置方式对比)

[1.3 整体工作流程](#1.3 整体工作流程)

[1.4 案例实战一：outputType 方式（推荐）](#1.4 案例实战一：outputType 方式（推荐）)

[1.5 关键点说明](#1.5 关键点说明)

二、ReactAgent结构化输出OutputSchema实战

[2.1 案例实战：outputSchema 方式（进阶）](#2.1 案例实战：outputSchema 方式（进阶）)

[2.2 嵌套复杂结构示例](#2.2 嵌套复杂结构示例)

[2.3 注意事项](#2.3 注意事项)

---

一、ReactAgent结构化输出OutputType实战

1.1 什么是结构化输出

• 定义：允许 Agent 以特定、可预测的格式返回数据，直接得到 JSON 对象或 Java POJO，应用程序可直接使用

• 核心原理：

  • ReactAgent 自动将 Java 类的字段信息转成 JSON Schema

  • 注入到 Prompt 指令中，模型按照 Schema 格式生成输出，框架再反序列化为 Java 对象

• 核心作用

  • ✅ 类型安全：编译期就知道返回字段，不再在运行时崩溃

  • ✅ 自动注入：框架自动将 Schema 指令加到 Prompt，无需手写提示词格式要求

  • ✅ 可维护：修改 Java 类字段，Schema 自动更新，代码即文档

1.2 两种配置方式对比

方式	方法	特点	推荐度
直接指定类型	.outputType(MyClass.class)	最简洁，框架自动生成 Schema	⭐⭐⭐ 推荐
手动提供 Schema	.outputSchema(schemaString)	灵活可定制，需要手动生成 String	⭐⭐ 进阶

1.3 整体工作流程

1.4 案例实战一：outputType 方式（推荐）

• 需求说明：解析用户输入，提取关键信息，返回 DTO 对象

• 第一步：定义输出 POJO 类（

@Data
public class CommentDTO {
    /**
     * 评论ID
     */
    private Long id;

    /**
     * 评论内容
     */
    private String content;

    /**
     * 用户名称
     */
    private String username;

    /**
     * 时间
     */
    private String createTime;
}

第二步：构建 ReactAgent，使用 .outputType()

@GetMapping(value = "/agent12", produces = "text/html;charset=utf-8")
public String agent12(@RequestParam(name = "msg") String msg) throws GraphRunnerException {
        ReactAgent reactAgent = ReactAgent.builder()
                .name("resume_extractor")
                .model(chatModel)
                .outputType(CommentDTO.class)           // 框架自动将类转为 JSON Schema
                .systemPrompt("你是一个评论专家，中文回复对应的问题")
                .build();

        AssistantMessage result = reactAgent.call(msg);
        String text = result.getText();  // 返回 JSON 字符串
        return text;
    }

测试：/api/v1/ai/agent7?msg=老王评论了这个手机壳质量不太好，他的ID是12123，在2028年12月1号评论的

1.5 关键点说明

• .outputType(CommentDTO.class) 内部使用 BeanOutputConverter 自动生成 JSON Schema

• result.getText() 返回的是符合 CommentDTO 结构的 JSON 字符串

• 若需要 Java 对象，再用 new ObjectMapper().readValue(text, CommentDTO.class) 转换

二、ReactAgent结构化输出OutputSchema实战

2.1 案例实战：outputSchema 方式（进阶）

• 需求说明：手动控制 Schema 格式，或复用已有的 BeanOutputConverter

import org.springframework.ai.converter.BeanOutputConverter;

@GetMapping(value = "/agent13", produces = "text/html;charset=utf-8")
public String agent13(@RequestParam(name = "msg") String msg) throws GraphRunnerException {
        // 第一步：用 BeanOutputConverter 生成 schema 字符串
        BeanOutputConverter<CommentDTO> converter = new BeanOutputConverter<>(CommentDTO.class);
        String schemaString = converter.getFormat();  // 生成标准 JSON Schema

        // 第二步：将 schema 传给 ReactAgent
        ReactAgent reactAgent = ReactAgent.builder()
                .name("resume_extractor")
                .model(chatModel)
                .outputSchema(schemaString)           // 手动传入 JSON Schema 字符串
                .systemPrompt("你是一个评论专家，中文回复对应的问题")
                .build();

        AssistantMessage result = reactAgent.call(msg);

        String text = result.getText();  // 返回 JSON 字符串
        // 第三步：反序列化为 Java 对象
        CommentDTO commentDTO = converter.convert(text);
        log.info("commentDTO:{}", commentDTO);
        return text;
}

• 关键点说明

  • converter.getFormat() 返回的是完整的 JSON Schema 字符串，框架将其注入 Prompt

  • converter.convert(text) 可将模型返回的 JSON 字符串直接反序列化为目标对象

  • outputSchema 和 outputType 本质相同，outputType 是其语法糖

2.2 嵌套复杂结构示例

• 支持嵌套对象、数组等复杂结构，框架会递归生成完整 Schema

// 定义嵌套输出类
public static class ProductReview {
    private int rating;           // 评分 1-5
    private String sentiment;     // 情感：正面/负面/中性
    private String[] keyPoints;   // 关键要点数组
    private ReviewDetails details;

    public static class ReviewDetails {
        private String[] pros;    // 优点列表
        private String[] cons;    // 缺点列表
        // Getters and Setters ...
    }
    // Getters and Setters ...
}

// 构建 Agent
ReactAgent agent = ReactAgent.builder()
        .name("review_analyzer")
        .model(chatModel)
        .outputType(ProductReview.class)   // 自动处理嵌套 Schema
        .build();

AssistantMessage result = agent.call(
    "分析评价：这个产品很棒，5星好评！配送快速，但价格稍贵。");
System.out.println(result.getText());
// 输出: {"rating": 5, "sentiment": "正面", "keyPoints": [...], "details": {"pros": [...], "cons": [...]}}

2.3 注意事项

• POJO 类必须有 Getter/Setter ：BeanOutputConverter 通过反射读取字段，Lombok 的 @Getter @Setter 可以简化

• 字段类型支持：基本类型、String、Date、数组、List、嵌套对象均支持，Map 类型慎用

• 模型并非100%稳定：小概率情况下模型仍可能偏离格式，生产环境建议加 try-catch 兜底

• 不要把 outputType 和 outputSchema 同时设置：两者选其一即可，同时设置会冲突

• 返回值是 JSON 字符串 ：AssistantMessage.getText() 返回 JSON 文本，需要自行解析为对象