🎯 今日核心问题
- 工具返回
OrderView的 JSON 还是返回一句人话,模型后续表现差在哪? - JSON 里塞了 40 个字段,模型会不会反而漏读关键字段?怎么裁剪?
- 怎么在一次返回里同时兼顾"机器可读"和"模型好懂",又不多花一倍 token?
- 为什么工具返回 null、空列表、"操作成功"这种字符串是 Agent 事故的高发区?
📖 精读提纲
【一】两种返回值的真实差异
结构化返回(JSON)的优势是可稳定解析、可被程序二次利用、字段语义清晰;劣势是冗长,尤其嵌套深层对象时模型容易只看顶层。自然语言返回的优势是模型理解成本低、能直接抄进答案;劣势是不可解析、歧义多、无法在代码里做断言。实践结论是默认结构化,但对模型加一层"摘要字段":顶层给 ok、summary 这类人话,深层给精确数据。这样既保留可编程性,又降低模型漏读关键信息的概率。不要二选一,要做分层。
【二】三条硬规则
规则一:返回体必须有统一外壳。所有工具都返回 {ok, code, message, data} 四段式,模型只需要学一次结构,就能判断"这次成功没有"。没有外壳时,模型经常把异常文本当正常数据用。规则二:只返回与当前任务相关的字段。数据库实体 40 列,工具视图就 6 列;宁可多写一个 OrderDetailView,也不要把 Order 实体直接扔给模型——里面往往还有 createdBy、version、deleted 这种纯噪音,还可能泄露内部字段。规则三:控制体积。列表类工具必须有 limit 与 total,单次返回不超过 20 条,超了就提示模型"结果已截断,请细化查询条件"。上下文窗口不是无限的,一次返回 200 条就能把后面所有推理空间挤掉。
【三】实战应用:Spring Boot 场景
推荐分层:Repository 返回实体 → Service 内的 View 转换器返回 *View → 工具方法把 View 包进 ToolResult 外壳。转换层是刻意冗余的,它就是 Agent 的防腐层:实体改字段不会连带改 Agent 行为。序列化用统一的 ObjectMapper,配置 WRITE_DATES_AS_TIMESTAMPS=false(否则模型看到 1761820800000 完全无法推理日期)。对金额统一输出"元 + 两位小数字符串",避免模型自己算浮点;对状态输出中文枚举而非 SHIPPED,或两者都给({"code":"SHIPPED","label":"已发货"}),模型抄 label、程序读 code。
【四】常见误区
- ❌ 成功返回实体、失败返回字符串——类型不一致,模型无法统一处理,解析端也会崩。
- ❌ 返回
"操作成功"却不带id——模型接着要调下一个工具时就断了,只能重查。 - ❌ 把堆栈信息
e.printStackTrace()的字符串返回给模型——既泄密又无意义,模型看不懂堆栈。 - ❌ 时间戳当日期返回——模型无法判断"还有几天到期"这类问题。
- ❌ 返回 null 表示"没找到"——模型会当成调用失败;应该返回
{"ok":true,"data":null,"message":"未找到该订单"}。
💻 代码示例
统一外壳 + 精简视图 + 截断提示,一次做全:
public record ToolResult<T>(boolean ok, String code, String message, T data) {
public static <T> ToolResult<T> ok(T data, String summary) {
return new ToolResult<>(true, "OK", summary, data);
}
public static ToolResult<Void> fail(String code, String message) {
return new ToolResult<>(false, code, message, null);
}
}
/** 给模型看的订单视图:6 个字段,日期是 ISO 字符串 */
public record OrderView(
String orderNo, String status, String statusLabel,
String shippedAt, String amountYuan,
boolean refundable, String refundReason,
String summary) { } // summary 是给人话层用的
@Component
@RequiredArgsConstructor
public class OrderTools {
private final OrderRepository repo;
private final ViewConverter conv;
@Tool("查询单笔订单状态、发货时间与是否可退款,当用户问某笔订单能否退货或何时到货时调用")
public ToolResult<OrderView> getOrderDetail(
@P("订单号,形如 A123 或 B20261027001") String orderNo) {
return repo.findByOrderNo(orderNo)
.map(conv::toView)
.map(v -> ToolResult.ok(v, "%s:%s,%s".formatted(v.orderNo(), v.statusLabel(),
v.refundable() ? "可退款" : "不可退款," + v.refundReason())))
.orElseGet(() -> ToolResult.fail("ORDER_NOT_FOUND",
"未找到订单 " + orderNo + ",请确认订单号是否正确"));
}
@Tool("按用户列出最近的订单,当用户问我有几笔订单/最近买了什么时调用")
public ToolResult<Paged<OrderBrief>> listUserOrders(
@P("用户ID,数字") Long userId,
@P("返回条数,1-20,默认5") Integer limit) {
int size = Math.min(limit == null ? 5 : limit, 20);
Page<Order> page = repo.findByUserId(userId, PageRequest.of(0, size + 1));
boolean truncated = page.getTotalElements() > size;
List<OrderBrief> items = page.getContent().stream().limit(size)
.map(conv::toBrief).toList();
String msg = truncated
? "共 " + page.getTotalElements() + " 笔,仅展示最近 " + size + " 笔,如需更早请缩小时间范围"
: "共 " + page.getTotalElements() + " 笔";
return ToolResult.ok(new Paged<>(items, page.getTotalElements(), truncated), msg);
}
}
@Component
public class ViewConverter {
public OrderView toView(Order o) {
return new OrderView(
o.getOrderNo(),
o.getStatus().name(),
o.getStatus().getLabel(),
o.getShippedAt() == null ? null : o.getShippedAt().toString(),
o.getAmount().setScale(2, RoundingMode.HALF_UP).toPlainString(),
o.isRefundable(),
o.isRefundable() ? null : o.refundReason(),
null);
}
}
@Configuration
class JacksonConfig {
@Bean
ObjectMapper toolObjectMapper() {
return JsonMapper.builder()
.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
.serializationInclusion(JsonInclude.Include.NON_NULL)
.build();
}
}
回填给模型时统一序列化成字符串,保证 tool 消息永远是一个合法 JSON:
String toolPayload = toolObjectMapper.writeValueAsString(result);
// tool 消息示例(模型实际收到的内容):
// {"ok":true,"code":"OK","message":"A123:已发货,不可退款,已超过7天无理由",
// "data":{"orderNo":"A123","status":"SHIPPED","statusLabel":"已发货",
// "shippedAt":"2026-10-20","amountYuan":"399.00",
// "refundable":false,"refundReason":"已超过7天无理由"}}
✏️ 今日动手
1)选一个你已有的工具,分别用"实体直返"和"ToolResult + View"两版跑同一组 10 个问题,记录 token 消耗(usage 字段)与答案正确率。通常会看到 token 下降 50% 以上而准确率上升。
2)构造"未找到"场景:查一个不存在的订单号,确认模型能正确回答"没有这笔订单"而不是编造一个状态。这是检验外壳设计是否有效的关键用例。
3)把 listUserOrders 的 limit 传 100,观察服务端是否被截到 20 并返回 truncated:true,再看模型会不会老老实实告诉你结果被截断了。
🔖 明日预告
外壳和视图都设计好了,但现实是:模型会传错参数、外部接口会超时、数据库会返回空。明天专门处理失败——参数校验、超时控制、异常转译,以及"让模型自己重试"的正确姿势。