🎯 今日核心问题

  1. 工具返回 OrderView 的 JSON 还是返回一句人话,模型后续表现差在哪?
  2. JSON 里塞了 40 个字段,模型会不会反而漏读关键字段?怎么裁剪?
  3. 怎么在一次返回里同时兼顾"机器可读"和"模型好懂",又不多花一倍 token?
  4. 为什么工具返回 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。

【四】常见误区

💻 代码示例

统一外壳 + 精简视图 + 截断提示,一次做全:

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,再看模型会不会老老实实告诉你结果被截断了。

🔖 明日预告

外壳和视图都设计好了,但现实是:模型会传错参数、外部接口会超时、数据库会返回空。明天专门处理失败——参数校验、超时控制、异常转译,以及"让模型自己重试"的正确姿势。