Spring AI Alibaba Agent 结构化输出（Structured Output）完整指南

基于 Spring AI Alibaba 1.1.2.0，实现 Agent 按标准 JSON 格式返回数据，支持 Java POJO 自动映射，提升程序化消费效率

一、概述

结构化输出是 Agent 框架中一项重要能力，它允许 Agent 以固定的、可预测的格式（如 JSON）返回数据，而不是自然语言的自由文本。这极大地简化了应用程序对 Agent 输出的解析和处理，尤其适用于数据提取、系统集成、API 对接等场景。

Spring AI Alibaba 通过 ReactAgent.Builder 提供了两种简洁的方式来实现结构化输出，同时框架自动处理 JSON Schema 的生成与注入，开发者只需关注业务逻辑。

本文将通过一个完整的可运行示例，从零开始演示如何配置和使用结构化输出，并特别强调在实际开发中必须处理的异常情况。

二、核心概念

2.1 什么是结构化输出？

结构化输出是指 Agent 按照预定义的格式（通常是 JSON）返回数据，该格式可直接映射为 Java 对象（POJO）。与传统的自然语言响应相比，结构化输出具有以下优势：

| 对比维度

|

自然语言输出

|

结构化输出

输出格式

|

自由文本

|

固定 JSON 结构

| |

解析方式

|

正则/字符串处理

|

直接 JSON 反序列化

| |

类型安全

|

弱

|

强（编译期校验）

| |

应用场景

|

聊天问答

|

数据提取、系统集成

|

典型场景：从一段描述中提取联系人信息（姓名、邮箱、电话），Agent 直接返回 {"name":"张三","email":"zhangsan@example.com","phone":"123456"}。

2.2 实现方式

Spring AI Alibaba 提供两种实现方式：

| 方法

|

说明

|

推荐度
.outputType(Class<?> type)

传入 Java 类，框架自动生成 JSON Schema

|

⭐⭐⭐⭐⭐ 强烈推荐

| | .outputSchema(String schema) |

手动传入 JSON Schema 字符串

|

仅特殊场景

|

推荐理由：outputType 利用 Java 类型信息自动生成 Schema，维护成本低，且编译期即可发现类型错误。

2.3 工作原理

  1. 调用前

    ：框架通过 BeanOutputConverter 根据 POJO 或手动 Schema 生成 JSON 格式指令，追加到用户消息后。

  2. 调用中

    ：模型按指令生成符合 Schema 的 JSON 字符串。

  3. 调用后

    ：返回的 AssistantMessage.getText() 即为 JSON 字符串，开发者可反序列化为 POJO。

模型兼容性：对于支持原生结构化输出的模型（如 DashScopeChatModel），框架优先使用原生能力；否则回退到 ToolCall 策略。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

三、完整示例项目

3.1 项目结构

<span leaf="leaf">spring-ai-structured-output-demo/</span>

3.2 依赖配置（pom.xml）

<span leaf="leaf">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>

3.4 输出 POJO 定义

简单 POJO（联系人信息）

<span leaf="leaf"><span>package</span>&nbsp;<span>com.example.ai.model</span>;</span>

复杂嵌套 POJO（商品评价）

<span leaf="leaf"><span>package</span>&nbsp;<span>com.example.ai.model</span>;</span>

3.5 Agent 配置类（AgentConfig.java）

<span leaf="leaf"><span>package</span>&nbsp;<span>com.example.ai.config</span>;</span>

3.6 Service 层（含异常处理）

关键点：reactAgent.call(...) 可能抛出 GraphRunnerException，必须捕获并进行妥善处理。

<span leaf="leaf"><span>package</span>&nbsp;<span>com.example.ai.service</span>;</span>

为什么要捕获 GraphRunnerException？
ReactAgent.call() 方法在 Agent 执行过程中可能因多种原因失败（如模型调用超时、工具执行错误、状态保存失败等），如果不捕获，异常将向上传播导致接口返回 500。通过捕获并转换为业务异常，可以更好地控制错误响应。

3.7 Controller 层

<span leaf="leaf"><span>package</span>&nbsp;<span>com.example.ai.controller</span>;</span>

3.8 启动类

<span leaf="leaf"><span>package</span>&nbsp;<span>com.example.ai</span>;</span>

四、测试与验证

4.1 启动应用

确保环境变量 DASHSCOPE_API_KEY 已设置，运行：

<span leaf="leaf">mvn spring-boot:run</span>

4.2 测试联系人提取（返回 POJO）

<span leaf="leaf"><span>curl</span>&nbsp;<span>-X</span>&nbsp;POST&nbsp;<span>"http://localhost:885/api/structured/contact?text=从以下信息提取联系方式：王五，wangwu@outlook.com，+86 139-9999-8888&amp;sessionId=test01"</span></span>

预期响应：

<span leaf="leaf">{</span>

图片

4.3 测试原始 JSON 输出

<span leaf="leaf"><span>curl</span>&nbsp;<span>-X</span>&nbsp;POST&nbsp;<span>"http://localhost:885/api/structured/contact/raw?text=赵六，zhaoliu@163.com，010-88886666&amp;sessionId=test01"</span></span>

预期响应：

<span leaf="leaf">{</span>

图片

4.4 测试商品评价分析

<span leaf="leaf"><span>curl</span>&nbsp;<span>-X</span>&nbsp;POST&nbsp;<span>"http://localhost:885/api/structured/review?reviewText=这款耳机音质不错，降噪效果好，但佩戴舒适度一般，价格略高。&amp;sessionId=test01"</span></span>

预期响应（结构示例）：

<span leaf="leaf">{</span>

图片

4.5 查看日志

控制台会输出 DEBUG 信息，包括 Agent 追加的 Schema 指令以及模型返回的原始 JSON，便于调试。

五、异常处理最佳实践

在 Service 层捕获 GraphRunnerException 并转换为业务异常，可以避免底层异常暴露给前端，同时便于统一错误处理。

| 异常类型

|

处理方式
GraphRunnerException

记录日志，转换为业务异常（如 RuntimeException）

| | JsonProcessingException |

记录原始 JSON，抛出解析异常

| |

其他未预期异常

|

记录错误信息，返回通用错误码

|

建议在 Controller 层使用 @ControllerAdvice 统一处理异常，返回友好的错误 JSON。

六、选择 outputType 还是 outputSchema？

| 场景

|

推荐方式

|

原因

标准业务对象（联系人、订单）

| outputType |

类型安全，维护成本低

| |

复杂嵌套对象

| outputType |

自动生成完整 Schema

| |

需要自定义字段描述

|

outputSchema

|

可精细控制每个字段

| |

快速原型开发

| outputType |

只需定义 POJO

| |

无法定义 Java 类型（纯动态 JSON）

|

outputSchema

|

灵活

|

结论：绝大多数情况使用 outputType 即可。

七、总结

  • 结构化输出

    ：让 Agent 按固定 JSON 格式返回数据，方便程序化消费。

  • 两种方式

    ：outputType（推荐）和 outputSchema。

  • 核心机制

    ：BeanOutputConverter 自动生成 JSON Schema 并注入到提示中。

  • 异常处理

    ：务必捕获 GraphRunnerException，确保应用健壮性。

  • 测试验证

    ：通过 REST API 直观验证结构化输出效果。

通过本文，你已经掌握了如何在 Spring AI Alibaba 中使用结构化输出，并能够应用到实际项目中，提升 Agent 与业务系统的集成效率。

参考资源：

  • Structured Output 官方文档

  • Spring AI Alibaba GitHub

  • DashScope API 文档